The WordPress Plugin Directory is ground zero for nearly half of all website creators out there searching for that perfect plugin to improve their WordPress website. A typical Google search for a WordPress plugin brings you straight to a catchy listicle or right at the doorstep of WordPress.org itself.
Plugin Authors! You’ve got the power to shape almost everything on your plugin’s page, which is a major SEO boost for your freemium business.
Over the years, I’ve optimized quite a few plugins of my own, assisted fellow plugin authors, and seen how adopting certain practices significantly impacts your success with your free plugin listing.
So, I’ve put together this friendly guide for all my fellow WordPress plugin authors. It’s all about giving your plugin’s readme.txt a little TLC, focusing on what matters most to your users, and seeing those download numbers climb.
Goals for your Plugin README
Every time I approach a new readme optimization project, I try to be laser-focused on two primary goals:
It really comes down to making your plugin easy to find and clearly communicating its benefits. Without those, your plugin is like the tree falling in the forest with no one around to install it.
Mechanics of the Plugin README
I might write a whole post on this as well, but HOW you implement your updates and changes for your plugin readme is important as well. For now, most of it is covered by this doc in the Plugin Handbook.
Decoding the WordPress Plugin Directory Rankings
Think of the Plugin Directory’s search rankings as less of a mystery and more of an open book compared to Google’s complex algorithms. If you understand how it works, your plugin can rank well based on the content of your readme.
If you’re really interested in a deep dive on the Plugin Directory search algorithm, refer to the footnotes1 [1]. But the main three takeaways you should understand about the Plugin Directory search revolve around query matching, on-page optimization, and mitigating factors.
For the purposes of this article, it’s easiest to think of your plugin search results in terms of 3 aspects: Query matching, On-page optimization, and mitigating factors.
Query Matching
Understanding how users search for your plugin is the most important and significant factor to focus on. Your plugin can’t rank for a query you are not optimized for.
A “query” is the words people type into the search bar. For example, users very often need an SEO plugin. The query they use differs according to the context. In the WP Admin “Add New Plugins” screen, they probably just query “SEO”. But on Google, they might query “SEO WordPress plugin.” They probably often get a bit wordy too and query: “How do I get my WordPress site found on Google?” Those are very different types of queries, and yet I’m sure Yoast SEO wants to be top of the list for all of those results.
Deciding which keywords, phrases, or tags you need to be found with is foundational to your success. It’s about choosing the right words that your audience queries in the search bar, and ensuring you’re at the top of the results.
"Your plugin can't rank for a query you haven't optimized for. Understanding user intent and how your plugin can solve their problem is step one in optimizing your plugin for the WordPress Plugin Directory." Click To TweetSo deciding on which keywords or phrases or tags you need to be found with is foundational to your success.
On-page optimization
After identifying your target keywords, incorporate them across your readme’s title, headings, FAQ, and screenshot captions. Doing this right not only helps folks find you in the Plugin Directory but also in the big search engines. This step is what the rest of this guide is focused on.
Mitigating Factors
Some search ranking indicators you have more control over, but others you have less. It’s important to keep in mind that if you do every single thing I suggest in this article you will get as high as you possibly can in the plugin search results, but you most likely won’t be at the very top.
The biggest mitigating factor outside of your control is the active install count of other plugins that are optimizing for your same terms.
The other mitigating factors that you have some influence over, but not entirely, are ratings and recency of your latest version release. While effective reputation management is important for every product business, you don’t have (and shouldn’t have) complete control over your user ratings. But it’s important to keep in mind how significantly negative ratings can impact your freemium business.
While you do control the timing of every single release, you don’t want to be pushing out releases all the time just to get higher search results. Remember to focus on what you can influence, like keeping your plugin updated and being responsive to users’ needs.
The WordPress Plugin User Adoption Journey
I’ll be writing an in-depth post on this concept in the future, but for the purposes of this subject, understanding the intent and goals of your prospective plugin users is vital.
Your readme is your handshake, your first impression that can lead them from curiosity to clicking that install button. Here’s my take on the ideal or typical WordPress plugin user adoption journey.
The plugin readme’s focus helping move your potential user from the Awareness phase through to the Testing phase. In order to do that, your readme has to help you get found in the Searching phase, and be educational and helpful enough to move you into the Testing phase. That’s what all of this is trying to accomplish.
OK, with all of that in mind, let’s go step by step through optimizing your plugin readme for maximum visibility and adoption.
Step 1: Focus on the Query
Everything starts with user search intent. This very broad issue2 keeps marketers occupied continually and can seem overwhelming. Our task is focused just on those who are searching for a WordPress plugin.
Users searching for a WordPress plugin have a specific problem they are trying to solve for their website. From the Plugin Adoption Journey diagram above, this is the “Searching” phase. So, we need to focus on what term or phrase users will use when they are trying to solve the problem your plugin addresses.
User Intent: Are you solving their problem
All of your readme content should focus on how you solve the problem the user is querying. If your plugin name is “Event Tickets” and the user wants to sell tickets to events through their website, how can you leverage that query in your title, headings, tags, FAQ, and screenshot captions? But what if they want to “book rsvps”? “Event Tickets” also does that, so that’s a term you’ll want to leverage in your readme.txt as well.
Catering your content to user search intent gets tricky when your plugin serves multiple purposes. For example, it’s easy to call MailPoet an “email plugin”, but people need email for so many different reasons. When the user queries “email” they can find all sorts of tools. But what if they query “marketing automation” or “ecommerce receipts”? Email automations, transactional emails, newsletters, email marketing, registration and login emails… What problem do users have most often, and does MailPoet solve them?
Keyword Research tools
How do you know which terms people are actually using to query for the problems that your plugin solves? Where can you get the data to answer this question?
WordPress.org doesn’t share this data at all, which is a shame. And Google keeps their algorithm locked up tighter than Fort Knox. But, there are some tools that can provide insightful and meaningful search intent data.
Semrush Keyword Manager is the gold standard for me, with Moz’s Keyword Research Tool being the next best option (free with email registration). With these tools, you can enter your best guess at phrases your potential users might use to find your plugin, and the tool will show you how much volume there is for that query.
What I find particularly useful though are the related keywords and Semrush’s tags for intent.
Taking examples like Sunshine Photo Cart, and Picu, I entered “client photo gallery” into Semrush. It displayed a vast array of related terms and showed their volume and intent. I was surprised how the term “client photo gallery” by itself clearly has a lot of “commercial intent”2.
I highly recommend using these tools to find the phrases that best match the problem your plugin solves, and then order them by volume and intent. Here’s an example for Sunshine Photo Cart and Picu:
| Keyphrase | Monthly Volume | Commercial Intent |
|---|---|---|
| Client photo gallery | 3.1K | 64% |
| Image content management | 1.2K | 42% |
| Photo proofing | 190 | 67% |
Step 2: Apply Your Query to Your Title, Tags, Headings, and Screenshots
Now that you’ve identified your primary search intent terms, you need to narrow them down to 5️⃣ “tags”. In your plugin header, you can put tons of tags, but the first 5 are the only ones that will appear on your page, and they are the only ones that impact search.
The Plugin Handbook is really clear about the 5 tag limitation, and that you cannot use your competitors’ names as tags.
For GiveWP, we’ve tweaked our tags here and there, but over the years we’ve narrowed in on the following: crowdfunding, donate, donation, fundraising, recurring donations.
For Google search, you don’t have to focus so explicitly on synonyms or variations of the same term. For example, you’ll see we have both “donate” and “donation” in there. Google search is smart enough to know when you use “donation” it should consider content that has “donate” in it as well. The Plugin Directory search is not that smart, it relies very heavily on what’s called “exact match” terms.
This is why you see a lot of “keyword stuffing” on the Plugin Directory. For example, this:
This is bad form. It’s understandable because of the limitations of the Plugin Directory search, but remember our goals are two-fold: discoverability AND education. Users are smart, they’ll see through this tactic. What you gain in discoverability here you lose in adoption.
Our goals in on-page content optimization are also two-fold. We want your plugin page to be found high in the results of the Plugin Directory search (meaning on WordPress.org and in the WP Admin Plugins search), but also high in Google searches.
We focus on the plugin title and tags for the Plugin Directory search. But we also focus on leveraging those tags in headings, screenshot captions, and in your short description because that’s what Google cares about as well.3
Step 3: Focus on Your Content on Persuasive Education
Your plugin listings on WordPress.org are not the same as blog articles or landing pages. Despite the fact that WordPress.org does not use structured product data at all, Google interprets them as product pages. How do we know that? Because the search results show us.
Notice the star ratings, the “vote” counts, and the price as “Free”. This is product structured data results.
Optimizing your plugin page for product results is slightly different than blog content or pricing pages. Your goal is to be educational and persuasive. Remember, you did the hard work of being discovered by the search engines, now you have to convince this user that your plugin solves the problem they just queried for.
Many plugin authors attempt to do this by listing out all of their features with emojis and exclamation marks. I encourage you to mentally shift from writing about your plugin’s features and instead emphasize benefits.
For example, GiveWP has a lot of features to help you fundraise online. We could easily make a bullet list:
- PayPal and Stripe gateways!
- Custom form fields!!
- Powerful Reporting!!!
- A Donor Dashboard!!!!
Instead of that, we focus on the benefits, like this:
- Let your donors donate however they like, with credit cards, Apply Pay, Google Pay, Direct Deposit and more
- Get the right information at the point of donation to understand your donors better with custom donation form fields
- Show your nonprofit board how effective your donation campaigns are with gorgeous and flexible report dashboards
- Empower your donors to manage their recurring subscriptions, their name and email and physical address all from one donor dashboard
Leverage Your FAQs
The readme FAQ section is also powerful and useful content to leverage. You should focus on questions people have specifically about the features and benefits of your plugin that they might type into a search bar. Like “How do I accept Stripe or PayPal for donations on my website?”
This content is a great place to add additional key phrases you want to be found for but didn’t make it into the top five tags.
Step 4: Visually Showcasing Your Plugin (Creative Assets, Outbound Link, and Live Demo)
Nowadays, plugin users want to verify a plugin as much as possible before they install it on their website. They often understand the risks involved in activating plugins even though they somehow still don’t use live staging environments.
This means that visually or physically showcasing your plugin for them is a powerful and important way to educate them on how you solve their problem.
Here are several ways to showcase your plugin via your readme:
Use of Video
You can embed videos directly in your readme4. Video is a powerful, educational, and persuasive way to showcase the benefits of your plugin. It’s really the best chance you have to speak directly to your potential users in detail.
A big benefit of embedding Youtube or Vimeo videos in your readme is if you choose a video that is only shared on your readme, you can get actionable data on impressions and views of your readme. It’s a great way to have actionable data to help you watch for trends in your plugin listing visibility.
To add a video to your readme, all you have to do is paste the video URL onto it’s own line in your readme.
Outbound Links
Link to your product website throughout the readme. You control the entire experience of your website, and getting prospective users from .org to your website is a powerful way to start to de-anonymize who these visitors are.
Use outbound links to your site to point them to your best well-crafted online docs, or to custom landing pages just for them. You can add lead-gen forms on those pages, or live chat to engage with these users.
My biggest protip on outbound links is to ensure you are using UTMs5 to understand which links in your readme are getting clicked the most, and from what type of visitors.
Screenshots
Screenshots are another way to showcase your plugin. You can add as many screenshots as you like, but I would focus on the first 3 as the most important. Screenshots are presented as a carousel and are at the very bottom of the readme. But in the WP Admin they have a dedicated tab, so my assumption is that prospective users look at the first 3 or 4 screenshots.
My biggest advice with readme screenshots is two-fold: (1) Make the captions very descriptive and ensure you are adding your tags in there; and (2) Zoom in very closely on the UI of your plugin. These images are relatively small unless you click on them, so zooming in is crucial.
Live Demo
A relatively new feature of the Plugin Directory is an integration with the new WordPress Playground. Playground is a “serverless” environment, so all of WP is loaded in the browser, so there are some quirks.
There’s no official documentation yet for how you leverage it, but this post explains what you need to know about enabling the Live Demo button and potentially using your own custom blueprint as well.
At this stage, if you’ve followed all the above steps then your readme should be in great shape! The next 3 steps all happen outside of the readme itself but are also crucial to your rankings and success.
Step 5: Focus on Daily Support and Ratings Habits
The percentage of support tickets you’ve resolved on your plugin’s Support Forum is a ranking factor. The author of the SEO Framework reported that his ranking rose from 10th to 6th place because of resolving support tickets
Customer Support is my job and my passion, so I won’t let you off easy on this one. Providing top-notch support to your users is important primarily because that’s what your integrity demands of you, secondly because it will grow your product and business by reputation, and thirdly because it’s a ranking factor. Make excellent support a priority – it has ROI and matters.
Additionally, if you have great support you’ll get great ratings. Ratings are also a ranking factor for .org.
Both of these items require daily attention, not just short campaigns in fits and starts. If you’re in the product business, take your customer experience and reputation management seriously.
Step 6: Your own Website and Referrals
Even though WordPress.org is a giant magnet for people looking for plugins, you should contribute to pushing traffic to your free plugin as well.
I see so many plugin authors create beautiful websites to see their Pro version or add-ons, and nowhere in the whole website does it show that users can start using their product for free! I guarantee you that your free product is driving more sales by itself for you than your website does by itself.
If you have social profiles for your product, use them to point to .org regularly. Update your social profiles with unique shortlinks to point to your free plugin.
If you are finding your competitors on listicle articles out on the web, like “Top 10 best photo gallery plugins for WordPress” and you’re not on them, reach out to those authors to get listed. Especially when those sites are run by WordPress folks. tThey are very open to reviewing and considering your plugin too.
Step 7: Monitor Your Results to Tweak and Improve Over Time
Lastly, never think of your readme as set-it-and-forget-it. It’s a living document that should be monitored and tweaked regularly. There’s been a lot of conversation about the data .org provides (or the lack thereof!), but there are a lot of ways to monitor and track your effectiveness. Here are a few:
- Download Counts – Downloads are not as meaningful as Active Installs at all, but daily, weekly, and monthly trends are still insightful. Check out my tutorial on how to automate reporting on your daily downloads here.
- PluginRank – this is the go-to platform for monitoring your search rankings and download counts on .org. I use it daily and love it. It’s also great for monitoring your competitors and their rankings. When you see movement and changes, it might be a good time to see what changes they made to their readmes!
- Youtube/Vimeo data – like I mentioned above, if you embed videos, make sure those are not shared anywhere else at all, then all the data on that one video is about your readme. Watching for spikes and drops here is really insightful.
- UTM data – if you’ve properly applied UTMs to all your links to your website throughout your readme, you can monitor daily traffic that you get from .org.
README’s Don’t have to be Version Controlled in SVN
One thing to keep in mind is that the readme that shows up on .org is the one that’s in the “trunk” of your SVN repo. And you can update the whenever and however you like without having to push a plugin version update.
Of course you’ll probably have Git versioning that you’ll want to keep separate, but I’d encourage you to get a lot more adventurous in pushing updates to your readme.txt in your trunk to get the results you want quicker without being tied to a plugin version update.
This gives you tons more freedom to A/B test and tweak and monitor as needed.
Special Thank you’s are in order!
This has been a piece I’ve sat on for years and years. Once I finally decided to focus on it and publish I knew it would need input and feedback from other smart and detail-oriented folks. When I reached out for insight and feedback, the WP community stood and delivered, like always!
So here’s a few fine folks I need to thank for their contributions to this article:
- Stephanie Liy – the Queen of Docs herself was instrumental on spell checking, and highlighting areas of improvement and where I needed more punch or detail.
- Jonathan Bossenger – for tons of moral support and validation of the ideas and perspective in this post.
- Eric Karkovack – for his keen editorial eye.
- Nathan Weller – for validation that I covered the most important things, and reminding me about how readmes don’t need to be tied to plugin versions.
- Brian Coords – for moral support and feedback.
Let me Glam your Plugin README
You are the most effective person to be doing this work on your readme, because you know your product and audience better than anyone. But sometimes an outside perspective helps you see more clearly.
If you’d like my perspective on how you can improve your free plugin readme, and will allow me to showcase my audit of your plugin on my Glam that Plugin video series, then fill out this form and I’ll get you queued up.
Footnotes
- Freemius wrote an in-depth technical but accessible write-up on how the Plugin Directory search works. I still refer to that article regularly to brush up on my search knowledge.
The Plugin Directory search is powered by Jetpack’s hosted search (via WordPress.com) which is essentially Elastic Search as a service. So understanding how Elastic search works is really informative as well. This article specifically addresses how Elastic search determines relevance. This is the key to understanding how a user query ends up matching your plugin title or tags or not. ↩︎ - Semrush’s intent tags are really powerful. Product companies should try to capitalize on terms with high volume and commercial or transactional intent. ↩︎
- On-Page SEO: The Definitive Guide + FREE Template (2024) (backlinko.com) ↩︎
- The Plugin Handbook specifies that you can use any support oembed video source in your readme, even Tiktok! See the full list of oembed sources here. ↩︎
- This is a great read on the how and the why of leveraging consistent UTMs in your content marketing. ↩︎
Fantastic write-up Matt! Sharing this in the Freemius Community Slack.