Related Posts by Taxonomy

Quickly increase your readers’ engagement by adding related posts in the sidebar or after post content with a widget or shortcode.

Posts with the most terms in common will display at the top!

This plugin is capable of finding related posts in multiple taxonomies and post types. Include or exclude terms from the search for related posts. Change the look and feel by using your own templates in your (child) theme.

Plugin features:

  • Widget and Shortcode
  • Post thumbnails, links, excerpts or full posts.
  • Small Footprint. Doesn’t slow down your site!
  • Object and persistent cache to get the related posts.
  • Search for related posts in single or multiple taxonomies and post types.
  • Exclude or include terms and posts.
  • Limit the search of related posts by date or number.
  • Automatic display of related posts after the post content.
  • Use your own Html templates for display of the related posts.
  • Use plugin functions in your theme templates to display related posts yourself.
  • Use Filters to change the default behavior of the plugin.
  • Highly Adjustable!
  • Follows WordPress coding standards and plugin best practices.

Download the plugin from the WordPress plugin repository: Related Posts by Taxonomy Plugin

For support visit the WordPress forums.

Visit the github repository for the development version.

The plugin documentation

Use the links below to navigate to a specific section in the documentation:

Note: It’s recommended you create a child theme whenever the documentation provides a way to modify the plugin by adding code to theme template files.

How to install the plugin

  1. Unzip the related-posts-by-taxonomy.zip folder.
  2. Upload the related-posts-by-taxonomy folder to your /wp-content/plugins directory.
  3. Activate Related Posts by Taxonomy.
  4. That’s it, now you are ready to use the widget and shortcode.

Widget

The widget settings are very self-explanatory.
widget settings

The display settings

You can choose from four different display formats:

  1. links: display a list of related post links
  2. posts: display a list of full posts
  3. excerpts: display a list of excerpts
  4. thumbnails: display a list of post thumbnails (version 0.2)

To override (edit) the templates used to display these formats see: Templates

For more information about the post ID and the widget outside the loop see Usage outside the loop.

To change the widget settings or display see the widget filters.

Shortcode

A shortcode is a WordPress-specific code to publish dynamic content using macros, without the need for programming skills. When a shortcode is inserted in a WordPress post or page editor, it is replaced with some other content.

Basic usage

[related_posts_by_tax]

This in your post content will be replaced with a list of related posts.

Shortcodes can also be used with additional attributes as the following example shows:

[related_posts_by_tax format="thumbnails" image_size="medium"]

This will be replaced by medium sized related thumbnails.

Note: To add the related posts automatically after the post content it’s recommended you use this method instead of the shortcode.

attributes:

All default attribute values can be filtered in your (child) theme’s functions.php file. This allows you to set your own defaults and more. See this Filter.

post_id
(int) Display related posts for a specific post ID. There is no default.
[related_posts_by_tax post_id="23"]
taxonomies
(string) Taxonomy name or a comma-separated list of taxonomy names. Default is ‘all’ (all taxonomies).
[related_posts_by_tax taxonomies="category,post_tag"]
post_types
(string) Post type name or a comma-separated list of post type names to search related posts in. Default none. The post type of the current post is used to get related posts for. If no post type is found it defaults to the ‘post’ post type.
[related_posts_by_tax post_types="post,movie"]
posts_per_page
(int) How many related posts to display. To display all related posts use -1. Default is 5.
[related_posts_by_tax posts_per_page="10"]
order
(string) Start searching for related posts from latest post date, oldest post date or randomly.

  • ‘DESC’ – from latest post date (show posts with most common terms first)(default).
  • ‘ASC’ – from oldest post date (show posts with most common terms first).
  • ‘RAND’ – random (show posts with terms in common randomly).
[related_posts_by_tax order="ASC"]
orderby
(string) Order by post date or by date modified.

  • ‘post_date’ – order by date (and show posts with most common terms first)(default).
  • ‘post_modified’ – order by last modified date (and show posts with most common terms first).
[related_posts_by_tax orderby="post_modified"]
before_shortcode (since 1.0)
(string) Text or Html to place before the shortcode.
Default is <div class="rpbt_shortcode">.
after_shortcode (since 1.0)
(string) Text or Html to place after the shortcode.
Default is </div>.
[related_posts_by_tax before_shortcode='<div>' after_shortcode='</div>' ]
title
(string) The title displayed above the related posts. Default is ‘Related Posts’. The title is removed if left empty.
[related_posts_by_tax title="My Related Posts"]
before_title
(string) Text or Html to place before the title. Since 1.0 the default is <h3>.
after_title
(string) Text or Html to place after the title. Since 1.0 the default is </h3>.
[related_posts_by_tax before_title='<h3 class="rpbt_title">' after_title="</h3>"]
exclude_terms
(string) Exclude a comma separated list of term IDs. This attribute cannot be used when including terms with the include_terms attribute below. Default is an empty string (don’t exclude terms).
[related_posts_by_tax exclude_terms="20,23,14"]

If you get unexpected results see the plugin’s logic for excluding terms.

