Optimizing Your WordPress.org Plugin Landing Page

When you create a free plugin and submit it to the WordPress.org plugin repository, you get the privilege of creating a landing page for that plugin.

Technically it’s not the same as creating a landing page for your own site using whatever layout and styling you want. But it’s a landing page nevertheless.

Whatever your plugin business model is, one goal most of us have that choose to put a plugin in the repo is to get as many downloads as possible.

Let’s start from the top of the landing page…

Create a Killer Banner Image

Just about everything you need to edit in order to optimize your plugin landing page is in the plugin’s readme.txt file. Except one of the most crucial parts: the banner image.

It’s basically a 772 pixel wide by 250 pixel tall image, and the technical details on how to submit it can be found at the bottom of the WordPress Plugin Developer FAQ.

This banner image is your header and comes above everything else on the page other than WordPress.org’s own header. It’s what viewers will notice first when making that 5-second decision to continue reading about your plugin or moving on to another.

When you’re creating a banner image, remember that the plugin name will overlay the bottom left corner of the banner image. The banner image screenshots below include the overlay text so you can see this. The overlay’s width is determined by how long the plugin name is.

Even though the plugin name is included in this overlay, you don’t have control of its placement or font. For this reason many good banner images include the name of the plugin or a strong headline higher up in the image with the brand’s font, style and sometimes logo.

Here’s what I consider a few great banner image examples at the time of this post:

Easy Digital Downloads

Ultimate Coming Soon Page



  • Easy Digital Downloads adds its tagline to the banner image below a custom logo and title. Pretty common practice on regular landing page optimization.
  • Ultimate Coming Soon Page goes right into its features with a separate bullet list off to the right-hand side.
  • VideoPress lists its features at the top-left along with a short subhead underneath its custom headline in the center of the banner image.
  • WooCommerce doesn’t include any additional headlines or bullet points in the banner image itself. Instead it relies on its “Woo Ninja” characters to strengthen its brand and adds “excelling eCommerce” to the actual plugin name so it appears in the overlay.

At this point I have to mention a fantastic copywriting and headline writing resource: Copy Hackers.

I’ve gotten a ton of value out of their books over the last couple years. Book 3 is specifically on headlines and subheads. But all their stuff is high quality and will help improve your overall ability to convert users with your web copy and calls-to-action.

Readme.txt and Markdown

Besides the banner image, everything else seen on the landing page is controlled by the readme.txt file. You’ll need to use Markdown, which gives you some formatting control (albeit limited).

You can reference the original Markdown syntax, but a better resource is in the Smashing Magazine post How To Improve Your WordPress Plugin’s Readme.txt.

For starters, the short text phrase under the banner image is like another subhead. Maybe even the only subhead if you don’t include one in your banner image.

This subhead should be 150 characters or less like a tweet. It should communicate what this plugin does and who it’s for. As you can see, it’s a larger font than the rest of your plugin’s description that follows, so make it count!

Writing Good Landing Page Copy

Don’t just write huge paragraphs. People will lose interest quickly. Make sure to take full advantage of the Markdown syntax available to you.

Use different heading sizes, bullet points and plenty of whitespace to break things up.

In most cases you want to list off the benefits and features your plugin has to offer. If applicable link to demos and examples of your plugin in use.

Besides getting a bunch of downloads, you may want to encourage users to pay for support, upsell them to a premium plugin or add-ons, or simply get your brand name out there. Various plugin shops have different business goals which should be communicated in the copy.

If you want to learn more about good landing page strategies and writing good web copy, here’s a few resources to get your started:

Embed a Video

A lot of non-plugin high-converting landing pages use video as the first visual after the headline. Video happens to be one of the only visual options WordPress.org plugin pages allow besides the banner image and author avatars.

Whether it’s a promo, intro or instructional video, put one out there if you can. Probably near the top. I’m sure this helps a ton and is something I need to tackle for my own plugins. Note you can only use YouTube or Vimeo embeds at this time.

Limitations on Calls-to-Action (CTAs)

As for big call-to-action buttons, the only one allowed on the plugin landing page is the orange “Download Version X.XX” that is automatically generated. If you’re attempting to upsell to a premium plugin or add-ons by directing the reader to your own site, you can’t create a nice call-to-action button in the copy. You just do what you can with Markdown.

Since you’re not allowed to use bold or heading text in a link, at least add line breaks and white space around any links you’re attempting to direct the reader to. Maybe add an exclamation point and/or double right arrow HTML symbol (HTML code ») to emphasize the link as much as possible.

