WP-Mix

The readme.txt file plays a central role when developing WordPress plugins, especially when hosting them at the WordPress.org Plugin Directory.

In this post I share some esoteric readme.txt tricks that plugin and theme developers may find useful. You also may want to read about how to add your plugin to the WP Plugin Repository (i.e., Plugin Directory).

Adding links

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

[Link Text](http://example.com/)

Alternately HTML also works:

<a href="http://example.com/">Link Text</a>

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

Adding screenshots

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

== Screenshots ==

1. This is the description for the first screenshot
2. This is the description for the second screenshot
3. This is the description for the third screenshot

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

/plugin-directory/assets/screenshot-1.png
/plugin-directory/assets/screenshot-2.jpg
/plugin-directory/assets/screenshot-3.gif

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):

[http://example.com/images/screenshot.png  Description for the first screenshot]
[http://example.com/images/another-one.png  Description for the second screenshot]
[http://example.com/images/and-another.jpg  Description for the third screenshot]

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. Maybe 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):

svn propset svn:mime-type image/gif *.gif
svn propset svn:mime-type image/jpeg *.jpg
svn propset svn:mime-type image/png *.png

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:

svn propset svn:mime-type image/jpeg screenshot-1.jpg
svn propset svn:mime-type image/jpeg screenshot-2.jpg
svn propset svn:mime-type image/jpeg screenshot-3.jpg

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:

[youtube https://www.youtube.com/watch?v=1234567890]

Or simply include the video URL on its own line:

https://www.youtube.com/watch?v=1234567890

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:

/assets/banner-772x250.(jpg|png)
/assets/banner-1544x500.(jpg|png)
/assets/banner-1880x609.(jpg|png)

/assets/icon-128x128.(gif|jpg|png)
/assets/icon-256x256.(gif|jpg|png)

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:

> This is boxed text

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

> This is multi-line boxed text
> This is multi-line boxed text

> This is multi-line boxed text

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:

<img src="http://example.com/image.jpg" alt="An amazing image" />

Alternately, I am guessing that maybe just adding the image URL on its own line might work as well:

http://example.com/image.jpg

But I haven’t tested this, so can’t say for sure.

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:

=== BBQ: Block Bad Queries ===

Plugin Name: Block Bad Queries (BBQ)
Plugin URI: https://perishablepress.com/block-bad-queries/
.
.
.

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 is used for the BBQ homepage at WordPress.org (so it 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 actual installed plugin itself (so it will be used on the Plugins screen to identify your plugin in the list of plugins). Tricks! ;)

Formatting text

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

Now go forth and document thy plugins!