⚡ Key Takeaways
- WordPress.org ranking is a two-factor system — text relevance from your readme, multiplied by quality signals like installs, ratings, and update freshness. Both have to be working for you
- Your readme is the only lever you fully control. Installs take time to accumulate. Ratings depend on users. But your readme can be optimized today — and most plugins leave enormous ranking power untouched
- The slug you choose at submission is permanent. It’s grouped with your title in the highest-weight ranking group. Most developers choose it for branding reasons without knowing it’s also their biggest SEO decision
- Competitor keyword research is where the real gains are. Understanding which keywords the plugin above you ranks for — and which ones they’ve left open — tells you exactly where to focus your optimization
- Ranking on WordPress.org is a compounding game. Every install makes the next install easier. Getting the text right early gives you the best possible foundation before quality signals start to accumulate
You submitted your plugin to WordPress.org. It got approved. You searched for your primary keyword and found your plugin on page four — or page eight — or not at all. You updated your readme, waited a few days, searched again. Still buried.
Most plugin developers hit this wall and assume the directory is a black box where established plugins with thousands of installs permanently own the top spots, and there’s nothing a newer plugin can do about it. That’s not quite right. The algorithm is documented in WordPress.org’s open-source code. It has specific rules, specific fields it cares about, and specific behaviors that reward the developers who understand it — and quietly ignore the ones who don’t.
This is the practical guide to ranking your plugin on WordPress.org — what the algorithm actually measures, where most developers leave ranking power on the table, and what to do about it in the right order.
What the Algorithm Actually Measures
Before optimizing anything, it helps to understand the two distinct things WordPress.org search cares about — because they require completely different actions.
Text Relevance
How well do your plugin’s text fields match the search query? This is determined entirely by your readme — the title, slug, short description, tags, and full description. It’s the only factor you can change today, with no dependency on users or time.
Quality Multiplier
Your text score gets multiplied by a quality score built from active installs, ratings, resolved support threads, and how recently you updated. These compound over time — and they compound against you if you neglect them.
The relationship between these two factors matters. Text relevance gets you into contention. Quality keeps you there and pushes you higher. A brand new plugin with a perfectly optimized readme can absolutely outrank an older plugin with a neglected one — but only if the older plugin’s quality signals have also decayed. For keywords where the top results have hundreds of thousands of installs, text optimization alone won’t close the gap. For keywords where the top results are in the low thousands, it absolutely can.
This is why keyword selection is part of the ranking strategy — not just keyword optimization.
New plugins start with zero installs, zero ratings, and zero support history. The algorithm applies sensible defaults for missing data so you’re not penalized to zero — but you are starting at a disadvantage on quality signals. The way to compensate is to get the text relevance side as close to perfect as possible from day one, so every install you earn compounds on a strong foundation rather than a weak one.
The Ranking Roadmap: What to Do and In What Order
- 1
Choose the right keywords before you write a word
The biggest ranking mistake plugin developers make happens before the readme is even written — targeting keywords they can’t win. Single generic terms like “seo,” “backup,” or “forms” are registered WordPress.org tags. When someone searches an exact tag, the algorithm bypasses text relevance entirely and returns results sorted purely by active installs. A new plugin with 50 installs cannot compete there regardless of how good the readme is.
The sweet spot is three and four-word descriptive phrases — specific enough to go through keyword scoring rather than tag matching, long enough for phrase matching to give you an advantage, and specific enough that the competition is realistic. “Automatic image optimizer” beats “image optimizer.” “Contact form builder” beats “forms.” Think about what a developer or site owner would type when they know what they need but haven’t decided on a plugin yet.
Before writing your readme: identify three to five target phrases, check whether any of them are registered WordPress.org tags, and verify that the top results for those phrases have install counts in a range you can realistically approach over the next six to twelve months.
- 2
Choose your slug carefully — it’s permanent
The plugin slug is the URL identifier that becomes your WordPress.org address — and it’s grouped directly with your title in the highest-weight ranking group. A keyword match in your slug carries the same boost as a keyword match in your title. Most developers choose their slug for branding reasons before they’ve done any keyword research, then discover later that it’s also their most important SEO decision.
The slug cannot be changed after your plugin is accepted without creating an entirely new listing and losing all your existing install count and reviews. This makes it the highest-stakes, most irreversible SEO decision in your plugin’s entire lifecycle.
If you haven’t submitted yet: include your primary keyword phrase in the slug.
your-brand-contact-form-builderoutranksyour-brand-formsfor the phrase “contact form builder” — significantly, because the slug group is the highest-weighted group in the entire algorithm. Note that WordPress.org guidelines prohibit generic terms like “plugin” or “WordPress” and any trademarked names in your slug. - 3
Optimize your title for phrase match, not branding
Your plugin title is the single most powerful text field in the algorithm. It appears in three separate scoring groups — more than any other field. A plugin whose title contains the exact search query as a phrase gets the maximum boost from the highest-weight group. No other field achieves this.
The practical implication: if someone searches “contact form builder” and your title is “YourBrand Contact Form Builder,” you score at the top of the highest-weight group. If your title is “YourBrand Forms — Build Contact Forms Easily,” you still score in this group but at a lower match level. The difference in ranking output is significant and it happens every single time someone searches that phrase.
The rule: your primary keyword phrase belongs in your title, in that word order, as early as possible. Branding comes after the keyword, not before it — or at least not between words in the phrase. And like slugs, WordPress.org guidelines prohibit the word “plugin,” “WordPress,” and trademarked names in plugin titles.
- 4
Write your short description as a keyword statement
The short description — the 150-character summary that appears in search results and at the top of your readme — scores in the second-highest group alongside your tags. Most developers treat it as a marketing tagline. It needs to do both: communicate your value proposition and place your primary keyword phrase where the algorithm gives it meaningful weight.
The algorithm looks for phrase matches in this field — meaning your primary keyword should appear as a coherent phrase, ideally at or near the start of the sentence. A short description that opens with your keyword phrase scores a phrase match in a high-weight group. One that buries the keyword mid-sentence loses that advantage.
Write it last. Once you know your exact keyword targets and have optimized your title and tags, write the short description to reinforce the same primary phrase while also giving a human visitor a reason to click.
- 5
Use all five tag slots for keyword phrases — not single words
Tags appear in the same scoring group as the short description and carry the same weight. The critical detail almost nobody knows: WordPress.org only indexes your first five tags. Everything after tag five is ignored entirely by the search algorithm.
The phrase matching behavior applies here too. “Contact form builder” as a tag scores a phrase match. “Contact,” “form,” and “builder” as three separate tags do not — they only contribute to the lower-weight word-match group. Five descriptive phrases that accurately represent what your plugin does, ordered with your most important keyword first, is the standard to optimize toward.
What to avoid: generic single words, competitor names, trademark terms, and filler tags that don’t represent specific search intent. WordPress.org’s review team will flag violations and your plugin can be closed for guideline breaches.
- 6
Write a full description that covers secondary keywords naturally
The full description is a medium-weight field that contributes to the word-match scoring group. It’s not where primary keyword battles are won — that happens in the title, slug, and short description. But it’s where you extend your reach to secondary keywords and long-tail variations that your primary fields don’t cover.
Write a genuinely useful description for conversion reasons first — this is what convinces a visitor to click Install. Then read it through the lens of secondary keywords: are there related phrases a user might search that appear naturally in your description? If not, work them in where they fit. Don’t keyword-stuff — the algorithm doesn’t reward density and the review team will notice.
- 7
Keep your plugin actively maintained
The quality multiplier includes an exponential decay function based on how long since your last update. The decay starts after 180 days and accelerates from there. A plugin last updated 18 months ago is scoring meaningfully lower than an identical plugin updated last month — regardless of readme quality.
The tested-up-to version carries a separate penalty. A plugin running several major WordPress versions behind the current release gets penalized on its compatibility signal. These two decay functions compound: a plugin that’s both old and behind on compatibility is getting hit simultaneously by both.
The maintenance rule: update your tested-up-to version every time WordPress releases a major version. Ship minor version bumps regularly even if they’re small. These actions cost almost nothing and prevent your quality score from silently eroding.
- 8
Understand what the plugin above you ranks for
Readme optimization gets you to the edge of what’s possible with text relevance alone. The next level is understanding the competitive landscape — specifically, which keywords the plugins ranking above you are targeting, and which ones they’ve left open.
Every plugin in the directory has a readme you can read. But reading readmes manually doesn’t tell you which keywords they actually rank for, at what positions, or which of those rankings are strong versus weak. That’s a data problem — and it’s where most plugin developers stop, because the data isn’t easy to get manually.
This is exactly what WhoKnew Directory SEO™ was built for. Enter any competitor’s slug and pull every keyword they rank for with live position data. The gap finder surfaces every keyword they rank for that you don’t target — scored by opportunity tier so you know which gaps are worth closing first.
The Mistakes That Keep Good Plugins Invisible
After going through this process with our own plugins and studying hundreds of readmes through the lens of the algorithm, the same patterns show up consistently in plugins that should be ranking but aren’t.
- Targeting single-word keywords that are registered tags. The algorithm skips text relevance entirely for exact tag matches and sorts by installs. A new plugin cannot win there. Three and four-word phrases are almost always the right starting point.
- Keyword in the description but not in the title. The title group carries three times the scoring coverage of the description group. A keyword that only appears in the description is doing a fraction of the ranking work it could do in the title.
- Five tags, all single words. Single-word tags only contribute to word matching in the lower-weight group. Phrase tags score phrase matches in the higher-weight group. The difference in ranking output is significant and the fix takes five minutes.
- Short description written as a tagline, not a keyword statement. “The fastest way to build beautiful forms” tells a human something. “Drag-and-drop form builder with conditional logic” tells a human the same thing and also scores a phrase match in a high-weight group for people searching “form builder.”
- Ignoring the freshness penalty. The decay is exponential and silent. Most developers don’t notice it until their rankings have already slipped significantly. A quarterly update habit prevents the compounding entirely.
- Never checking what competitors rank for. Optimizing your readme in isolation means you’re guessing at the right keywords. Knowing that the plugin above you ranks for twelve keywords you don’t target — and three of them have low competition — tells you exactly where to focus next.
Why Getting This Right Early Matters More Than You Think
The WordPress.org ranking system is compounding in both directions. A well-optimized readme on a new plugin starts accumulating installs faster than a poorly optimized one — and more installs means a higher quality multiplier, which means better rankings, which means more installs. The flywheel starts turning earlier and faster.
The reverse is also true. A plugin that launches with a weak readme, accumulates installs slowly, and lets its quality signals decay ends up in a worse position every month — not because anything actively went wrong, but because the compounding worked against it instead of for it.
Getting the text right before you have significant installs is the highest-leverage point in the entire ranking process. Once you have thousands of installs, the quality multiplier does a lot of the work for you. Before you have them, the readme is doing most of the heavy lifting — and most readmes aren’t pulling their weight.
Run a keyword scan on your primary target phrases and see where you actually rank right now. Without a baseline, every optimization decision is a guess. With one, you know exactly which fields are costing you positions — and which changes will move the needle first.
Making It Measurable
Every step in this guide produces a change you should be able to measure. Your keyword positions on WordPress.org are trackable. Your readme field coverage is scoreable. Your competitor’s keyword strategy is visible if you have the right tool.
That’s what WhoKnew Directory SEO™ was built to give you. Live keyword position tracking on WordPress.org, field-by-field readme scoring against the actual algorithm, competitor keyword spy that pulls every term the plugin above you ranks for, a gap finder that surfaces the opportunities they’ve left open, and an AI optimizer that generates a ready-to-paste rewrite prompt pre-loaded with your specific data. Everything runs inside your WordPress dashboard — no separate account, your data stored on your own server.
Most plugin developers optimize blind. The ones who rank well don’t.
Who knew the difference between page one and page eight was sitting in a readme file nobody had optimized?
