⚡ Key Takeaways
- WordPress.org search runs a two-phase scoring system — text relevance first, then quality signals — and most plugin developers only think about one of them
- There are 7 text fields that directly affect your search ranking — but they are not weighted equally, and the gap between the most important and least important is enormous
- Your plugin title and slug carry the most ranking power of any text fields — by a significant margin — which is why getting keywords in the right places matters more than stuffing your description
- Tags are indexed — but only the first five — and most developers waste all five on generic terms that don’t help rankings
- Quality signals like active installs, rating, and how recently you updated your plugin multiply your text score — a well-optimized readme on a neglected plugin still loses to a weaker readme on an actively maintained one
Most WordPress plugin developers think about WordPress.org search the wrong way. They treat the plugin directory like a search engine where you sprinkle keywords into your description and hope for the best. That’s not how it works — and that misunderstanding is why so many genuinely good plugins are invisible while mediocre ones rank above them.
WordPress.org uses a specific, documented scoring algorithm. It has been reverse-engineered from the published source code, verified against live results, and it behaves in ways that are counterintuitive until you understand the underlying mechanics. Once you do, the path to better rankings becomes much clearer — because you stop guessing and start optimizing the things that actually move the needle.
This is a breakdown of that system: the seven text fields the algorithm actually indexes, how they’re weighted relative to each other, and what that means practically for how you should be writing your readme.
The Two Phases of WordPress.org Search Scoring
Before getting into the individual fields, it helps to understand the structure of the scoring system. WordPress.org search runs in two distinct phases, and both have to go well for your plugin to rank.
Text Relevance Score
How well do your plugin’s text fields match the search query? This is where the 7 indexed fields come in. Each field is weighted differently — some fields carry dramatically more influence than others. A keyword in your title is worth far more than the same keyword buried in your description.
Quality Multiplier
Your text relevance score doesn’t stand alone — it gets multiplied by a quality score built from active installs, ratings, resolved support threads, how recently you updated, and how current your tested-up-to version is. Quality multiplies relevance. A great readme on a dead plugin still loses.
The critical word in Phase 2 is multiply. It’s not additive — the quality signals don’t just add a few points to your score. They multiply the entire text relevance score up or down. A plugin that hasn’t been updated in two years, regardless of how well-optimized its readme is, takes a significant multiplier penalty. A plugin running well behind the current WordPress version takes another. These compound.
WordPress.org applies an exponential decay to your score based on how long ago you last updated your plugin. The decay starts after 180 days and continues from there — meaning a plugin updated 18 months ago is scoring meaningfully lower than an identical plugin updated last month, regardless of readme quality. Keeping your plugin current isn’t just good practice. It’s a ranking factor.
The 7 Fields WordPress.org Actually Indexes
Phase 1 scoring is built around multiple text field groups. Each group runs a match against the search query, and each group carries a boost. A field that appears in more groups — or in higher-weighted groups — contributes more to your final text score than a field that appears in only one. Here’s how the seven fields actually stack up.
Your plugin title is the single most powerful text field in the entire algorithm. It appears in three separate field groups — the title group, the phrase match group, and the content group — meaning a keyword match in your title is scored multiple times from different match types. No other field gets this treatment.
The practical implication is significant: a plugin whose title contains the exact search term will almost always outrank a plugin that only mentions the term in its description, even if the description is longer and more detailed. If there’s a primary keyword your plugin should rank for, it belongs in your title. Not hinted at — in the title, clearly.
What this means for you: Your plugin title is not just a name. It’s your most valuable ranking real estate. Don’t waste it on something clever that contains no searchable keywords.
The plugin slug — the URL identifier that becomes your WordPress.org address — is grouped directly with your title in the highest-weighted field group. It receives the same group boost as the title itself. Most developers choose their slug for branding reasons without considering that it’s also a significant ranking signal.
The slug is permanent once your plugin is accepted. You cannot change it without creating a new plugin listing. This makes it arguably the highest-stakes SEO decision you’ll make for your plugin — and it’s one most developers make before they know the algorithm exists.
What this means for you: If you haven’t submitted your plugin yet, your slug is a critical decision. Include your primary keyword. If you’re already live, this is why slug research matters so much for new plugins you’re planning.
The short description — the one-line summary that appears in search results and the first line of your readme — appears in two field groups: the phrase match group and the content group. This gives it significantly more scoring weight than the full description field.
Most developers treat the short description as a marketing tagline. It should also be a keyword statement. You have 150 characters. A well-written short description can do both — communicate your value proposition clearly while placing your most important keywords where the algorithm gives them meaningful weight.
What this means for you: The short description is your second-most optimizable field after the title. It’s also what visitors see in search results — so it needs to convert as well as rank. Write it last, once you know exactly which keywords you’re targeting.
Tags carry the same field weight as the short description — they appear in the same two groups with the same boost. The critical detail almost nobody knows: WordPress.org only indexes the first five tags you list. Everything after the fifth tag is ignored entirely by the search algorithm.
This is one of the most common optimization mistakes plugin developers make. Many plugins list ten or fifteen tags — generic ones like “plugin” or “WordPress” mixed in with actually useful keyword tags — and the algorithm is only reading the first five regardless. If your five most important keyword tags aren’t your first five tags, you’re wasting ranking potential.
What this means for you: You have exactly five tag slots that matter. Use them for specific, searchable keyword phrases that real users type when looking for a plugin like yours. Order matters — put your strongest tags first.
The full description — the main body of your readme — appears in the same two groups as the short description and tags, but with a reduced sub-boost applied. It has meaningful reach but less punch per keyword than the fields above it.
This surprises a lot of developers who spend hours perfecting their description while treating their title and tags as afterthoughts. The description is not your most powerful ranking field. It’s a supporting field — important for covering secondary keywords and long-tail phrases, but not where your primary keyword battles are won or lost.
What this means for you: Write a genuinely good description for conversion reasons — this is what convinces a visitor to install. For ranking, focus on covering secondary keywords and variations naturally throughout. Don’t keyword-stuff; the algorithm doesn’t reward it and the review team will notice.
The author field is indexed in its own group alongside contributors. It carries meaningful weight for brand searches — someone searching for your company name or username will be served results where your name appears in the author field. For keyword-based searches unrelated to your brand, it contributes less.
What this means for you: You can’t optimize this in a traditional sense — use your real author name. Its primary value is ensuring you rank for searches on your own brand name, which matters as your reputation grows.
Contributors are grouped with the author field and carry the same weight. For most single-developer plugins this field is identical to the author field. For plugins with multiple listed contributors, it adds additional name coverage in the same group.
What this means for you: Keep your contributors list accurate. Beyond that, this isn’t a field you can meaningfully optimize for keyword rankings.
The Quality Signals That Multiply Everything
Here’s where most readme optimization guides stop — and where the real story starts. Your text relevance score isn’t your final score. It gets multiplied by a quality score built from signals outside your readme entirely.
The three quality signals the algorithm uses are active installs, rating, and resolved support threads. Each is processed through a mathematical function that produces a multiplier. These multipliers are applied in sequence — they compound. A plugin that scores well on all three gets a significantly larger boost than one that scores well on only one.
There are also two decay functions layered on top: one for how recently your plugin was updated, one for how current your tested-up-to version is relative to the current WordPress release. Both use exponential decay — meaning the penalty grows slowly at first, then accelerates the further behind you fall.
A new plugin with zero installs and no ratings isn’t penalized as harshly as you might expect — the algorithm uses sensible defaults for missing data so new plugins can still surface. But a plugin that was once popular, has let its update cadence slip, and is running well behind the current WordPress version? That plugin is getting hit by multiple compounding penalties simultaneously, and no amount of readme optimization will fully compensate.
The practical upshot is that readme optimization and plugin quality are not separate concerns — they’re part of the same ranking system. Getting your fields right gets you into contention. Maintaining your plugin keeps you there.
What Most Plugin Developers Get Wrong
After looking at hundreds of plugin readmes through the lens of this algorithm, a few patterns show up consistently.
- Keyword in the description, not in the title. The title carries three times the group coverage of the description. A keyword buried in paragraph four of your description is doing a fraction of the work it would do in your title.
- Five tags — none of them specific. Generic tags like “widget,” “admin,” and “shortcode” tell the algorithm almost nothing useful. Five tags of actual keyword phrases that your target users search for is the standard to aim for.
- Short description written for humans, not for search. It needs to do both. The short description gets the same group weight as tags — and it’s the first thing a visitor reads in search results. It’s doing double duty and should be written accordingly.
- Ignoring the slug entirely. The slug gets grouped with the title. For plugins not yet submitted, this is the most underrated decision in the entire launch process.
- Optimizing text while neglecting freshness. Updating your plugin regularly — even minor version bumps — keeps the freshness decay from compounding. An updated tested-up-to version keeps the compatibility signal from penalizing you. These matter.
- Not knowing what competitors rank for. The algorithm scores your plugin against a query — but you can only optimize for queries you know about. Understanding which keywords competing plugins rank for, and which ones they don’t, is where real ranking opportunities hide.
Seeing Your Own Plugin Clearly
The honest challenge with all of this is that it’s impossible to optimize what you can’t measure. You can read this breakdown and have a solid conceptual understanding of the algorithm, but knowing that your title is your most powerful field doesn’t tell you whether your current title is actually ranking for anything — or what your competitors are ranking for that you aren’t.
That gap between knowing the rules and knowing your actual position is what WhoKnew Directory SEO™ was built to close. It tracks your live keyword positions on WordPress.org, scores your readme field by field against the algorithm, surfaces competitor keywords you aren’t targeting, and generates an AI prompt pre-loaded with your specific gaps so you can close them without guessing.
The algorithm is the same for everyone. What differs is whether you’re optimizing against it with real data or flying blind.
Before optimizing anything, the first question is: what keywords does your plugin actually rank for right now, and where do you rank for them? Without a baseline, every change you make is a guess. That baseline is where the work starts.
Who knew the difference between page one and page five was which five tags you put first?
