The WordPress.org plugin directory has had a massive overhaul and, as a result, plugin information is now shown differently to before. For plugin developers, therefore, a tweak to how you present your README (and associated assets) can ensure your plugin is presented better.

To this end, I’ve already updated my YouTube Embed plugin README to demonstrate what I mean with all of the following. Please feel free to examine and use this as an example of use.

Here are, I believe the important changes that have been made…

New Structure

The new directory shows all the plugin information, rather than as a series of tabs, as a single vertical page, showing an excerpt of each section of the plugin – a ‘Read More’ link at the bottom of each section expands it fully.

The Banner

The banner used to have the name of the plugin overlaid onto it. As a result, they even allowed you to supply an RTL version of the banner, for when the text is on the other side. For my own plugins, I presented a single colour background with an icon on the opposite side to the text. It was simply but worked. Now, though, the plugin title is shown separately so the banner sits by itself. I’m also making the assumption that the RTL banner is, now, no longer needed.

The Avatar

This used to only be used on the search results but is now shown to the left of the plugin name on its main page.

Tags

It has been recommended for a while that the number of tags used should be restricted to 12 but the new directory will only display the first five. However, any not being displayed can still be searched on successfully.

As users can click on these tags, you may want to display the five most important tags first. Of course, these will link to other plugins so how you use these is up to you!

Description

Rather than the initial README section showing here, this also shows any of your additional sections too (which used to covered under the ‘README’ tab). Only a few lines are shown initially, so I’d ensure the first few lines of this are the important sell.

Short Description

This is the short item of text that you place above the ‘Description’ section of the README. In the new directory, this is no longer shown. However, it is relevant as it it used for the short description that appears next to search results.

My recommendation would be to repeat this as the opening line of your main description too, to ensure this is shown, as a nice summary of the plugin.

Issues

There are a number of known issues, all recorded on Trac.

For me, however, one of those issues is having a significant effect. The back-end of the new plugin directory makes use of the shortcodes [youtube] and [vimeo]. If your plugin therefore uses these (as one of mine does) then you will need to escape mention of the shortcode in the README using double square brackets.