Support Home > Developers > Customize Related Posts

Customize Related Posts

Like Jetpack’s other features, Related Posts includes filters that allow you to customize the look of the related posts section to fit your needs.

The code snippets below provide examples of some of the filters included with Jetpack Related Posts. You can add these code snippets to a functionality plugin, or to your child theme’s functions.php file. You can also check out Jetpack’s source code to discover more filters in addition to those demonstrated below.

Generally, if the Related Posts block exposes controls for a setting, the filters below will not effect the output of the block. For example, changes made to the count or context will be ignored by any inline Related Posts content.

Note: These snippets are provided as a courtesy and our support team is unable to offer assistance customizing them further.

Change the number of Related Posts that display

By default, Jetpack’s Related Posts section will include up to 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' );

Show the author of the posts displayed as Related Posts

If you would like to display the post author’s (display) name, you can do so with the jetpack_relatedposts_filter_post_context filter, like so:

/**
 * Display the post author after the Related Posts context.
 *
 * @param string $context Context displayed below each related post.
 * @param string $post_id Post ID of the post for which we are retrieving Related Posts.
 *
 * @return string $context Context, including information about the post author.
 */
function jetpackme_related_authors( $context, $post_id ) {
	// Get the author ID.
	$post_author = get_post_field( 'post_author', $post_id );

	// Get the author's display name.
	$author_display_name = get_the_author_meta( 'display_name', $post_author );

	// Add the author name after the existing context.
	if ( isset( $author_display_name ) && ! empty( $author_display_name ) ) {
		return sprintf(
			__( '%1$s<span class="jp-relatedposts-post-author">By %2$s</span>', 'my-plugin-slug' ),
			$context,
			esc_html( $author_display_name )
		);
	}

	// Final fallback.
	return $context;
}
add_filter( 'jetpack_relatedposts_filter_post_context', 'jetpackme_related_authors', 10, 2 );

Insert Related Posts within your post content via a block

You can use the Related Posts Block to insert Related Posts in a custom location within your post content.

Remove Related Posts from the bottom of your posts

You can remove 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() {
	if ( class_exists( 'Jetpack_RelatedPosts' ) ) {
		$jprp = Jetpack_RelatedPosts::init();
		$callback = array( $jprp, 'filter_add_target_to_dom' );

		remove_filter( 'the_content', $callback, 40 );
	}
}
add_action( 'wp', 'jetpackme_remove_rp', 20 );

You could then add Related Posts back to a specific post using the [jetpack-related-posts] shortcode, or by adding this shortcode directly into your template pages, thanks to the do_shortcode() function. To do so, simply add the following to your template inside the loop where you want Related Posts to be displayed:

if ( class_exists( 'Jetpack_RelatedPosts' ) ) {
	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(
		'<p>
			<h3><em>%s</em></h3>
		</p>',
		esc_html( 'Check These Out!' )
	);

	return $headline;
}
add_filter( 'jetpack_relatedposts_filter_headline', 'jetpackme_related_posts_headline' );

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

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

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', 20, 2 );

Exclude sticky posts from appearing among Related Posts results

If you want to exclude sticky posts on your site from showing up under other posts, you can exclude it with this snippet of code:

function jetpackme_exclude_sticky( $exclude_post_ids, $post_id ) {
	$sticky = get_option( 'sticky_posts' );

	if ( ! is_array( $exclude_post_ids ) ) {
		$exclude_post_ids = array();
	}

	if ( is_array( $sticky ) ) {
		$exclude_post_ids = array_merge( $sticky, $exclude_post_ids );
	}

	return $exclude_post_ids;
}
add_filter( 'jetpack_relatedposts_filter_exclude_post_ids', 'jetpackme_exclude_sticky', 20, 2 );

Exclude an entire category from ever appearing among Related Posts results

Note: These category exclusion filters will remove the category from all related post results, regardless of other categories assigned to the post.

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

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 the default post category then it’s a bit more complicated as the filter 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' => '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 where we want to prevent Related Posts from being displayed. Those posts are still eligible to be displayed as Related Posts on other posts.

Display Related Posts on Pages as well

By default, Related Posts only appear at the bottom of your Posts. To display them at the bottom of your Pages as well, you can use the following filter:

function jetpackme_allow_pages_for_relatedposts( $enabled ) {
	if ( is_page() ) {
		$enabled = true;
	}

	return $enabled;
}
add_filter( 'jetpack_relatedposts_filter_enabled_for_request', 'jetpackme_allow_pages_for_relatedposts' );

Include pages in search results for related content

Add the following snippet to include pages in the Related Posts section, which would display alongside posts.

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 );

Selectively disable Related Posts from appearing on specific pages

If you have specific pages on which you do not want Related Posts displayed, you can use this snippet as a starting point.

function jetpackme_no_related_posts_onpages( $options ) {
    if ( is_page( 11 ) ) {
        $options['enabled'] = false;
    }
    return $options;
}
add_filter( 'jetpack_relatedposts_filter_options', 'jetpackme_no_related_posts_onpages' );

In the above example, `11` is the page ID of the specific page on which we do not want Related Posts to be displayed. Those pages are still eligible to be displayed as Related Posts on other pages.

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 jetpackme_allow_my_post_types( $allowed_post_types ) {
	$allowed_post_types[] = 'your-post-type';

	return $allowed_post_types;
}
add_filter( 'rest_api_allowed_post_types', 'jetpackme_allow_my_post_types' );

Please note that you will need to edit the code above and replace your-post-type with the slug of your custom post type. We also advise that you reindex your site so that Jetpack will be aware of this change. You can request a reindex of your site by clicking on the “initiate a sync manually” link at the bottom of this page. If you are not seeing 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 those times when you’d like to build your own instance of 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 that returns a list of Related Posts.

/**
 * Create a [jprel] shortcode.
 *
 * @param array $atts Shortcode attributes.
 */
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 );
}
add_shortcode( 'jprel', 'jetpackme_custom_related' );

Hide the post date on the Related Posts

The appearance of Related Posts can now be changed in the customizer, by going to Appearance → Customize → Related Posts and then viewing a single post.

Related Post Customize box

Do not add any context below each Related Post

By default, Related Posts include some context to explain why that post was chosen. It can be because it belongs to the same category, or because it shares the same tag.

You can remove that context via the customizer as shown in the screenshot above.

Remove Related Posts from WooCommerce Products

If you’d like to prevent Jetpack Related Posts from appearing on WooCommerce products (for example, because your theme already includes Related Products), you can use the following:

function jetpackme_exclude_jetpack_related_from_products( $options ) {
	if ( is_product() ) {
		$options['enabled'] = false;
	}

	return $options;
}
add_filter( 'jetpack_relatedposts_filter_options', 'jetpackme_exclude_jetpack_related_from_products' );

Filter Related Posts by Date

If you’d like to restrict related posts to a specific date range, you can use the following:

function jetpackme_related_posts_past_halfyear_only( $date_range ) {
	$date_range = array(
		'from' => strtotime( '-6 months' ),
		'to'   => time(),
	);

	return $date_range;
}
add_filter( 'jetpack_relatedposts_filter_date_range', 'jetpackme_related_posts_past_halfyear_only' );
  • Table Of Contents

  • Contact Us

    Need more help? Feel free to contact us.