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 documentation

Plugin features:

  • Widget and Shortcode.
  • Display related posts as post thumbnails, links, excerpts or full posts.
  • Small Footprint. Doesn’t slow down your site!
  • Automatic display of related posts after the post content.
  • 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.
  • Use your own HTML templates for display of the related posts.
  • Use the WordPress REST API to get related posts. (opt-in feature)
  • Use a persistent cache layer for the related posts. (opt-in feature)
  • Use plugin functions in your theme templates to display related posts yourself.
  • Use Filters to change the default behavior of the plugin.
  • Extensive plugin documentation.
  • Highly Adjustable!
  • Follows WordPress coding standards and plugin best practices.

Follow this plugin on GitHub.

See the FAQ to have related posts automatically display after the post content without using the shortcode or widget.

Default usage for the shortcode is:


Attributes for the shortcode are:

  • post_id
  • taxonomies
  • post_types
  • posts_per_page
  • order
  • orderby
  • before_shortcode
  • after_shortcode
  • title
  • before_title
  • after_title
  • exclude_terms
  • include_terms
  • exclude_posts
  • format
  • image_size
  • columns
  • caption
  • link_caption
  • limit_posts
  • limit_year
  • limit_month
  • related

Example to show 10 related posts instead of the default 5.

[related_posts_by_tax posts_per_page="10"]

See the documentation for more information about these attributes.



  • The Widget
  • Twenty Fifteen screenshot. Related posts in the sidebar and after post content
  • Twenty Twelve screenshot. Post thumbnails (after post content) and the widget
  • Twenty Thirteen screenshot. Post thumbnails (after post content) and the widget


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


For more information about the plugin see the plugin documentation.
To customize this plugin see the plugin recipes page.

Installation Instructions
  • Unzip the folder.
  • Upload the related-posts-by-taxonomy folder to your /wp-content/plugins directory.
  • Activate Related Posts by Taxonomy.
  • That’s it, now you are ready to use the widget and shortcode
Can I change the layout for the related posts?

Yes. Review this section of the documentation to style the related posts yourself.

How can I automatically add related posts after the post content?

Review Adding Related Posts After the Post Content.

Can I include or exclude posts or terms with the widget or shortcode

Yes. For the widget see this filter and for the shortcode see the attributes exclude-terms, include_terms and exclude_posts.

Can I set my own defaults for the shortcode?

Yes. Review Setting your own defaults for the shortcode

The widget only lets you choose “all taxonomies” or a single taxonomy. Can I make it only use the taxonomies I want?

Yes. See this filter on how to do that.


Very good

Works very well and developer provides top-notch support! Helped me troubleshoot a style issue and went ahead in providing a CSS fix specific for my theme. 🙂

Customizable shortcodes

One of the most interesting plugin for related posts. Shortcodes are very customizable and the default appearance is nice.
I was looking for a plugin which let me set posts manually and this one doesn’t so I can’t use it but it’s very good.

A bit more thinking would not hurt.

The worst possible judgment was to hang it all on the tail of post content.
Do you have any idea how crowded it gets there?
It would be absolutely no big deal to provide an alternative hook, but who cares, right?

Read all 54 reviews

Contributors & Developers

“Related Posts by Taxonomy” is open source software. The following people have contributed to this plugin.


“Related Posts by Taxonomy” has been translated into 4 locales. Thank you to the translators for their contributions.

Translate “Related Posts by Taxonomy” into your language.

Interested in development?

Browse the code, check out the SVN repository, or subscribe to the development log by RSS.

