WordPress.org

Ready to get started?Download WordPress

Plugin Directory

Yet Another Related Posts Plugin (YARPP)

Display a list of related posts on your site based on a powerful unique algorithm. Earn money by including sponsored content!

Common Questions about YARPP Basic

Below are Frequently Asked Questions about YARPP basic. For questions about the new YARPP Pro enhancements, please visit the YARPP Pro FAQ.

If your question isn't here, ask your own question at the WordPress.org forums. We'd also appreciate if you would help us improve YARPP by answering a few survey questions. Thanks for your feedback!

Many pages list "no related posts."

Most likely you have "no related posts" right now because the default "match threshold" is too high. Here's what I recommend to find an appropriate match threshold: lower your match threshold in the YARPP "Relatedness" options to something very low, like 1. (If you don't see the match threshold, you may need to display the "Relatedness" options via the "Screen Options" tab at the top.) Most likely the really low threshold will pull up many posts that aren't actually related (false positives), so look at some of your posts' related posts and their match scores. This will help you find an appropriate threshold. You want it lower than what you have now, but high enough so it doesn't have many false positives.

How can I move the related posts display?

If you do not want to show the Related Posts display in its default position (right below the post content), first go to YARPP options and turn off the "automatically display" options in the "website" section. If you would like to instead display it in your sidebar and you have a widget-aware theme, YARPP provides a Related Posts widget which you can add under "Appearance" > "Widgets." (You can choose to display sidebar content from either YARPP Basic or YARPP Pro.)

