This page is part of the plugin documentation for the Related Posts by Taxonomy plugin.

Plugin Templates

There are four templates used by the widget and shortcode to display the related posts. These templates can be found in the plugin folder ‘/templates’.

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

Editing Plugin Templates

You can override (edit) these templates with your own templates in two ways.
First, create a folder “related-post-plugin” in the root of your (child) theme folder.

The first method is by copying (not moving) the files you want to edit from the plugin ‘templates’ folder into your (child) theme’s ‘related-post-plugin’ folder. The widget and shortcode will now use the template in your (child) theme folder if the template exists.

The second method is by creating your own template in the “related-post-plugin” folder and filter the template used in your (child) theme’s functions.php file. This way you can also have separate templates for the widget and the shortcode.

Example of overriding the links template for the shortcode:

add_filter( 'related_posts_by_taxonomy_template', 'my_related_posts_templates', 10, 2 );

function my_related_posts_templates( $template, $type ) {

	// Shortcode templates
	if ( isset( $type ) && ( 'shortcode' === $type ) ) {
		// Return templates for shortcodes here.
		// Check what template the plugin wants to use.
		if ( $template === 'related-posts-links.php' ) { // the links template
			// Return your template file in themes/yourtheme/related-post-plugin/
			// Example for a file named my-shortcode-links-template.php
			return 'my-shortcode-links-template.php';
	// Widget templates
	if ( isset( $type ) && ( 'widget' === $type ) ) {	
		// Return templates for widgets here.
	// Return the default template as a fallback.
	return $template;

Create a new format for a template

In this example we’re going to create a new template that displays a post thumbnail and an excerpt. To let us use this template in the widget and shortcode we create a new format thumbnail_excerpt for it.

Note: This is an advanced topic as you need to style the display of this template (thumbnails/excerpt) yourself.

First, create a folder “related-post-plugin” in the root of your (child) theme folder. Copy the related-posts-excerpts.php file (found in this plugin’s /templates folder) and paste it in the related-post-plugin folder (in your theme). Rename the file to related-posts-thumbnail-excerpts.php.

Now we have to let the plugin know what template to use for the the thumbnail_excerpt format. Put this in your child theme’s functions.php

add_filter( 'related_posts_by_taxonomy_template', 'rpbt_thumbnail_exerpt_format_template', 10, 3 );

// Return the right template for the thumbnail_excerpt format
function rpbt_thumbnail_exerpt_format_template( $template, $type, $format ) {
	if ( isset( $format ) && ( 'thumbnail_excerpt' === $format ) ) {
		return 'related-posts-thumbnail-excerpts.php';
	return $template;

Let’s create the format itself so we can use it in a shortcode or widget. Put this in your child theme’s functions.php

// Create new format thumbnail_excerpt for use in widget and shortcode
add_action( 'wp_loaded', 'rpbt_thumbnail_excerpt_format', 11 );

function rpbt_thumbnail_excerpt_format() {

	if ( !class_exists( 'Related_Posts_By_Taxonomy_Defaults' ) ) {

	$defaults = Related_Posts_By_Taxonomy_Defaults::get_instance();

	// Add the new format .
	$defaults->formats['thumbnail_excerpt'] = __( 'Thumbnail with excerpt' );

With this done you can select the format in the widget. For shortcodes use it like you would normally use the format attribute

[related_posts_by_tax format="thumbnail_excerpt"]

Because we need the plugin to return only posts that have a post tumbnail for this new format we need to add in another step. Put this in your child theme’s functions.php.

// Return posts with post thumbnails for the thumbnail_excerpt format.
add_filter( 'related_posts_by_taxonomy_shortcode_atts', 'rpbt_thumbnail_exerpt_args' ); // shortcode
add_filter( 'related_posts_by_taxonomy_widget_args', 'rpbt_thumbnail_exerpt_args' ); // widget

function rpbt_thumbnail_exerpt_args( $args ) {
	if (  'thumbnail_excerpt' === $args['format'] ) {
		$args['post_thumbnail'] = true;

	return $args;

We’re ready to edit the new template related-posts-thumbnail-excerpts.php and add thumbnails to it. Here’s a very basic example. Add the HTML markup needed and style it in your (child) theme’s stylesheet to get the layout you’re after.

<?php if ( $related_posts ) : ?>

	<?php foreach ( $related_posts as $post ) :
		setup_postdata( $post );

	// Check if size was set in widget or shortcode
	$size = isset( $rpbt_args['size'] ) ? $size : 'thumbnail';

	 	<!-- post thumnail -->
		<?php if ( has_post_thumbnail() ) : ?>
			<a href="<?php the_permalink(); ?>"><?php the_post_thumbnail( $size ); ?></a>
		<?php endif; ?>

		<!-- title -->
		<a href="<?php the_permalink() ?>"><?php the_title(); ?></a>

		<!-- excerpt -->
		<?php the_excerpt(); ?>
	<?php endforeach; ?>

<?php else : ?>
<p><?php _e( 'No related posts found', 'related-posts-by-taxonomy' ); ?></p>
<?php endif ?>