include_terms (since 0.3)
(string) Search for related posts with the included term IDs. Use a comma separated list of term IDs. The current post must have at least one of the terms in common. This attribute overrides the exclude_terms attribute. Default is an empty string (don’t include terms).
[related_posts_by_tax include_terms="20,23,14"]

Set the attribute related below to false to search for posts with the included IDs even if the current post doesn’t have any of the term IDs.

[related_posts_by_tax include_terms="20,23,14" related="false"]

If you get unexpected results see the plugin’s logic for including terms.

[related_posts_by_tax related="false"]
exclude_posts
(string) Exclude a comma separated list of post IDs. Default is an empty string (don’t exclude posts).
[related_posts_by_tax exclude_posts="83,102,44"]
format
(string) Display related posts as links, full posts, excerpts or post thumbnails (version 0.2).

  • ‘links’ (default):
    • display a list of related post links.
    • template used for display: related-posts-links.php.
  • ‘posts’:
    • display post title and full post.
    • template used for display: related-posts-posts.php.
  • ‘excerpts’:
    • display post title and excerpt.
    • template used for display: related-posts-excerpts.php.
  • ‘thumbnails’ (since version 0.2):
    • display post thumbnails and post title as caption (same as the gallery shortcode).
    • template used for display: related-posts-thumbnails.php.

To override (edit) the templates used for display see Templates

[related_posts_by_tax format="thumbnails"]
image_size (since 0.2.1)
(string) Image size used for the format thumbnails (see above). Choose from the default image sizes thumbnail, medium, large, post-thumbnail and the image sizes set by the current theme. Default is ‘thumbnail’
[related_posts_by_tax image_size="medium" format="thumbnails"]
columns (since 0.2.1)
(string) Set the number of image columns for the format thumbnails (see above). Default is 3
[related_posts_by_tax columns="2" format="thumbnails"]
caption (since 0.3)
(string) Caption text for the post thumbnail. Choose from post_title, post_excerpt attachment_caption, attachment_alt, or a custom string. Default is ‘post_title’
[related_posts_by_tax caption="post_excerpt" format="thumbnails"]
limit_posts
(string) Limit the search for related posts to the latest published posts only. Default is ‘-1’ (search in all posts). Example: search for related posts in the last 100 posts.
[related_posts_by_tax limit_posts="100"]
limit_year
(string) Limit the search for related posts to posts published in the past year(s). Default is an empty string (no limit). Example: search only in posts published within the last year.
[related_posts_by_tax limit_year="1"]
limit_month
(string) Limit the search for related posts to posts published in the past month(s). Default is an empty string (no limit). Example: search only in posts published within the last 6 months.
[related_posts_by_tax limit_month="6"]

Adding Related Posts After the Post Content

Add related posts automatically after the post content by using a code snippet in your (child) theme’s functions.php file

Example with four related posts after the content on all single post pages.

Note: See below this code snippet how you can change it to suit your needs.

add_filter( 'the_content', 'add_related_posts_after_post_content' );
function add_related_posts_after_post_content( $content ) {

	//check if it's a single post page.
	if ( is_single() ) {

		// check if we're inside the main loop
		if ( in_the_loop() && is_main_query() ) {

			// add your own attributes here (between the brackets [ ... ])
			$shortcode = '[related_posts_by_tax posts_per_page="4"]';

			// add the shortcode after the content
			$content = $content . $shortcode;
		}
	}

	return $content;
}

Adding your own attributes to the code above
Add the attributes to the code snippet above as you would with the shortcode in the post editor. Let’s say you want to have the code snippet above show six medium sized related thumbnails. All you would have to do is change this:

$shortcode = '[related_posts_by_tax posts_per_page="4"]';

to this:

$shortcode = '[related_posts_by_tax posts_per_page="6" format="thumbnails" image_size="medium"]';

See the shortcode attributes you can add to the $shortcode variable.

Widget usage outside the loop

If the widget is used outside the loop (like in a sidebar) and no post ID is provided in the widget’s settings it gets the first post ID for that page request (e.g. on a category archive page it will get the post ID from the first post of that category archive page).

Custom queries with WP_Query()

To let the widget get the first post ID outside the loop on pages that query the main loop with new WP_Query you have to make some alterations after the query:

<?php // example query
$the_query = new WP_Query('cat=3');

// add this right after the query
// use the query object ($the_query) to check if posts are found
$the_query_id = ( isset( $the_query->post->ID ) ) ? $the_query->post->ID : 0;
set_query_var( 'km_rpbt_related_post_id', $the_query_id );
?>

