Jetpack
Support Home > Appearance > Customize Related Posts

Customize Related Posts

Like the other Jetpack modules, the Related Posts module includes filters allowing you to customize the look of the Related Posts to fit all your needs.

The code snippets below provide examples of some of the filters included in the module. You can add these code snippets to a functionality plugin, or to your theme’s functions.php file.

You can also check Jetpack’s source code to discover more filters.

Change the number of Related Posts displayed under your posts

By default, The Related Posts section will include at most 3 posts. You can change this number thanks to the jetpack_relatedposts_filter_options filter, like so:

function jetpackme_more_related_posts( $options ) {
	$options['size'] = 6;
	return $options;
}
add_filter( 'jetpack_relatedposts_filter_options', 'jetpackme_more_related_posts' );

Move the Related Posts to the top of your post content

By default, The Related Posts section will show up at the end of your post. You can change it to show above the post content thanks to the jetpack_relatedposts_filter_options filter, like so:

function jetpackme_move_related_posts_to_top( $options ) {
	$options['show_above_content'] = true;
	return $options;
}
add_filter( 'jetpack_relatedposts_filter_options', 'jetpackme_move_related_posts_to_top' );

Insert the Related Posts within your post content via a shortcode

You can use the [jetpack-related-posts] shortcode to insert the Related Posts in a custom location within your post content. Once you insert the shortcode, Related Posts won’t appear at the bottom of your posts.

Remove the Related Posts from the bottom of your posts

You can remove the Related Posts from your posts by adding the following code to your theme’s functions.php, or to a functionality plugin.

function jetpackme_remove_rp() {
    $jprp = Jetpack_RelatedPosts::init();
    $callback = array( $jprp, 'filter_add_target_to_dom' );
    remove_filter( 'the_content', $callback, 40 );
}
add_filter( 'wp', 'jetpackme_remove_rp', 20 );

You could then add Related Posts back to a specific post using the shortcode mentioned above, or by adding the shortcode directly into your template pages, thanks to the do_shortcode() function. To do so, simply add the following to your template, where you want Related Posts to be displayed:

<?php echo do_shortcode( '[jetpack-related-posts]' ); ?>

Change the “Related” headline at the top of the Related Posts section

In this example, we can change the default “Related” headline to “Check These Out!”:

function jetpackme_related_posts_headline( $headline ) {
$headline = sprintf(
			'<h3 class="jp-relatedposts-headline"><em>%s</em></h3>',
			esc_html( 'Check These Out!' )
			);
return $headline;
}
add_filter( 'jetpack_relatedposts_filter_headline', 'jetpackme_related_posts_headline' );

Replace one of the Related Posts by a custom result, for a specific post

In the following example we want to append post ID 1036 as the first related post result so we will just filter the returned ‘hits’ array:

function jetpackme_append_related_post( $hits, $post_id ) {
	// $post_id is the post we are currently getting related posts for
        if ( 2194 == $post_id ) {
    	    // Add 1036 to the front of the hits array
	    array_unshift( $hits, array( 'id' => 1036 ) );
            // Remove the last element of the array
            array_pop( $hits );
        }

	return $hits;
}
add_filter( 'jetpack_relatedposts_filter_hits', 'jetpackme_append_related_post', 20, 2 );

Exclude a specific post from ever appearing among Related Posts results

In the following example, 1037 and 1038 are the IDs of the posts we want to exclude:

function jetpackme_exclude_related_post( $exclude_post_ids, $post_id ) {
	// $post_id is the post we are currently getting related posts for
	$exclude_post_ids[] = 1037; // Exclude post_id 1037
	$exclude_post_ids[] = 1038; // Also exclude post_id 1038
	return $exclude_post_ids;
}
add_filter( 'jetpack_relatedposts_filter_exclude_post_ids', 'jetpackme_exclude_related_post', 2 );

Exclude an entire category from ever appearing among Related Posts results

Let’s say you have category named “Dogs” that you want to completely exclude from appearing among the returned Related Posts:

function jetpackme_filter_exclude_category( $filters ) {
    $filters[] = array( 'not' =>
      array( 'term' => array( 'category.slug' => 'dogs' ) )
    );
    return $filters;
}
add_filter( 'jetpack_relatedposts_filter_filters', 'jetpackme_filter_exclude_category' );

If you wish to eliminate uncategorized posts it’s a bit more complicated as the filters must exclude both posts marked as uncategorized as well as those without a category set at all. To do that use the following:

function jetpackme_filter_exclude_uncategorized( $filters ) {
    $filters[] = array( 'exists' =>
      array( 'field' => 'category.slug' )
    );
    $filters[] = array( 'not' =>
      array( 'term' => array( 'category.slug' => 'uncategorized' ) )
    );
    return $filters;
}
add_filter( 'jetpack_relatedposts_filter_filters', 'jetpackme_filter_exclude_uncategorized' );

Selectively disable Related Posts from appearing on specific posts

If you have specific posts you would like to not have Related Posts displayed on, you can use this snippet as a starting point.

function jetpackme_no_related_posts( $options ) {
    if ( is_single( array( 17, 19, 1, 11 ) ) ) {
    	$options['enabled'] = false;
    }
    return $options;
}
add_filter( 'jetpack_relatedposts_filter_options', 'jetpackme_no_related_posts' );

You can use a wide range of Conditional Tags in place of is_single. In the above example, 17, 19, 1, and 11 are the post IDs of the specific posts we want to remove Related Posts from being displayed. Those posts are still eligible to be displayed as Related Posts on other posts.

Include pages in search results for related content

Add the following to include pages in the Related Posts search, which would then display pages in the results that show up on each post.

function jetpackme_add_pages_to_related( $post_type, $post_id ) {
	if ( is_array( $post_type ) ) {
		$search_types = $post_type;
	} else {
		$search_types = array( $post_type );
	}

	// Add pages
	$search_types[] = 'page';
    return $search_types;
}
add_filter( 'jetpack_relatedposts_filter_post_type', 'jetpackme_add_pages_to_related', 10, 2 );

Do not add any context below each Related Post

By default, Related Posts include some context, as a quick explanation of why that post was chosen as a Related Post: it can be because it belongs to the same category, or because it shares the same tag.

You can remove that context thanks to this filter:

add_filter( 'jetpack_relatedposts_filter_post_context', '__return_empty_string' );

Use Related Posts with Custom Post Types

Related Posts will automatically work with your site’s Posts, but you can also use it with other Custom Post Types you might have, like Events, a Portfolio, or even Products. In order to get Related Posts to index and display on your Custom Post Types, you will need to add this function and filter:

function allow_my_post_types($allowed_post_types) {
	$allowed_post_types[] = 'your-post-type';
	return $allowed_post_types;
}
add_filter( 'rest_api_allowed_post_types', 'allow_my_post_types' );

Please note you will need to edit the code above and replace your-post-type with your Custom Post Type. We also do advise that you Reindex your site so that Jetpack will know of the new changes. You can Reindex your site by clicking Jetpack on your site’s Dashboard, and scrolling down and clicking the “Debug” link at the bottom of the page. From there you will have a “Reindex Posts” available. If you are not seeing the Related Posts show up right away with your Custom Post Types, try clearing your browser and site’s cache.

Add a default fallback image if no image can be found in a post

You can define a default image that will be used with all Related Posts that do not include an image in the post content. To do so, you can follow the instructions here.

Use Jetpack_RelatedPosts_Raw to build your own list of Related Posts

For the times when you’d like to build your own instance a Related Posts, you can use `Jetpack_RelatedPosts::init_raw()` to return a static instance of `Jetpack_RelatedPosts_Raw`. In the example below, we’ve created a shortcode returning a list of Related Posts.

function jetpackme_custom_related( $atts ) {
	$posts_titles = array();

	if ( class_exists( 'Jetpack_RelatedPosts' ) && method_exists( 'Jetpack_RelatedPosts', 'init_raw' ) ) {
		$related = Jetpack_RelatedPosts::init_raw()
			->set_query_name( 'jetpackme-shortcode' ) // Optional, name can be anything
			->get_for_post_id(
				get_the_ID(),
				array( 'size' => 3 )
			);

		if ( $related ) {
			foreach ( $related as $result ) {
				// Get the related post IDs
				$related_post = get_post( $result[ 'id' ] );
				// From there you can do just about anything. Here we get the post titles
				$posts_titles[] = $related_post->post_title;
			}
		}
	}

	// Return a list of post titles separated by commas
	return implode( ', ', $posts_titles );
}
// Create a [jprel] shortcode
add_shortcode( 'jprel', 'jetpackme_custom_related' );

Hide the post date on the Related Posts

If you’d like to hide the post date, you can use this CSS in your theme or in Jetpack’s Custom CSS module (in Appearance → Edit CSS):

.jp-relatedposts-post-date {
display: none;
}

If you have more questions about the Related Posts module, do not hesitate to send us an email!

Follow

Get every new post delivered to your Inbox.

Join 68,352 other followers