Some “freemium” plugins such as Ultimate Coming Soon Page list their “Pro” features after their free plugin features, then put a link “Upgrade to Pro” after the list. The hope is that some readers will see that they need Pro features right away and head over to buy the Pro plugin immediately.

But in the end it’s assumed the majority of readers will download your free plugin to try it out first before pulling out their credit card. For this reason you may want to focus your upselling efforts more within your free plugin itself where you have more formatting control anyway. I plan on covering methods and strategies for upselling within a free plugin in a future post.

WordPress.org Plugin Page SEO

Remember that WordPress.org is a high-ranking domain in search engines. Do a search for a type of plugin in Google (i.e. “twitter wordpress plugin”) and usually at least a few free plugins hosted on WordPress.org show up within the top 5 or so results.

If you’re selling a premium plugin you’ll also want to get your own website to rank high, but chances are your free plugin on WordPress.org will rank higher for key terms for a while.

Taking this into consideration, make sure your readme.txt content is like a good search optimized post in that it contains the keywords you want to rank for. There’s a ton more to learn to create a highly SEO-optimized page. I suggest heading over to the Hittail blog for some helpful SEO articles.

Plugin Version Numbers and Compatibility

On the right of your main plugin copy is the big call-to-action download button and a few other items to maintain at the beginning of your plugin’s readme.txt. Make sure and get these right.

The “Download Version x.x.x” button points to what you’ve indicated in the “stable” tag. Make sure folks are downloading the correct version.

Set “Requires” to a WordPress version that makes sense for your plugin. Don’t assume everyone will upgrade to the latest version of WordPress right away. Consider going back a few versions as long as it doesn’t create a support headache for you.

Set “Compatible up to” to at least the current version of WordPress. Some plugins put the beta version that’s on the horizon here to give readers confidence it’ll continue to work when they update WordPress core.

“Last Updated” indicates the last date the readme.txt or any code has been updated. Keeping this date fairly current gives readers confidence that the plugin is unlikely to be abandoned or break anytime soon.

If you’re regularly optimizing your readme.txt anyway, keeping this date current will take care of itself.

Here’s a snapshot of my Pinterest “Pin It” Button Lite plugin right-hand side at the time of this post.

WordPress.org plugin sidebar

Below “Downloads” are your plugin ratings and author avatars. Make sure your WordPress author profiles are filled out and Gravatars linked properly. And please display decent profile images for your authors instead of a lame generated cartoon character. It can only help your plugin page’s trust factor when readers see a real face.

To update these plugin header options properly use the official WordPress.org readme.txt boilerplate or the more in-depth guide by David Decker on Pippin’s Plugins titled How to Properly Format and Enhance Your Plugin’s Readme.txt File for the WordPress.org Repository.

Both of these guides also go into the other pages controlled by the readme.txt besides the plugin landing page, such as Installation, FAQ, Screenshots and Changelog.

Test and Experiment

Just like regular website landing pages, you can continually optimize the conversion rate of your plugin landing page by tweaking and testing.

Since you can update your plugin’s readme.txt as often as you like, test and experiment to find what works for your plugin and your business goals. Try something for a week or two and look at your plugin download stats and referrals to your main website. Make sure to add trackable URLs (like Google campaign URLs) to all links back to your website in your readme.txt.

If you have any tips or tricks that have helped you optimize your WordPress.org plugin landing pages, I’d love to hear about it in the comments.


  1. John Turner on June 19, 2013 at 8:15 am

    Awesome article and thanks for the mentioning the Ultimate Coming Soon Page plugin!

  2. Pippin Williamson on June 19, 2013 at 8:18 am

    Testing different copy and placements is hugely important, though it’s definitely something I fail miserably on. I’d love to hear about the results of your testing :D

  3. Adrian on June 24, 2013 at 1:07 am

    Great article Phil! Really looking forward on your thoughts and methods of upselling within a free plugin.

  4. Phil Derksen on June 24, 2013 at 9:37 am

    Thanks guys. I’ve been doing some upselling within my free plugin for a while with banners and such, but I plan on changing things around a bit to see what happens. I’ll report back in the future here.

  5. Adam W. Warner on June 26, 2013 at 7:42 pm

    Really great article here Phil, I’ve shared it with our team as a “must read”. I wish you the best of success!

    • Phil Derksen on June 26, 2013 at 9:07 pm

      Thanks Adam! I enjoyed your interview on Matt Report and look forward to what’s in store with your new plugin marketplace.

  6. Kyle on May 3, 2014 at 2:00 pm

    Thanks Phil. This is a timely post for me as I prep my first for submission.

    • Phil Derksen on May 3, 2014 at 2:31 pm

      Great to hear Kyle.