How to write a WordPress.org plugin readme that ranks
Oct 28, 2026
Your readme.txt is your WordPress.org listing. The plugin page, the line under your name in search results, your tags and two of the six factors search multiplies your score by all come from it. A readme can’t make up for a weak plugin, but a careless one costs you searches you’d otherwise rank for. This guide goes through the readme from top to bottom: what each part becomes, what search reads, and what TrackWP’s Readme Checker looks for.
The header: small fields with big effects
The header is the block at the top of the file. Most of it looks like housekeeping, but several lines feed search directly.
=== Acme Booking Calendar ===
Contributors: yourusername
Tags: booking, calendar, appointments, reservations, scheduling
Requires at least: 6.5
Tested up to: 7.1
Stable tag: 2.4.0
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Take bookings on a calendar: customers pick a free slot, you get an email.
Plugin name. WordPress.org shows the name from the readme’s first line, and only falls back on the name in your main plugin file when the readme has none. Search weighs the name more than any other field, so it’s worth more thought than any other line here. How to choose a plugin name, short description and tags that search can find covers the name in detail.
Contributors. A comma-separated list of WordPress.org usernames, and only usernames: anything else won’t link to a profile. Search matches author and contributor names too, so people who search for you by name can find all your plugins.
Tags. One to five terms. WordPress.org’s plugin guidelines count more than five tags as spam, and tags no other plugin uses aren’t shown. How to choose tags for a WordPress.org plugin covers choosing them.
Tested up to. The latest WordPress version you’ve tested with, as numbers only. WordPress.org ignores minor versions, so 7.1 covers 7.1.3. This line is one of the six search factors: within one branch of the current WordPress you keep full score, and beyond that it falls. See What “Tested up to” does to your ranking.
Stable tag. The version WordPress.org serves. The directory works from this field, so it has to name a real folder in your SVN tags directory. Using trunk here isn’t supported for new plugins.
Requires at least and Requires PHP. These don’t change your score, but WordPress shows them before someone installs, and a plugin that won’t run on their site is a likely 1-star review.
The short description: 150 characters
The line right after the header is your short description. WordPress.org cuts it at 150 characters, so anything after that is lost. It’s the line under your name in search results, and search reads it as the excerpt, at the same boost as your description and tags.
Write it for a person deciding whether to click: what the plugin does and who it’s for, with the search you most want to rank for in it, or a second search your name can’t hold. The Readme Checker warns below 50 characters, because that leaves room unused, and above 150, because the end is cut off.
The description: the long answer
The == Description == section is the main body of your plugin page. Search reads it in the same group as the short description and tags, where the best-matching field sets the score, so it adds most for searches the shorter fields don’t cover.
The Readme Checker looks for three things:
- 300 words or more. Below 150 it fails. A short description of the features rarely uses all the words people search with.
- Your main search in the first 100 words. That’s where readers decide whether to keep going.
- The exact phrase at no more than 3% of the words. Above that it reads as stuffing. WordPress.org’s guidelines say readmes are to be written for people, not bots, and treat repeating a term as keyword stuffing.
A structure that works: one paragraph on what the plugin does and for whom; a list of the main features, each in the words a user would search with; a short section per main use case; then anything that helps someone choose, such as which other plugins or themes it works with. Name related products only where they’re true. The guidelines allow related products, not competitors, as tags, and the same honesty applies to the text.
The sections people look for
The Readme Checker checks that four sections exist and have something in them:
| Section | Missing counts as | Why it matters |
|---|---|---|
| FAQ | Fail | Answers questions before they become support threads |
| Screenshots | Fail | Shows what the plugin looks like before anyone installs it |
| Changelog | Fail | Shows the plugin is looked after |
| Installation | Warning | Helps people who install by uploading the zip |
FAQ. Each answer you write here is a support thread nobody has to open. Use the questions people actually ask in your support forum, in their words. That helps searches too, since people search with the same phrasing.
Screenshots. The images live in your SVN assets folder as screenshot-1.png, screenshot-2.png and so on, and the numbered list under == Screenshots == gives each one its caption, in order. TrackWP’s listing audit flags screenshots without captions, because a caption tells someone scanning the page what they’re looking at.
Changelog. WordPress.org recommends keeping the current release in the readme. TrackWP’s audit checks that the changelog starts with your current version: a changelog that stops two releases ago looks unmaintained even when the plugin isn’t.
Keep it under 10 KB
WordPress.org warns that a readme larger than 10 KB may cause errors. If yours is long, move old changelog entries to a changelog.txt file and link to it, and keep long tutorials on your own site.
Translations count too
A listing translated on translate.wordpress.org can rank in that language’s WordPress.org searches. TrackWP’s audit counts the languages with a finished translation of your listing and passes from five. You can’t translate everything yourself, but a line in your readme inviting translators helps, and native speakers among your users are often glad to.
Where the readme sets two search factors
Two of the six factors search multiplies your score by come straight from the readme and your release dates:
- Tested up to: full score within one branch of current WordPress. Updating the line is a readme edit, with no new code needed.
- Last release: full score for 180 days after your last release, then halving with every further 360 days. Any new version resets it.
The Readme Checker fails “Tested up to” as soon as it costs you score, and warns about the release from 150 days, a month before the factor starts to fall. The Decay Countdown shows the exact date for any plugin.
Check yours
The Readme Checker reads your published readme for any search and marks each check pass, warn or fail. Its score counts a pass as 1, a warning as ½ and a fail as 0, out of 100. For a plugin you track, TrackWP runs a fuller audit every day: the same checks plus translations, screenshot captions and whether the changelog is current, together worth 70% of the score, and where each of your tracked searches appears (name, short description, tags and the description’s first 100 words), worth 30%.
Fix the failures first, then make sure each search you care about is in the name or short description. Once the text is right, the order comes down to the six factors: How to rank higher in WordPress.org plugin search goes through each one.