WordPress Plugin README Tags – what you need to know

When building a WordPress plugin, a good quality README is critical, particularly if you’re going to be hosting it in the official directory. However, I’ve recently come across some unusual behaviour with the tags option that I want to dive into further.

According to “Developer Resources” on WordPress.org, tags are…

1 to 12 comma separated terms that describe the plugin. Only the first five will show on the generated page, and anything over 12 will be detrimental to SEO. Plugins must refrain from using competitors plugin names as tags.

Readme Header Information

There didn’t used to be a limit on the number of tags, but they introduced, a few years ago, a recommendation of up to 12.

So, according to this documentation, you can have up to 12 but only 5 will show on your plugin page. Got it. I regularly have around 6 to 7, so this is all good.

Over the last week I’ve decided to put 3 of my plugins up for adoption. There’s a little known tag, adopt-me that you can use to indicate this, so I added it on. When you do this your plugin should appear on a search for this tag, as well as a banner appearing on your plugin like this…

But, in my case, this only happened for one of my plugins.

When I studied all 3 what I noticed is that, for the one that worked, I’d added the flag at the 5th position. For the other 2 they were greater than this. Would moving them earlier in the list work? In fact, yes, it did. It appeared that this specific tag had to be used within the first 5 for it to work (I’ve since shifted this tag to the first position for all 3 of these plugins now, just to get me into the habit).

This isn’t documented anywhere so I spoke to the Meta team for clarity. Not only is this true (i.e. that it has to be one of the first 5) but the documentation is confusing in how the tags work more generally. So, let me clear this up…

Only the first 5 tags do ANYTHING on WordPress.org. That includes when you do a plugin search (and I’ve checked and can confirm this), search for a specific tag or even how your plugin is indexed. Tags 6 – 12 are only for any indexing that external services (such as search engines) do of your README file.

As Otto said to me…

We made the limit 12 originally so that people would stop filling it in with hundreds and hundreds of tags. They are used in the sense that the search engine sees them. But they are not used by the directory itself. Basically, the limit of 12 is not a technical limit. It is a rules based limitation.

Personally, I can’t therefore see any real advantage to having anything over the first 5 and, it seems to me, by doing so you’re only potentially going to forget some of the above rules and end up causing more issues than it’s worth. No, in future I’ll stick to just the 5 limit.