39 thoughts on “Related Posts by Taxonomy

  1. This plugin is awesome, i tried a bunch of plugins without succeed, but this one is easy to use with great parameters, thank you so much

  2. Hi Keesie,

    great Plugin. I got one issue with it:

    i use photolux as theme and your plugin as widget on singlepage.
    settings are “thumbnail” and here is a problem. the thumbnail is set as image but the imagelink is to the page it self. photolux trys to show the thumbnail as image with lightbox and do not forward to the post.

    any suggestions?

    regards torsten

  3. A question. I would like to use the shortcode alone to place the posts (actually just the thumbnails but I got that part) related to a page on the page. But because it grabs from taxonomy the page doesn’t have a “category” or a “tag” and so I’m lost. Hints? Is this outside the bounds of what this plugin can do? Apologies if this is a basic question. Thank you.

  4. Hello!

    I really liked Your plug-in “Related Post by Taxonomy”
    But I ran into a problem: all miniatures of posts are built in one column. Unable to set, for example 4 or 8 columns. Or display of 5-6 thumbnails on each row.
    Have you encountered this problem? And whether it is possible to solve it somehow?

    Thank you very much, for your attention.
    Sincerely, Tony.

  5. Hi! Please help me, it is work in default taxonomy post, but not work not display in new my taxonomy portfolio, I used it code for register_taxonomy and register_post_type

    [[code removed]]

    and in file single-portolio.php used it code

    but not work, please help me, dear friend (

  6. I try this plugin with the code below to show related post after first paragraph, it works fine in single article but when trying to home page, there is only white page! I don’t know what happen?

    Does this plugin conflict with other plugins?

    [[code removed]]

    1. Hi vuongdaovan
      What happens if you put this:

      $related_posts= do_shortcode('[related_posts_by_tax title=""]');
      

      inside the is_single() conditional:

      if ( is_single() ) {
      $related_posts= do_shortcode('[related_posts_by_tax title=""]');
      return count_paragraph( $related_posts, 1, $content );
      }
      
  7. Dear,
    Let me introduce myself. My name is Borisa Djuraskovic. I am associated with Web Hosting Hub community team.

    I found your Related Posts by Taxonomy plugin at https://keesiemeijer.wordpress.com/related-posts-by-taxonomy/ very interesting. I would like to translate it to my native Serbo-Croatian language and help people from my community find your plugin useful too.
    Do you mind if I do so?
    Please let me know.

    Regards,
    Borisa Djuraskovic

    1. Hi Borisa Djuraskovic

      I would very much appreciate it🙂
      You can contact me here.
      https://keesiemeijer.wordpress.com/contact/

      If you’re not familiar with translating a plugin check out this tutorial. I have no problem if you’re using other tools to do the translation or want to send me the translation strings in a text file. But I’m guessing you already know how to do this.

      If you want I can add a link to your website next to the translation in the WordPress repository plugin page. Let me know in the contact form what the link should be.

      Thanks🙂

  8. What a fantastic plugin, so clean and light- thank you!

    I’m using it in the functions.php file of my child theme but the “Related Posts” text is unformatted. I’ve noticed that there is no css class applied to this heading. Is there a future-proof way to style the “Related Posts” text and the actual related posts wrapper itself?

    Thank you!

    1. Hi Tee

      See the examples for this filter how you can change the shortcode title.
      https://keesiemeijer.wordpress.com/related-posts-by-taxonomy/filters/#related_posts_by_taxonomy_shortcode_defaults

      The widget title before and after title is set by your theme. If you need to add to or change the html of the related posts you can do so by using your own templates:
      https://keesiemeijer.wordpress.com/related-posts-by-taxonomy/templates/

      Could you please open a topic in the WordPress forums if you have any more questions.
      http://wordpress.org/support/plugin/related-posts-by-taxonomy#postform

      1. I am working locally with wampserver. In fact this displays me the name of my Custom Post Types instead of the title.

  9. Hi Keesie,

    Fantastic plugin! I’m running a movie review website and this widget is really useful.
    However, I’m using two different images per post: the featured image and a custom field with an image as object (that is the DVD cover image). I’d like to use the secondary image file, instead of the automatically generated thumbnail that is based on the featured image, for the thumbnail view.

    Normally, I would use “$image = get_field(‘dvd_cover’);” and “$url = $image[‘url’];” to get the image vars, but how can I implement this in your plugin?

    Many thanks!

      1. Thanks for your quick reply. The difference with your example is that my posts do have thumbnails, but I want to use an image file that is uploaded in a custom field. I assume I need to use “wp_get_attachment_image()” for this, but I don’t know how to handle the parameters (I’m just getting into WordPress). The only thing I know is that the image is an object which is placed in the field ‘dvd_cover’.
        Are you able to help me with this?

  10. Thanks, your example works fine! The only thing is that it shows the attachment of the current post, not of the related post that it points to.
    Fixed it by adding $related it: get_field( ‘dvd_cover’, $related);

    Thank you for your help!

  11. Fantastic plugin! Doesn’t slow it down and it is easily styled. I do have one question though and I don’t really venture into php or java – is it possible to feature outside website posts as a “related” post – which would be fantastic for sites that feature guest posts from other blogs (returning the favor for being allowed to post such content is to highlight their other work etc).

  12. Great plugin – although I’m having one small issue.

    I’d like to display related posts based on a single tag – but this will be output onto a page using the shortcode.

    I’ve installed a plugin to add matching tags to pages, but setting [related_posts_by_tax format=”thumbnails” image_size=”medium” posts_per_page=”3″ order=”RAND” taxonomies=”post_tag”] and it just comes up blank.

    Is there a way I can specify which tag I want it to search for to pull the related content?

    Any ideas?

    Thanks in advance!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s