If you would like to add the Related Posts display elsewhere, edit your relevant theme file (most likely something like single.php) and add the PHP code related_posts(); within The Loop where you want to display the related posts. (Make sure you don't add echo related_posts(); or you may end up with duplicates in your related posts section.)

How can I limit related posts to a certain time frame? For instance, I don't want to show posts from two years ago.

Yes. In WordPress, go to "Settings" and "Related Posts (YARPP)" and make sure "The Pool" is checked in the "Screen Options" section at the top of the page. In "The Pool" section, check the box next to "Show only posts from the past X months."

Where do I tell YARPP to display related posts only by tags?

In WordPress, go to "Settings" and "Related Posts (YARPP)" and make sure "Relatedness" is checked in the "Screen Options" section at the top of the page. In the "Relatedness" section, configure the dropdown boxes next to "Titles," "Bodies," "Categories," and "Tags."

Can I specify related posts?

Sorry, but specifying related posts, displaying related posts from external WordPress sites, and pulling content from the Comments section are all outside the scope of YARPP at this time.

I'm seeing related posts displayed on the home page. How do I prevent that?

Some WordPress themes treat the home page as an archive or a "page." Go to "Settings" then "Related Posts (YARPP)" and view the "Display Options" section. Make sure "Pages" and "Also display in archives" are not checked.

How can I prevent the "related posts" list from displaying on specific posts?

If you have several posts where you don't want to display related posts and they all share a similar category or tag, you could use "Disallow by Category" or "Disallow by Tag" in "The Pool" section. (Go to "Settings" and "Related Posts (YARPP)" and make sure "The Pool" is checked in the "Screen Options" section at the top of the page.)

You could also add <!--noyarpp--> to the HTML code of any post to prevent related posts from displaying. This solution will only work if you are using "Automatic Display" in the "Display Options" section. If you are programatically calling related_posts() from PHP code, you'll have to do your own checking to see if related posts are appropriate to display or not.

I'm using the Thumbnails display in YARPP 4. How do I override the style of the text that displays? The title only shows two lines, the font is larger than I'd like, I'd like to center the thumbnails, etc.

If you're familiar with CSS, you can override any YARPP styles by editing your theme's style.css file, or any other CSS file you may have created that loads after the YARPP one. To edit your theme's CSS file, go to "Appearance" then "Editor" and then click style.css in the right sidebar. Add changes at the bottom of the file and click "Save." If you do edit this file, just make sure you add !important after each style declaration, to make sure they'll override the YARPP rules.

Some common overrides that YARPP users have added are:

/* Reduces the title font size and displays more than two title lines */
.yarpp-thumbnail {height: 200px !important;}
.yarpp-thumbnail-title {font-size:0.8em !important; max-height: 4em !important}

/* Centers the thumbnail section */
.yarpp-related-widget {text-align:center !important;}

Once you save any CSS changes, empty your browser's cache and reload your page to see the effect.

I'm using the Thumbnails display. How can I change the thumbnail size?

The default YARPP thumbnail size is 120px by 120px. The thumbnail size can be specified programmatically by adding add_image_size('yarpp-thumbnail', $width, $height, true); to your theme's functions.php file with appropriate width and height variables. In the future I may add some UI to the settings to also set this. Feedback is requested on whether this is a good idea.

Each time you change YARPP's thumbnail dimensions like this, you will probably want to have WordPress regenerate appropriate sized thumbnails for all of your images. I highly recommend the Regenerate Thumbnails plugin for this purpose.

Please note that, by enabling the YARPP Pro enhancements, you can customize the thumbnail display using the admin interface instead of through PHP code.

I'm using the Thumbnails display. Why aren't the right size thumbnails being served?

By default, if an appropriately sized thumbnail is not available in WordPress, a larger image will be served and will be made to fit in the thumbnail space via CSS. Sometimes this means images will be scaled down in a weird way, so it is not ideal. What you really want is for YARPP to serve appropriately-sized thumbnails.

There are two options for doing so:

  • First, you can use the Regenerate Thumbnails plugin to generate all these thumbnail-sized images in a batch process. This puts you in control of when this resizing process happens on your server (which is good because it can be processor-intensive). New images which are uploaded to WordPress should automatically get the appropriate thumbnail generated when the image is uploaded.

  • Second, you can turn on a feature in YARPP to auto-generate appropriate size thumbnails on the fly, if they have not yet been created. Doing this type of processing on the fly does not scale well, so this feature is turned off by default. But if you run a smaller site with less traffic, it may work for you. Simply add define('YARPP_GENERATE_THUMBNAILS', true); to your theme's functions.php file.

I'm using the Thumbnails display. Why are some of my posts missing appropriate images?

YARPP's thumbnail view requires that a WordPress "featured image" be set for each post. If you have many posts that never had a featured image set, I recommend the plugin Auto Post Thumbnail, which will generate post thumbnails for you.

How can I use the custom template feature?

YARPP's custom templates feature allows you to uber-customize the related posts display using the same coding conventions and Template Tags as in WordPress themes. Custom templates must be in your active theme's main directory in order to be recognized by YARPP. If your theme did not ship with YARPP templates, move the files in the yarpp-templates directory which ships with YARPP into your active theme's main directory. Be sure to move the files (which must be named yarpp-template-....php) to your theme, not the entire directory.

Is YARPP compatible with WordPress Multisite?

YARPP should work fine in a multisite environment, and many users are running it without any issues using WordPress Multisite. It will, however, only get results within each blog. It will not display related posts results from across your network.

I want to use YARPP on a site with content in multiple languages.

The recommended solution in such cases is to use the Polylang plugin. Polylang has posted a tutorial for using YARPP with Polylang.

Does YARPP work with full-width characters or languages that don't use spaces between words?

YARPP works fine with full-width (double-byte) characters, assuming your WordPress database is set up with Unicode support. 99% of the time, if you're able to write blog posts with full-width characters and they're displayed correctly, YARPP will work on your blog.

However, YARPP does have difficulty with languages that don't place spaces between words (Chinese, Japanese, etc.). For these languages, the "consider body" and "consider titles" options in the "Relatedness options" may not be very helpful. Using only tags and categories may work better for these languages.

Does YARPP slow down my blog/server?

The YARPP calculation of related content does make a little impact, yes. However, YARPP caches all of its results, so any post's results need only be calculated once. YARPP's queries have been significantly optimized since version 3.5.

If you are running a large site and need to throttle YARPP's computation, try the official YARPP Experiments plugin which adds this throttling functionality. If you are looking for a hosting provider whose databases will not balk under YARPP, I personally have had great success with MediaTemple.

Are there any plugins that are incompatible with YARPP?

  • DISQUS: go to the DISQUS plugin advanced settings and turn on the "Check this if you have a problem with comment counts not showing on permalinks".
  • SEO_Pager plugin: turn off the automatic display option in SEO Pager and instead add the code manually.
  • Pagebar 2;
  • WP Contact Form III plugin and Contact Form Plugin;
  • WPML: various incompatibilities have been reported. The multilingual plugin Polylang has great support for YARPP and is suggested as a replacement for WPML.
  • Other related posts plugins, obviously, may also be incompatible.

Please submit similar bugs by starting a new thread on the WordPress.org forums. I check the forums regularly and will try to release a quick bugfix.

YARPP seems to be broken since I upgraded to WordPress X.X.

Before upgrading to a new WordPress version, you should first deactivate all plugins, then upgrade your WordPress, and then reactivate your plugins. Even then, you may still find that something went wrong with your YARPP functionality. If so, try these steps:

  1. Visit the "Related Posts (YARPP)" settings page to verify your settings.
  2. Deactivate YARPP, replace the YARPP files on the server with a fresh copy of the new version, and then reactivate it.
  3. Install the official YARPP Experiments plugin to flush the cache.

Can I clear my cache? Can I build up the cache manually?

The official YARPP Experiments plugin adds manual cache controls, letting you flush the cache and build it up manually.

I removed the YARPP plugin but I still see YARPP-related database tables. Shouldn't those be removed, too?

Beginning with version 4.0.7, YARPP includes clean uninstall functionality. If you no longer wish to use YARPP, first deactivate YARPP using the "Plugins" page in WordPress, then click the "Delete" link found on the same page. This process will automatically remove all YARPP-related files, including temp tables. If you manually try to remove YARPP files instead of going through WordPress, some files or temp tables could remain.

Does YARPP support custom post types?

Yes. To make YARPP support your custom post type, the attribute yarpp_support must be set to true on the custom post type when it is registered. It will then be available on options on the YARPP settings page.

'yarpp_support' => true

If you would like to programmatically control which post types are considered in an automatically-displayed related posts display, use the yarpp_map_post_types filter.

Can I customize how YARPP displays?

Yes. Developers can call YARPP's powerful relatedness algorithm from anywhere in their own code. Some examples and more details are in my slides from my WordCamp Birmingham talk.

yarpp_related(array(
    // Pool options: these determine the "pool" of entities which are considered
    'post_type' => array('post', 'page', ...),
    'show_pass_post' => false, // show password-protected posts
    'past_only' => false, // show only posts which were published before the reference post
    'exclude' => array(), // a list of term_taxonomy_ids. entities with any of these terms will be excluded from consideration.
    'recent' => false, // to limit to entries published recently, set to something like '15 day', '20 week', or '12 month'.
    // Relatedness options: these determine how "relatedness" is computed
    // Weights are used to construct the "match score" between candidates and the reference post
    'weight' => array(
        'body' => 1,
        'title' => 2, // larger weights mean this criteria will be weighted more heavily
        'tax' => array(
            'post_tag' => 1,
            ... // put any taxonomies you want to consider here with their weights
        )
    ),
    // Specify taxonomies and a number here to require that a certain number be shared:
    'require_tax' => array(
        'post_tag' => 1 // for example, this requires all results to have at least one 'post_tag' in common.
    ),
    // The threshold which must be met by the "match score"
    'threshold' => 5,

    // Display options:
    'template' => , // either the name of a file in your active theme or the boolean false to use the builtin template
    'limit' => 5, // maximum number of results
    'order' => 'score DESC'
),
$reference_ID, // second argument: (optional) the post ID. If not included, it will use the current post.
true); // third argument: (optional) true to echo the HTML block; false to return it

Options which are not specified will default to those specified in the YARPP settings page. Additionally, if you are using the built-in template rather than specifying a custom template file in template, the following arguments can be used to override the various parts of the builtin template: before_title, after_title, before_post, after_post, before_related, after_related, no_results, excerpt_length.

If you need to use related entries programmatically or to know whether they exist, you can use the functions yarpp_get_related( $args, $reference_ID ) and yarpp_related_exist( $args, $reference_ID ). yarpp_get_related returns an array of post objects, just like the WordPress function get_posts. yarpp_related_exist returns a boolean for whether any such related entries exist. For each function, $args takes the same arguments as those shown for yarpp_related above, except for the various display and template options.

Note that custom YARPP queries using the functions mentioned here are not cached in the built-in YARPP caching system. Thus, if you notice any performance hits, you may need to write your own code to cache the results.

Does YARPP support custom taxonomies?

Yes. Any taxonomy, including custom taxonomies, may be specified in the weight or require_tax arguments in a custom display as above. term_taxonomy_id specified in the exclude argument may be of any taxonomy.

If you would like to choose custom taxonomies to choose in the YARPP settings UI, either to exclude certain terms or to consider them in the relatedness formula via the UI, the taxonomy must (a) have either the show_ui or yarpp_support attribute set to true and (b) must apply to either the post types post or page or both.

Which languages does YARPP support?

YARPP is currently localized in the following languages:

Requires: 3.3 or higher
Compatible up to: 3.9.2
Last Updated: 2014-3-17
Downloads: 3,064,294

Ratings

3 stars
3.8 out of 5 stars

Support

9 of 50 support threads in the last two months have been resolved.

Got something to say? Need help?

Compatibility

+
=
Not enough data

1 person says it works.
0 people say it's broken.

100,1,1 50,4,2 100,3,3 100,1,1
50,2,1 86,14,12 100,3,3 100,1,1 100,1,1 100,1,1
88,16,14 100,1,1 100,1,1 100,1,1 100,1,1 100,1,1 100,2,2
100,2,2 100,1,1 33,3,1 92,12,11 100,1,1 100,5,5 100,1,1 100,1,1 100,1,1 100,1,1 100,1,1
70,23,16 100,1,1 100,1,1
100,3,3 100,4,4 100,8,8 70,10,7 90,21,19 67,6,4
67,3,2 53,19,10 52,21,11 100,1,1
80,45,36 100,1,1 0,1,0 50,2,1 0,1,0
100,1,1
83,6,5
86,7,6 100,1,1 0,1,0
100,1,1 67,3,2 0,1,0
80,5,4 73,11,8 70,10,7 60,10,6 100,1,1 100,1,1 100,2,2
100,12,12 100,1,1
78,9,7 100,1,1 100,1,1
100,6,6 100,1,1 70,10,7
67,3,2
86,14,12 50,2,1 100,1,1
86,7,6 42,24,10 68,22,15 25,4,1 33,3,1 100,5,5 0,1,0
100,2,2 25,8,2 22,9,2 100,10,10 71,14,10
86,22,19 50,4,2 68,25,17 100,1,1
70,20,14 100,1,1 0,1,0
100,6,6 100,1,1
81,21,17 100,10,10 100,2,2 100,1,1
100,4,4 89,9,8 100,1,1 93,14,13 100,4,4 78,9,7 100,3,3 100,2,2 80,5,4 67,3,2 100,3,3 100,1,1 100,1,1
100,7,7 77,13,10 100,1,1
89,9,8 80,10,8 91,11,10 78,18,14
63,8,5 100,1,1
100,12,12 0,1,0 100,1,1
86,7,6 83,6,5 100,1,1 86,7,6
100,1,1
85,13,11 0,4,0 100,2,2 100,1,1
100,1,1 100,5,5 100,3,3
75,8,6
100,2,2
100,1,1 100,1,1
67,3,2 100,1,1
0,1,0 0,1,0 89,9,8
0,2,0
100,1,1