=== Related Posts for WordPress ===
Contributors: never5, barrykooij
Donate link: https://www.barrykooij.com/donate/
Tags: related, inline related posts, similar posts, contextual relations, seo bounce rate, internal links
Requires at least: 6.8
Tested up to: 7.1
Stable tag: 3.0.0
License: GPLv3 or later
License URI: https://www.gnu.org/licenses/gpl-3.0.html
Requires PHP: 8.0

The best WordPress plugin for related posts. Simple, flexible, powerful algorithm, and built-in caching. Fully set up with only 1 click!

== Description ==

= Related Posts for WordPress =

Related Posts for WordPress offers you the ability to link related posts to each other with just 1 click!

Our installer will do all the hard work for you: simply activate the plugin, choose how many related posts every post gets and press Start. It runs in the background, so you can keep working while Related Posts for WordPress does the rest. Relating posts in WordPress has never been this easy!

Fully tested and working on PHP 8.0 and up (including PHP 8.1, 8.2, 8.3, 8.4 & 8.5) and WordPress 6.8 and up!

> #### Related Posts for WordPress Premium
> There's an even better version of this plugin that comes with the following extra features:<br />
>
> - Full Styling Control With Our Configurator<br />
> - Cross Custom Post Type Support<br />
> - Overwritable templates<br />
> - Custom Taxonomy Support<br />
> - Adjustable Weights<br />
> - Older posts get your new posts as related posts, right away and on a schedule<br />
> - See why posts are related<br />
> - WordPress Network / Multisite support<br />
> - Priority Email Support<br />
>
> [More information](https://www.relatedpostsforwp.com/features/?utm_source=wp-plugin-repo&utm_medium=link&utm_campaign=after-features-info-link) | [Upgrade >>](https://www.relatedpostsforwp.com/upgrade-premium/?utm_source=wp-plugin-repo&utm_medium=link&utm_campaign=after-features-purchase-link)

= Related Posts for WordPress won't lag your server! =
We believe having related posts shouldn't slow down your website. That's why Related Posts for WordPress keeps its own tables and does the heavy lifting in the background and when you publish a post. Showing related posts only reads the links stored for a post, offering you quality related posts while keeping your website fast!

= Automatically link posts to each other =
After activating the plugin, its settings screen offers to analyze your posts and link them to each other based on what we think is related. This runs in the background, which means you can install Related Posts for WordPress on your website that has thousands of posts and create related connections on the fly, without any manual work!

= Manually add, edit or remove =
Everyone makes mistakes, so do we. That's why you can easily modify all automatically created related posts. Simply navigate to the post that has incorrect related posts attached to it, select the correct related post and you're done. Related posts you add by hand keep their place when the plugin links your posts again.

= Shortcode =
Related Posts for WordPress has a related post shortcode allowing you to display related posts on any position within your content.

= Widget =
Related Posts for WordPress has a related post widget allowing you to display related posts in any sidebar you'd like.

**More information**

- Visit the [Related Posts for WordPress website](https://www.relatedpostsforwp.com/?utm_source=wp-plugin-repo&utm_medium=link&utm_campaign=more-information)
- Other [WordPress plugins](https://profiles.wordpress.org/barrykooij/) by [Barry Kooij](https://www.barrykooij.com/)
- Contact Barry on X: [@barry_kooij](https://x.com/barry_kooij)
- If you're a dev, follow or contribute to the [Related Posts for WordPress plugin on GitHub](https://github.com/barrykooij/related-posts-for-wp)


== Installation ==

= Installing the plugin =
1. In your WordPress admin panel, go to *Plugins > Add Plugin*, search for *Related Posts for WordPress* and click "Install now"
1. Alternatively, download the plugin and upload the contents of `related-posts-for-wp.zip` to your plugins directory, which usually is `/wp-content/plugins/`.
1. Activate the plugin

== Frequently Asked Questions ==

> #### Related Posts for WordPress Premium
> There's an even better version of this plugin that comes with the following extra features:<br />
>
> - Full Styling Control With Our Configurator<br />
> - Cross Custom Post Type Support<br />
> - Overwritable templates<br />
> - Custom Taxonomy Support<br />
> - Adjustable Weights<br />
> - Older posts get your new posts as related posts, right away and on a schedule<br />
> - See why posts are related<br />
> - WordPress Network / Multisite support<br />
> - Priority Email Support<br />
>
> [More information](https://www.relatedpostsforwp.com/features/?utm_source=wp-plugin-repo&utm_medium=link&utm_campaign=faq-info-link) | [Upgrade >>](https://www.relatedpostsforwp.com/upgrade-premium/?utm_source=wp-plugin-repo&utm_medium=link&utm_campaign=faq-purchase-link)

= Where's the settings screen? =
Settings > Related Posts.

= Can the displaying of excerpt be disabled? =
Yes, set the excerpt length to 0 in the Related Posts for WordPress settings screen.

= Can I use custom CSS? =
Yes, it's in the Related Posts for WordPress settings screen. To change only the space between the posts or the width of the images, set the CSS custom properties `--rp4wp-gap` and `--rp4wp-image-width` in your theme, for example `.rp4wp-related-posts { --rp4wp-gap: 2rem; --rp4wp-image-width: 25%; }`.

= Can the automatically outputted CSS be disabled? =
Yes, clear the CSS field in the Related Posts for WordPress settings screen, or use the `rp4wp_disable_css` filter: `add_filter( 'rp4wp_disable_css', '__return_true' );`.

= Is there a theme function so I can output this list anywhere in my theme I want? =
Yes, you can use `rp4wp_children();`.<br />
[More information on the theme function can be found here](https://www.relatedpostsforwp.com/documentation/theme-functions-to-display-related-posts/?utm_source=wp-plugin-repo&utm_medium=link&utm_campaign=faq-item).

= Is there a shortcode? =
Yes. To display your related posts via a shortcode use: `[rp4wp]`

= Can I limit the amount of related posts in the shortcode? =
Yes. Use the limit attribute, for example `[rp4wp limit=1]` for one related post, and the offset attribute to skip the first ones, for example `[rp4wp limit=3 offset=3]` for the fourth to the sixth.

= Is there a widget? =
Yes there is!

= Does Related Posts for WordPress support WordPress Network / Multisite websites? =
No, the free version does not. [The premium version however does, get it here](https://www.relatedpostsforwp.com/checkout/?utm_source=wp-plugin-repo&utm_medium=link&utm_campaign=faq-item).

= How does Related Posts for WordPress find related posts? =
It keeps the 25 most telling words of every post: words that are in the post often and in few other posts, so a word that is in every post on your site says little. The words of the title count 5 times, and the categories, tags and posts a post links to count as well. Common words like "the" and "and" are ignored in the language of each post, in 57 languages. Posts that share the most telling words are related, the most related first. There is no minimum score, so a post gets as many related posts as you chose whenever enough posts share a word, a category, a tag or a link with it.

= Does Related Posts for WordPress use its own database tables? =
Yes. It keeps the words of your posts, how many posts each word is in, the links between posts and when each post was read and linked in tables of its own, and records its changes to them in one more. Showing related posts reads only the links, so it stays fast.

= What happens to my related posts when I update to 3.0? =
On the first request after the update, the links move to the new tables. Then every post is read again and linked again in the background, one post at a time. No post shows fewer related posts meanwhile, related posts you added by hand keep their place, and a notice says when it is done.

== Screenshots ==
1. After activating Related Posts for WordPress, the settings screen offers to link your existing content: choose how many related posts every post gets and press Start.
2. The installer runs in the background and shows how far it is. You can leave the page while it works.
3. That's it! The settings are on the same screen, in the style of WordPress.
4. A new meta box is added to your post edit screens allowing you to link related posts, we will sort them on what we think is related (where top is most related).
5. Related posts are automatically added below your posts!

== Changelog ==

= 3.0.0: October 11, 2026 =
* Feature: A new settings screen, with the installer built in. The installer runs in the background, so the page can be closed while it works, and the screen shows its progress.
* Feature: The settings screen has a sidebar again, with links to the documentation and the support forum, and what Premium adds.
* Feature: Link the posts that are not linked yet, or rebuild every link, from the new Installer tab. Rebuilding asks first, and keeps the related posts you added by hand (2.x removed them).
* Feature: A modern default layout for the related posts, built with flexbox instead of floats. It works for right-to-left languages without a separate stylesheet, and themes can change the spacing and the image width with the CSS custom properties --rp4wp-gap and --rp4wp-image-width. Sites that changed the CSS, or style the related posts in the Additional CSS of the Customizer, keep their CSS as it is; the CSS field has a "Restore default" button to switch.
* Feature: Related posts shown by the shortcode or the widget outside single posts, on pages and archives for example, get the CSS too.
* Feature: The rp4wp_disable_css filter turns the CSS off, as in Premium.
* Feature: Related Posts for WordPress Premium 3.0 is an add-on for this plugin: keep both installed and active. Next to Premium 2.x, this plugin leaves the related posts to Premium and asks to update it.
* Feature: Better related posts. The words of a post count by how often they are in it and how rare they are on your site, and posts are compared as a whole, so words that are in every post decide little and long posts are recommended as often as short ones. Every post keeps its 25 most telling words (it was 6).
* Feature: Categories, tags and the posts a post links to count when finding related posts: the words of their names, and the category, tag or linked post itself. A category with most posts in it counts for little.
* Feature: The ignored words follow the language of each post, from WPML or Polylang or from the words of the post, with the ignored words of 57 languages. Posts in Chinese, Japanese and Korean get related posts, and accented letters match their plain form.
* Feature: After the update, every post is read again and linked again in the background, one post at a time. No post shows fewer related posts meanwhile, related posts you added by hand keep their place, and a notice shows how far it is and when it is done.
* Tweak: A word of the title counts 5 times (it was 80), a tag 5 (10) and a category 10 (20), so the content of a post counts too.
* Tweak: A post published while the installer or the update runs is linked when it is done, with the words of every post in place.
* Tweak: The links and the marks on posts move from posts and post meta to tables of their own, which makes showing related posts faster. The update moves them, and wp rp4wp migrate shows and undoes the changes to the database.
* Tweak: The filters rp4wp_get_related_posts_sql, rp4wp_get_children_link_args and rp4wp_get_parents_link_args are removed; rp4wp_finder_clauses and rp4wp_links_query take their place.
* Tweak: Related posts you add by hand are marked as such, so the refresh of Premium keeps them, also on a site that gets Premium later.
* Fix: The words of a post are removed when it is deleted or unpublished, also from WP-CLI and cron.
* Fix: Words with 4-byte letters are stored, and HTML entities no longer count as words.
* Fix: The rp4wp_after_link_add and rp4wp_after_link_delete actions fire for every link, also when posts are linked in batches or a post is removed.
* Fix: Related posts with the same link order keep the order they were added in, so a limit or an offset in the shortcode always shows the same posts.
* Fix: The related posts meta box skips links to posts that no longer exist.
* Fix: The installer no longer keeps waiting on posts without words or with emoji.
* Fix: PHP 8 deprecation notices, and word extraction no longer changes the locale of the rest of the request.
* Fix: Deleting the plugin with "Remove data on uninstall" on also removes the widget settings, the state of an unfinished installation wizard, the dismissed review notice and the chosen number of links per page.
* Tweak: Titles, settings and links in the admin are escaped.
* Tweak: The notices about mbstring and the unfinished installation wizard can be translated.
* Tweak: The bundled Dutch, French, German, Italian, Portuguese (Brazil and Portugal), Serbian, Swedish and Ukrainian translations are updated for 3.0, the new settings screen included.
* Tweak: The translations that come with the plugin are used first, so they are complete for this version; a language pack from translate.wordpress.org only adds strings they lack.
* Feature: New translations in Bulgarian, Czech, Dutch (formal), German (formal), Japanese, Norwegian (Bokmål), Polish, Russian, Spanish (Spain) and Turkish.
* Tweak: The Settings link on the Plugins screen also shows when the plugin folder is renamed.
* Tweak: Rewritten on a modern, tested code base. The classes of 2.x and RP4WP() still work, and report their use as deprecated when WP_DEBUG is on.
* Tweak: The installation wizard is replaced by the installer on the settings screen; links to the wizard open it there.
* Tweak: The notice about an unfinished installation shows its progress, and can only be dismissed with a link that is valid for you.
* Tweak: Requires WordPress 6.8 or newer and PHP 8.0 or newer.

= 2.3.1: September 23, 2026 =
* Security: Fixed an SQL injection in bulk linking that could be abused by users with the Contributor role or higher.
* Security: Users can now only add, remove or reorder related posts on posts they are allowed to edit.
* Security: The installation wizard can now only be run by administrators.
* Fix: Fixed a fatal error in the multisite notice on PHP 8.
* Tweak: Tested up to WordPress 7.1.

= 2.3.0: May 10th, 2025 =
* Feature: Added support for an offset in the [rp4wp] shortcode.

= 2.2.5: November 28, 2024 =
* Tweak: Load translation in init hook, fixes debug notice.

= 2.2.4: September 27, 2024 =
* Tweak: Added $rp4wp_post variable to rp4wp_post_title_html_values filter.
* Tweak: Removed PHP 5.2 classmap autoloading support.

= 2.2.3: April 16, 2024 =
* Tweak: Adding empty string instead of null in add_submenu_page, fixes PHP 8.1 warnings.

= 2.2.2: March 11, 2024 =
* Tweak: Fixed a WPCLI issue where HTTP_HOST notices were logged.
* Tweak: Added nonces and nonce checks to link adding in admin screen. Fixes CVE-2024-0592, props Krzysztof Zając.
* Tweak: Various fixes and improvements.

= 2.2.1: October 5, 2023 =
* Tweak: Playground links need to be opened in a new tab.

= 2.2.0: October 5, 2023 =
* Tweak: Updated & improved stop words list for en_US.
* Tweak: Corrected ahref detection in linking process.
* Tweak: Multiple word-processing improvements.
* Tweak: Skipping the default category in the linking process.
* Tweak: Added a WP Playground check.

= 2.1.4: March 27, 2023 =
* Tweak: Added rp4wp_post_title_html_values filter.
* Tweak: Moved rp4wp_after_content action to after closing of li (this was the designed position, it was placed incorrectly inside of li)

= 2.1.3: October 13, 2022 =
* Tweak: Fixed CWE-79 XSS issue on related posts settings screen, props [Juampa Rodríguez](https://github.com/und3sc0n0c1d0).

= 2.1.2: October 1, 2022 =
* Tweak: Fixed CWE-79 XSS issue on manually link related post screen, props [foobar7](https://github.com/foobar7).
* Tweak: Properly escape redirect URL params on manually bulk linking of related posts.
* Tweak: Properly escape links in post table on manually link related post screen.
* Tweak: Properly escape rp4wp_view on manually link search page.

= 2.1.1: September 17, 2022 =
* Tweak: Added rp4wp_post_title_html filter.
* Tweak: Added rp4wp_post_link filter.
* Tweak: Added rp4wp_before_content action.
* Tweak: Added rp4wp_after_content action.
* Tweak: Added rp4wp_before_image action.
* Tweak: Added rp4wp_after_image action.
* Tweak: Related posts output is now using an output buffer instead of 1 big variable concat.
* Tweak: Fixed grabber backend asset path.

= 2.1.0: September 12, 2022 =
* Feature: Added compatibility support for Yoast Duplicate Post plugin.
* Tweak: meta data updates.
* Tweak: Various small improvements.

= 2.0.5: July 6, 2021 =
* Tweak: Fixed an XSS vulnerability in heading text option.
* Tweak: Fixed an XSS vulnerability in custom CSS option.

= 2.0.4: March 15, 2021 =
* Tweak: Fixed an XSS vulnerability with WPML language GET attribute.

= 2.0.3: March 2, 2018 =
* Tweak: Removed hard removal of non a-z0-9 characters because this removes all non-latin chars causing issues for non-latin languages. Instead we're now using a specific blacklist of characters that needs to be removed. Also moved this to convert_characters so we apply this blacklist also to title,taxonomy,etc.
* Tweak: Made case lowering of words in cache UTF-8 compatible, solving an issue with non-latin characters.
* Tweak: We no longer cache all words but only the top 6. This greatly improves performance of the caching task.
* Tweak: Added filter 'rp4wp_cache_word_amount' to filter amount of words added in cache (default=6).

= 2.0.2: October 10, 2017 =
* Tweak: Fixed an issue where sticky posts were always included in related posts.
* Tweak: Removed a post type check since post type is always post.

= 2.0.1: September 7, 2017 =
* Tweak: Plugin is now checking if required mbstring PHP extension is installed.
* Tweak: Improved handling of plugin when premium version is also activated.
* Tweak: Updated various translations.

= 2.0.0: December 16, 2016 =
* Feature: New related post is found for parents of posts that are put back to draft or deleted.
* Feature: Related post are now removed when a post is put back to draft or deleted.
* Feature: Improved Content Matching Score algorithm. Better related content result. Rerun wizard for better results.
* Tweak: Fixed issue with search queries with multiple words in manual post linking.
* Tweak: Added post dates to manual linking screen.
* Tweak: Fixed jQuery lib include for HTTPS websites.
* Tweak: Added rp4wp_settings_sections filter to settings.
* Tweak: Renamed 'Restart wizard' to 'Rebuild Linkage'.
* Tweak: Added rp4wp_supported_post_types filter to various places.
* Tweak: Added keys to settings to allow for more detailed filtering.
* Tweak: Language updates for: NL, DE, FR, IT, BR, PT, RS, SE, UA.

= 1.9.3: May 2, 2016 =
* Tweak: Fixed a bug that caused the search query to reset when navigating through pages on the manual linking page.
* Tweak: Fixed unescaped page request variable on manual linking page.

= 1.9.2: April 18, 2016 =
* Tweak: We're now ignoring all characters that are not letters or numbers from word cache.
* Tweak: Various performance optimizations, props [Danny van Kooten](https://github.com/dannyvankooten).
* Tweak: Fixed a nonce error in installer when user clicked 'Skip linking'.
* Tweak: Various translations updates.

= 1.9.1: September 10, 2015 =
* Tweak: Fixed the `Woah! It looks like something else tried to run the Related Posts for WordPress` error message when resuming the wizard via the installing notice.

= 1.9.0: June 29, 2015 =
* Feature: Add pagination to manual post link table.
* Feature: Added id attribute to [rp4wp] shortcode.
* Feature: Added limit attribute to [rp4wp] shortcode.
* Feature: Added Brazilian Portuguese commonly used words.
* Feature: Added Czech commonly used words.
* Feature: Added Bulgarian commonly used words.
* Feature: Added Russian commonly used words.
* Feature: Added Swedish commonly used words.
* Feature: Added Spanish commonly used words.
* Feature: Added Norwegian Bokmål commonly used words.
* Tweak: Now displaying amount of posts left to link in installer.
* Tweak: Weight must be > 0 and words must be array in order to start adding words.
* Tweak: Add Composer autoloading (PHP 5.2 compatible) instead of custom autoloader, props [Danny van Kooten](https://github.com/dannyvankooten).
* Tweak: Static loading of hooks instead of directory scan, props [Danny van Kooten](https://github.com/dannyvankooten).
* Tweak: Added filter: rp4wp_get_children_link_args in RP4WP_Post_Link_Manager:get_children().
* Tweak: Added filter: rp4wp_get_children_child_args in RP4WP_Post_Link_Manager:get_children().
* Tweak: Fixed an issue with encoding non ASCII characters.

= 1.8.2: April 20, 2015 =
* Escaped view filter URL when manually linking posts to prevent possible XSS.

= 1.8.1: January 3, 2015 =
* Fixed a bug where UTF-8 encoded characters were not correctly parsed.
* Introduced icon alternative for when iconv isn't installed on server.

= 1.8.0: December 30, 2014 =
* Now preventing double form submitting in settings screen.
* Added plugin version to enqueued scripts.
* Added nonce checks to installer AJAX requests.
* Check installer nonce every step of installer.
* Added 'show love' option.
* Added dynamic option filter.
* Added warning on setting screen when an option is filtered.
* Added 'rp4wp_post_title' filter to filter related post titles.
* Added 'view post' link in manual link screen.
* Made related Posts block title WPML string translatable.
* Added translations: French, Italian, Portuguese, Portuguese (Brazil), Swedish.
* Updated translations: Dutch, German, Serbian.

= 1.7.6: December 2, 2014 =
* Added 'rp4wp_post_excerpt' filter.
* Added RTL support.
* Fixed a scheduled post bug.

= 1.7.5: November 15, 2014 =
* Fixed a hardcoded database table bug.
* Display notice and don't load plugin on multisite.

= 1.7.4: November 12, 2014 =
* Fixed an UTF-8 - iconv bug.
* Remove shortcodes from the related posts excerpt.

= 1.7.3: November 10, 2014 =
* Fixed multisite/network compatibility.

= 1.7.2: October 27, 2014 =
* Fixed a bug where permission were checked to soon.
* Removed an unused query var.
* Updated Dutch, German, Serbian, Swedish.

= 1.7.1: October 17, 2014 =
* Fixed a bug with manually creating links.

= 1.7.0: October 14, 2014 =
* Major performance improvements for post link creation.
* Fixed a shortcode bug.
* Changed NONCE_REINSTALL constant to NONCE_INSTALL.
* Added nonce checks.

= 1.6.3: September 18, 2014 =
* Fixed an install bug.

= 1.6.2: September 17, 2014 =
* Fixed a WSOD caused by wp_created_nonce being called before init hook.
* Changed the way the plugin is bootstrapped.

= 1.6.1: September 13, 2014 =
* Fixed a bug that caused the manual post link table to be empty.
* Added checks to only do certain checks in admin.

= 1.6.0: September 12, 2014 =
* We're now replacing 'special' characters with their 'normal' equivalent.
* Save the wizard settings to options to improve defaults.
* Added a percentage to the progressbar to improve progress clarity.
* The wizard progress is now updated when returned to wizard.
* Various caching tweaks.
* Added utf8 charset to cache database table in installer.

= 1.5.0: September 5, 2014 =
* Added Related Posts widget.
* Changed 'Delete Post' label to 'Unlink Related Post'.
* Lowered amount of posts cached per request to increase feedback in wizard.
* Various small wizard tweaks.
* Added nonce check to wizard restart procedure.
* Fixed a plugin activation redirect bug.

= 1.4.1: August 29, 2014 =
* Added filter 'rp4wp_append_content' to allow disabling of related post append to content.
* Fixed various hook and filter class bugs.

= 1.4.0: August 24, 2014 =
* Created the possibility to restart the installation wizard. See settings page for this option.
* Added notice that allows resuming installation wizard that will be displayed if the installation wizard crashed.
* Only load frontend CSS on singles.
* Fixed a default image size bug, props [Robert Neu](https://github.com/robneu).
* Small default CSS tweaks, props [Jackie D'Elia](https://github.com/savvyjackie).
* Complete plugin is now translatable.
* Updated Dutch translation.
* Default values are now in site language, if available.
* Uninstall script now also deletes the caching table.
* Added 'settings' link to plugins links.

= 1.3.2: August 22, 2014 =
* Fixed a bug where ignored words where not properly loaded.

= 1.3.1: August 21, 2014 =
* Added an uninstall procedure, see settings panel.
* Added plugin icons (yay).

= 1.3.0 : August 18, 2014 =
* Added 'rp4wp_children' template function.
* Added shortcode [rp4wp]
* Added pot translation template file.
* Added Dutch translation.
* Added review request admin notice.

= 1.2.2 : August 16, 2014 =
* Solved a conflict with the NextGen plugin (apply_filters recursion on same filter kills underlying call).
* Excerpt length is now set in words instead of characters.
* Small default CSS tweaks.

= 1.2.1 : August 14, 2014 =
* Fixed a small CSS default rule.

= 1.2.0 : August 14, 2014 =
* Related Posts heading text is now a setting.
* Amount of words in excerpt is now a setting.
* Displaying images of related posts is now a setting.
* Frontend CSS is now editable via settings.
* Added 'rp4wp_heading' filter, allows filtering of complete related posts block heading.

= 1.1.0 : August 11, 2014 =
* Added settings screen.
* Added to option to automatically link related posts on new posts, enabled by default.
* Added 'rp4wp_ignored_words' filter.
* Added 'rp4wp_thumbnail_size' filter.
* Added missing ABSPATH checks.

= 1.0.0 : August 7, 2014 =
* Initial version
