⚡ Key Takeaways
- WordPress.org search is not Google — it uses a purpose-built algorithm that treats different types of queries completely differently depending on what the user types
- The directory distinguishes between three distinct query types — keyword searches, author searches, and tag searches — and each one triggers a different ranking path
- Short queries and long queries are scored differently. A two-word search behaves differently from a six-word search, and most devs optimize for the wrong one
- The algorithm gives heavy weight to exact phrase matches — a plugin whose title contains the exact search phrase will almost always outrank one that contains all the same words in a different order
- Understanding how search works doesn’t just help you rank — it tells you which keywords are actually worth targeting in the first place
There’s a common approach to WordPress.org SEO that goes something like this: find keywords, stuff them into your readme, hope the algorithm notices. It works occasionally — well enough that most developers never question whether it’s the right approach at all.
The problem is that WordPress.org search doesn’t work like Google. It’s not a general-purpose search engine trying to understand intent across the entire internet. It’s a purpose-built directory search with specific rules, specific query types, and specific behaviors that are documented in its open-source code. Once you understand how it actually works, the optimization decisions become obvious — because you stop guessing at a black box and start working with a known system.
This is a breakdown of how WordPress.org search actually processes a query from start to finish, and what that means for how you position your plugin.
It’s Not One Search. It’s Three Different Searches.
The first thing to understand about WordPress.org search is that it doesn’t treat all queries the same way. Before scoring anything, the algorithm classifies the incoming query into one of three types — and each type triggers a completely different ranking path.
Keyword Search
The most common type. A user types descriptive words about what they want — “contact form,” “image optimizer,” “automated backup.” The algorithm runs a full text relevance match across indexed fields, weighted by field importance and phrase structure.
Author Search
When the query matches a known WordPress.org username or author slug, the algorithm shifts into author mode — returning all plugins by that author sorted by active installs. Text relevance is bypassed entirely.
Tag Search
When the query exactly matches a tag in the directory’s tag taxonomy, the algorithm returns all plugins with that tag sorted by active installs. Again — text relevance is bypassed entirely. Only installs determine the order.
You Can’t Optimize Blind
If your target keyword is also a registered directory tag, some users will hit the tag path and see results sorted purely by installs — where a new plugin with no traction can’t compete, regardless of readme quality.
This three-path structure has a direct strategic implication. If you’re targeting a keyword that happens to be a registered WordPress.org tag — something like “backup” or “seo” or “forms” — some portion of users searching that term will see a tag-based result set sorted by install count. Your readme optimization does nothing for those users. The only lever you have there is installs.
For most plugin developers, this means choosing keywords that are descriptive phrases rather than single generic terms — “contact form builder” over “forms,” “automatic site backup” over “backup.” Longer phrases almost never match exact tags. They always go through the text relevance path where your readme can actually influence the result.
How Keyword Search Actually Scores Plugins
Once the algorithm confirms a query is a keyword search — not an author or tag match — it runs the query through a multi-group scoring system. Each group applies a different matching strategy against a different set of fields, and each group has a different weight multiplier.
The matching strategies run in order of specificity:
The highest-weighted group runs an exact and phrase match against your plugin title and slug combined. A plugin whose title contains the exact search query as a phrase gets the maximum boost from this group. This is why title optimization is so disproportionately important — it’s not just that the title is in a high-weight field. It’s that exact phrase matches in the title get scored against the highest boost multiplier in the entire system.
Note that WordPress.org guidelines prohibit using generic terms like “plugin,” “WordPress,” or trademarked names in your title or slug — so keyword optimization here means choosing the descriptive words that define what your tool actually does, not padding with prohibited terms.
What this means: 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 Beautiful Contact Forms Easily,” you still score in this group but at a lower match level. The difference in ranking output is significant.
The second group runs a phrase match against your short description and your first five tags. A phrase match means the algorithm is looking for your search query as a coherent phrase within those fields — not just the individual words scattered throughout. This is why tag order matters, and why your short description should open with your primary keyword phrase rather than burying it mid-sentence.
WordPress.org guidelines also restrict what you can put in tags — no competitor names, no trademarked terms, no generic filler. Your five tag slots should be specific descriptive phrases that accurately describe what your plugin does and that real users actually search for.
What this means: “contact form builder” as your first tag scores a phrase match. “Contact,” “form,” and “builder” as three separate tags do not — they only contribute to word matching in the lower-weight group. Phrase tags beat word tags every time.
The third group runs across all indexed fields — title, slug, short description, tags, full description — but using word matching rather than phrase matching. This means the algorithm checks whether all the words in the query appear somewhere in the fields, regardless of whether they appear together as a phrase. This group has a lower boost multiplier than the phrase-match groups above it.
What this means: Your full description primarily contributes here. It’s a supporting field that extends your reach to secondary and long-tail keywords. It doesn’t move the needle on your primary keyword the way your title and short description do.
The fourth group matches the query against author name and contributors. For keyword searches this group rarely contributes meaningfully — it mainly activates when someone searches your brand name or username. Its primary value is ensuring your own plugins surface when someone searches directly for you.
What this means: You can’t optimize this for generic keyword rankings. Use your real author name and keep contributors accurate. That’s the extent of it.
The final text relevance score is the sum of all group scores, each multiplied by its group boost. Then that combined score gets multiplied by the quality signals — active installs, rating, resolved support threads, update freshness, and tested-up-to version — to produce your final ranking position. As covered in the guide to the 7 fields WordPress.org actually indexes, those quality multipliers compound. Getting the text right puts you in contention. Maintaining the plugin keeps you there.
Why Word Order Changes Everything
One of the most underappreciated aspects of the WordPress.org search algorithm is how it treats phrase matching differently from word matching. Two plugins with identical words in their titles can score very differently depending on whether those words appear in the same order as the search query.
A user searches: “automated site backup”
- Plugin A title: “YourBrand Automated Site Backup” → scores a phrase match in the highest-weight group
- Plugin B title: “YourBrand Backup — Automated Protection for Your Site” → contains all three words but not as a phrase → drops to the lower-weight word-match group
- Plugin C title: “BackupMaster Pro” → no words match at all in the title → scores zero in the title group, relies entirely on description and tags
Plugin A wins the title group contest even if Plugin B has a better description and more tags. The phrase match in the highest-weight field dominates.
This is why “write naturally and keywords will take care of themselves” is bad advice for WordPress.org specifically. The algorithm rewards deliberate keyword placement in a specific field hierarchy, in phrase form, in the right order. Natural writing often doesn’t produce that. Deliberate optimization does.
Short Queries vs Long Queries
Query length affects how the algorithm scores results in a subtle but important way. Short queries — one or two words — are more likely to match directory tags exactly, which means some portion of users searching those terms will hit the tag path and never see your text relevance score at all.
Long queries — four or more words — almost never match exact tags. They always go through keyword search scoring. And because they’re longer phrases, the phrase-match boost applies to a more specific string — meaning a plugin whose content contains that exact longer phrase has a significant advantage over one that only contains the individual words.
The practical implication is that three-word and four-word keyword phrases are generally the best targets for new plugins. They’re specific enough to avoid the tag path, long enough for phrase matching to matter, and short enough that real users actually search them.
Single-word targets like “seo” or “security” or “forms” are dominated by plugins with hundreds of thousands of installs. The algorithm’s quality multiplier means these terms are nearly impossible to compete on without significant traction — regardless of readme quality. Targeting them early is a waste of optimization effort.
If a keyword is a registered WordPress.org tag and the top results have 500,000+ active installs, optimizing your readme for that keyword will not move you past them. Focus on three and four-word phrases where the competition is beatable and your readme work actually changes outcomes.
What This Means When You Sit Down to Optimize
Understanding the search mechanics translates into a fairly clear set of decisions when you’re actually working on your plugin page.
- Choose phrase targets, not word targets. “Automatic image optimizer” is a better target than “image optimizer” — it goes through keyword scoring instead of risking the tag path, and your readme can actually influence the result.
- Put your primary phrase in your title, in that word order. Phrase match in the title group is the single highest-scoring outcome in the algorithm. Rearranging words to sound better often costs you this boost entirely. Remember: WordPress.org prohibits generic terms like “plugin” or “WordPress” and any trademarked names in your title.
- Open your short description with your primary phrase. Phrase match in the short description group is the second-highest scoring outcome. The algorithm reads your short description as a string — front-loading your phrase maximizes the chance of a clean phrase match.
- Write your first tag as a descriptive phrase, not a single word. “Contact form builder” as a tag scores a phrase match. “Contact,” “form,” and “builder” as three separate tags do not — they only contribute to word matching in the lower-weight group. And keep tags accurate — WordPress.org prohibits competitor names and trademarks in tags.
- Use your slug as a keyword asset. The slug is grouped with the title in the highest-weight group. A slug like
contact-form-builderscores the same phrase match boost as having those words in your title. Most developers choose slugs for branding and leave this entirely on the table. - Understand which of your target keywords are tags. Before spending time optimizing a keyword, check whether it’s a registered directory tag. If it is, you’re competing on installs — not on readme quality — for users who search that exact term.
Knowing the Rules vs Playing the Game
There’s a gap between understanding how the algorithm works and actually knowing where you stand inside it. This breakdown tells you the rules. It doesn’t tell you which keywords your plugin currently ranks for, which ones your top competitors rank for that you don’t, or which of your readme fields are costing you phrase-match opportunities.
That’s a data problem. And it’s exactly what WhoKnew Directory SEO™ was built to solve. It tracks your live keyword positions on WordPress.org, scores your readme field by field, surfaces every keyword the plugin above you ranks for that you aren’t targeting, and generates a ready-to-paste AI prompt pre-loaded with your specific gaps to close them. Everything runs inside your WordPress dashboard — no separate account, your data on your own server.
Understanding the system is step one. Knowing exactly where you are inside it is step two.
Before changing anything in your readme, run a scan on your primary target keywords and see where you actually rank. The algorithm rewards specific changes in specific fields — knowing your current position tells you which changes are worth making first.
Who knew the algorithm was documented in the source code all along — and almost nobody had read it?