Aldaketen loga


  • Enhancement
    • Add support to disable the shortcode or widget for this plugin
    • Add support to update all plugin settings with one filter.


  • Enhancement
    • Add a WordPress REST API layer to get related posts (opt-in feature)
    • Add new filter to activate the WordPress REST API layer


  • Enhancement
    • New option to link thumbnail captions (post titles) to posts in the widget and shortcode
    • Make the widget UI more intuitive
  • Bug fixes
    • Fix wrong results for cached custom post type related posts


  • Enhancement
    • Add selective refresh to the widget for the customizer
  • Bug fixes
    • Fix deprecated notice (by removing PHP4 style constructor) when installing this plugin with PHP7. Props: @dima-stefantsov


  • Enhancement
    • Refactor of the persistant cache for consistent results when using the plugin filters
    • Better data sanitation for taxonomies and comma separated values
    • New PHPunit tests (GitHub only)


  • Enhancement
    • Add Spanish, Catalan and Polish translation files
  • Bug fixes
    • Fix minor regression bug with the hide empty filter.
    • Fix minor bug where the wrong default post type was being used by the shortcode.


  • Enhancement
    • Optimised related posts query.
    • All round better validation of function arguments.
    • Persistent cache out of beta. Now fully functioning.
    • Cached data will be deleted after deleting the plugin from the wp-admin
    • New opt-in cache log in the toolbar.


  • Enhancement
    • New option for the widget to randomise the related posts.
    • Refactored the query to get the related posts.
    • Organized files in the new ‘includes’ directory.
    • Added a new class for debugging (only loaded if needed, with a filter).
    • New PHPUnit tests for the widget(GitHub only).
    • Updated the widget constructor as it is deprecated with WP 4.3
    • Added a new (beta) front end cache layer.


  • Bug fixes
    • Fixed a minor compatibility bug with the widget customizer. Settings were not saved properly when adding a new widget.


  • Enhancement
    • Using WordPress semantic versioning.
    • New shortcode attributes before_shortcode and after_shortcode.
    • Default h3 heading for the shortcode ‘Related Posts’ title
    • Shortcode is wrapped in a div container
    • New filter to add classes to gallery items.
    • New action after displaying related posts.
    • Better logic for the ‘related’ parameter.
  • Bug fixes
    • Applying ‘the_title’ filters for the shortcode caption.


Updated ‘include_terms’ logic to search for related posts with different taxonomy terms if ‘related’ is set.
Updated unit tests to be more reliable.


  • Enhancement

    • Added a new parameter ‘related’ to get posts with include_terms even if the current post doesn’t have the included terms (unrelated).
    • Used attribute aria-describedby in wp_get_attachment_image for accessibility (similar changes as in the WordPress 4.1 gallery).
    • Added new filters related_posts_by_taxonomy_post_thumbnail_link and related_posts_by_taxonomy_rss_post_thumbnail_link.
    • Removed extract() from all files (WordPress core best practices).
    • Added Phpunit tests (in the github repository).
  • Bug fixes

    • Fixed a filter recursion bug for the shortcode if it’s used in the WordPress the_content filter and the format is excerpts or posts.
  • Notice

    • Deprecated filters related_posts_by_taxonomy_post_thumbnail and related_posts_by_taxonomy_rss_post_thumbnail.


  • New filters for the related posts query.
  • Fixed minor bug when using spaces in post_types string in the short code.
  • Added plugin icons introduced with WordPress 4.0


  • Enhancement

    • New parameters for the shortcode and widget: include_terms and caption.
    • New support for html5 tags (set by themes) in the thumbnail gallery (same as in WordPress 3.9 gallery shortcode).
    • Allow image columns to be set to zero (same as in WordPress gallery shortcode).
    • New options for gallery captions. Use the post title (default), excerpt, attachment caption or attachment alt text for the caption.
    • Reformatted code and new inline filter documentation is added to adhere to new WordPress coding standards.
    • New filters for overriding images in the thumbnail gallery.
  • Bug fixes

    • Fixed bug where duplicate related posts where found for order=”RAND”. Props: Mock.
    • Fixed php notices coming from the Related_Posts_By_Taxonomy_Defaults class.
  • Notice

    • Removed backward compatibility for WordPress 3.4.
    • The template used for display of the post thumbnails is updated. Review the changes made in the updated related-posts-thumbnails.php file if you’re using it to display the thumbnails in your own theme.


  • Added image sizes and columns for the widget and shortcode.
  • Cleaned up of code base and speed improvements.
  • Added a Dutch translation.
  • Added a filter for the caption of post thumbnails.
  • Added two filters for a future settings page for this plugin. (this will be a separate plugin)


  • Added new feature to display related post thumbnails.
  • Removed the docs that came with the plugin.
  • some minor bug fixing for the shortcode.