How-To Guides and Blog

Formating readme.txt for WordPress Plugins 🔫

NBH Support
NBH Support
No Comments

I was inspired by Pippin’s post from 2012  about properly formating readme.txt for WordPress plugins and I decided to refresh it a bit. I tried to contribute to the official Plugin Readmes instructions on WordPress.org repository, but the editorial team said to send it over to them, and then they will rewrite the docs themselves. So I started writing on slack but since it just got bigger and bigger, I decided to write this article here instead.

If you’ve already published on WordPress.org or plan to do so, your plugin or theme is required to provide a so-called “readme.txt” text file. This is required because the repository parses it with Markdown language and draws all appropiate information from it, which is then displayed on the public repository. The header of that file also controls all aspects of the title, tagging, author, donate link etc. for your plugin or theme.

This is Pippin’s introduction into the article and for what I can tell, nothing has really changed here. However,  in the old days you had to write the file from scratch or download an existing wp plugin and copy it’s readme. Today, we have more options. We can use the plugin readme generator and put the result through the readme validator to check it.

Below I will share examples for each type of markdown and section.

Adding links

Use markdown syntax to add a link to your readme.txt file, for example:

https://gist.github.com/stefanpejcic/44d7de95f336636f10fdd8c61a1b0382

Tip: Do NOT leave empty space between the ] and (  brackets because it won’t work.

Alternately HTML also works:

https://gist.github.com/stefanpejcic/4ecf7b2b22e4acd3c574b6f15ab1f34f

Using HTML for links enables you to include other attributes such as target.

Another tip: Be careful with the target attribute because it can mess up the popup window that’s shown within wp-admin when the user clicks on “View Details”.

Adding screenshots

Adding screenshots of your plugin can be done by adding a “Screenshots” section to your readme.txt. Here is an example:

https://gist.github.com/stefanpejcic/d98d13c10a8ec6f3333723f9a3b4227b

Then you can use SVN to add the images that correspond to each of these descriptions, for example:

https://gist.github.com/stefanpejcic/21161c5c29717d73d518d588dd799103

Notice that the file type doesn’t matter, only the file name (e.g. screenshot-1 ) is important. That is, the number specified in the screenshot name corresponds to the description number.

Alternately you can use the following syntax if you want to host the images at an external location (i.e., instead of bundling them with your plugin files):

https://gist.github.com/stefanpejcic/2c31e3edc51b45ce583c440acb7925a7

A benefit of this technique is that you can name the image files whatever you want, and change the images quickly without having to update your plugin or use SVN.

Note also that you can include other information in the “Screenshots” section, but it will not be displayed by default at the Plugin Directory. It may be useful for sharing more information to any users who are reading the readme.txt directly.

Display screenshots in browser

If you are including screenshots in your plugin, you may notice that they are downloaded to the user’s browser when clicked from your plugin page. To prevent the download, and instead get the images to display in the browser, run whichever of the following commands applies to your image(s):

https://gist.github.com/stefanpejcic/9d217dc0e8c2ceeb7030fd0763f7823d

These commands set the MIME types for ALL images of type (e.g. .gif .jpg .png), so they will definitely cover all of your screenshots. But you can also target individual images like so:

https://gist.github.com/stefanpejcic/1113608fbc0f0d3a45b5e44c73f65aac

Etc., so that you apply the mime-type to whichever specific screenshots are desired. After doing so, your screenshots and other images will be displayed in the user’s browser instead of getting downloaded to their local drive.

Adding video

To add a video to your plugin’s readme.txt, you can use the following syntax:

https://gist.github.com/stefanpejcic/6758795dd7fa932ce084b8bd0baf4360

Or simply include the video URL on its own line:

https://gist.github.com/stefanpejcic/c0fa51278e602ee2d8cd76068f5a9a8c

As far as I can tell, this technique uses WP’s oEmbed feature. So the video must be hosted at a supported location. Other options may be available. Check the WP Codex for more information.

Adding Banners & Icons

To add banners and icons, create the following image files:

https://gist.github.com/stefanpejcic/9544ef81b04ae9c60ba6b765889054af

Notes:

  • This: (jpg|png) just means that you can create the files in either JPG or PNG format
  • As the path suggests, you want to add these files to your plugin’s assets/ directory
  • You can also add an SVG-format icon if desired

Add popout text

To add a popout text box, precede the text with a right-angle bracket:

https://gist.github.com/stefanpejcic/979ddb4425b91a6678d62dccf9822d6c

That will display the line of text in a light-grey colored box. To box multiple lines, you can do this:

https://gist.github.com/stefanpejcic/06eeee6ac57d7c57127cd023d846ccc7

This is useful for making content “pop” on the page.

Adding other images

To add other images elsewhere in the readme/documentation, use <img> tags, for example:

https://gist.github.com/stefanpejcic/2c24c010d09889e0722b606ad4602092

UPDATE: At the time of this edit (21 Aug 2019) Images are not longer supported in the readme file.

Tip: Autoplay GIF’s are not allowed inside WP docs and I’ve also noticed that GIF’s aren’t displayed in the description either. Therefore avoid GIF’s!

Separate plugin name and title

You can have a different name and title for your plugin. Consider the top part of most readme.txt files, they look something like this:

https://gist.github.com/stefanpejcic/d6d174f19c57d27c9df30758bb18ccae

Notice the “Plugin Name” is different than the plugin title (as specified via the top line).. that is the trick to naming your plugin something unique. So in this example, the plugin title will be used when searching for new plugins via the “Add New” screen in the WP Admin Area), while the “Plugin Name” is used to identify the actually installed plugin itself (so it will be used on the Plugins screen to identify your plugin in the list of plugins).

Create Lists

Unordered (bulleted) lists use asterisks, pluses, and hyphens  ( *, + and) as list markers. These three markers are interchangeable; this:

https://gist.github.com/stefanpejcic/9ba7906bccff2915f9314a67f2bcacf0

Ordered (numbered) lists use regular numbers, followed by periods, as list markers:

https://gist.github.com/stefanpejcic/1ce442c7fe9d880df45bfce4d812805e

Formatting text

To format text as strong, emphasized, and so forth, use markdown.

Example readme.txt file

This is an example of the readme.txt file feel free to fork it on Github Gist and re-use it.

https://gist.github.com/stefanpejcic/05922daaab1b364cdd1f380c9d114938

Final Thoughts

As I get more and more involved in the WordPress community and #polyglots on slack, this article will be used as a starting point to rewrite the Plugin Readmes section in WordPress.org Docs.

Over time I will add more markdown examples and definitely some screenshots. Anyone iTs welcome to comment and share any suggestion or trick that they use for readme.txt

Leave a Comment