How Your Readme.txt Works
This page will explain some aspects of the plugin directory, and explain of the more obvious aspects which a lot of people miss.
To make your entry in the plugin browser most useful, each plugin should have a readme file named
readme.txt that adheres to the WordPress plugin readme file standard. You can use the plugin readme generator and put the result through the readme validator to check it.
Example Readme #Example Readme
=== Plugin Name === Contributors: (this should be a list of wordpress.org userid's) Donate link: http://example.com/ Tags: comments, spam Requires at least: 3.0.1 Tested up to: 3.4 Stable tag: 4.3 License: GPLv2 or later License URI: http://www.gnu.org/licenses/gpl-2.0.html Here is a short description of the plugin. This should be no more than 150 characters. No markup here. == Description == This is the long description. No limit, and you can use Markdown (as well as in the following sections). For backwards compatibility, if this section is missing, the full length of the short description will be used, and Markdown parsed. A few notes about the sections above: * "Contributors" is a comma separated list of wp.org/wp-plugins.org usernames * "Tags" is a comma separated list of tags that apply to the plugin * "Requires at least" is the lowest version that the plugin will work on * "Tested up to" is the highest version that you've *successfully used to test the plugin*. Note that it might work on higher versions... this is just the highest one you've verified. * Stable tag should indicate the Subversion "tag" of the latest stable version, or "trunk," if you use `/trunk/` for stable. Note that the `readme.txt` of the stable tag is the one that is considered the defining one for the plugin, so if the `/trunk/readme.txt` file says that the stable tag is `4.3`, then it is `/tags/4.3/readme.txt` that'll be used for displaying information about the plugin. In this situation, the only thing considered from the trunk `readme.txt` is the stable tag pointer. Thus, if you develop in trunk, you can update the trunk `readme.txt` to reflect changes in your in-development version, without having that information incorrectly disclosed about the current stable version that lacks those changes -- as long as the trunk's `readme.txt` points to the correct stable tag. If no stable tag is provided, it is assumed that trunk is stable, but you should specify "trunk" if that's where you put the stable version, in order to eliminate any doubt. == Installation == This section describes how to install the plugin and get it working. e.g. 1. Upload `plugin-name.php` to the `/wp-content/plugins/` directory 1. Activate the plugin through the 'Plugins' menu in WordPress 1. Place `<?php do_action('plugin_name_hook'); ?>` in your templates == Frequently Asked Questions == = A question that someone might have = An answer to that question. = What about foo bar? = Answer to foo bar dilemma. == Screenshots == 1. This screen shot description corresponds to screenshot-1.(png|jpg|jpeg|gif). Note that the screenshot is taken from the /assets directory or the directory that contains the stable readme.txt (tags or trunk). Screenshots in the /assets directory take precedence. For example, `/assets/screenshot-1.png` would win over `/tags/4.3/screenshot-1.png` (or jpg, jpeg, gif). 2. This is the second screen shot == Changelog == = 1.0 = * A change since the previous version. * Another change. = 0.5 = * List versions from most recent at top to oldest at bottom. == Upgrade Notice == = 1.0 = Upgrade notices describe the reason a user should upgrade. No more than 300 characters. = 0.5 = This version fixes a security related bug. Upgrade immediately. == Arbitrary section == You may provide arbitrary sections, in the same format as the ones above. This may be of use for extremely complicated plugins where more information needs to be conveyed that doesn't fit into the categories of "description" or "installation." Arbitrary sections will be shown below the built-in sections outlined above. == A brief Markdown Example == Ordered list: 1. Some feature 1. Another feature 1. Something else about the plugin Unordered list: * something * something else * third thing Here's a link to [WordPress](https://wordpress.org/ "Your favorite software") and one to [Markdown's Syntax Documentation][markdown syntax]. Titles are optional, naturally. [markdown syntax]: http://daringfireball.net/projects/markdown/syntax "Markdown is what the parser uses to process much of the readme file" Markdown uses email style notation for blockquotes and I've been told: > Asterisks for *emphasis*. Double it up for **strong**. `<?php code(); // goes in backticks ?>`
SVN Layout #SVN Layout
There are four directories created by default in all SVN repositories.
/trunk directory is where your plugin code should live. The trunk can be considered to be the latest and greatest code, however this is not necessarily the latest stable code. Trunk is for the development version. Hopefully, the code in trunk should always be working code, but it may be buggy from time to time because it’s not necessarily the “stable” version. For simple plugins, the trunk may be the only version of the code that exists, and that’s fine as well.
/tags directory is where you can put versions of the plugin at some specific point in time. Usually, you’ll use version numbers for the subdirectories here. So version 1.0 of the plugin would be in
/tags/1.0, version 1.1 would be in
/tags/1.1, and so forth. Again, not every plugin uses tags for versioning, however for those that do we strongly encourage the use of semantic software versioning.
/branches directory is a place that you can use to store branches of the plugin. Perhaps versions that are in development, or test code, etc. The WordPress.org system does not use the branches directory for anything at all, it’s considered to be strictly for developers to use as they need it.
Note: See also: How Your Plugin Assets Work
Assets is where your screenshots, header images, and plugin icons reside. It’s recommended but not required to put screenshot files in
Readme Details #Readme Details
All plugins contain a main PHP file, and almost all plugins have a
readme.txt file as well. The
readme.txt file is intended to be written using a subset of markdown.
Readme Header Information #Readme Header Information
The Plugin readme header consists of this information:
=== Plugin Name === Contributors: (this should be a list of wordpress.org userid's) Donate link: http://example.com/ Tags: comments, spam Requires at least: 3.0.1 Tested up to: 3.4 Stable tag: 4.3 License: GPLv2 or later License URI: http://www.gnu.org/licenses/gpl-2.0.html Here is a short description of the plugin. This should be no more than 150 characters. No markup here.
The line for Contributors is a case sensitive list of all WordPress.org usernames who have contributed to the code. It is generally considered respectful to include the names of people who worked on forked projects. Some developers will ask to be removed from the list, as they don’t want other plugins showing up on their profile page. It’s best to honor those requests. Remember to only use the WordPress.org username – anything else will show up sans profile link and gravatar, which is sad. If you want to change your display name (which shows on the front facing pages for you plugin), edit your profile
https://wordpress.org/support/users/YOURID/edit/ and change the display name.
The Donate link makes a “Donate to this plugin” link in the sidebar. It’s entirely optional, and if there is no link,
The Requires at least and Tested up to fields are used for compatibility checking with WordPress core. If a plugin sets the required version to 4.4, then users on 4.4 and below will not receive update notifications. Use this wisely.
At the end of the header section is a place for a short description of a plugin. The example recommends no more than 150 characters and to not use markup. That line of text is the single line description of the plugin which shows up right under the plugin name. If it’s longer than 150 characters, it gets cut off, so keep it short.
How The Readme Is Parsed #How The Readme Is Parsed
WordPress.org’s Plugin Directory works based on the information found in the field Stable Tag in the readme. When WordPress.org parses the
readme.txt, the very first thing it does is to look at the
readme.txt in the
/trunk directory, where it reads the “Stable Tag” line. If the Stable Tag is missing, or is set to “trunk”, then the version of the plugin in
/trunk is considered to be the stable version. If the Stable Tag is set to anything else, then it will go and look in
/tags/ for the referenced version. So a Stable Tag of “1.2.3” will make it look for
Warning: If you do not use a stable tag, everything will be read from the trunk location.
If the Stable Tag is 1.2.3 and
/tags/1.2.3/ exists, then nothing in trunk will be read any further for parsing by any part of the system. If you try to change the description of the plugin in
/trunk/readme.txt, and Stable Tag isn’t trunk, then your changes won’t do anything on your plugin page. Everything comes from the
readme.txt in the file being pointed to by the Stable Tag. If there is no folder for the Stable Tag, then WordPress will default to using the trunk folder’s content.
The WordPress.org Plugin Directory reads the main plugin PHP file to get things like the Name of the plugin, the Plugin URI, and most importantly, the version number. On the plugin page, you’ll see the download button which reads “Download Version 1.2.3” or similar. That version number comes from the plugin’s main PHP file, not the readme!
The Stable Tag points to a subdirectory in the
/tags directory. But the version of the plugin is not actually set by that folder name. Instead, it’s the version that is listed in the plugin’s PHP file itself which determines the name. If you have changed Stable Tag to 1.4 and the plugin still says 1.3 in the PHP file, then the version listed will be 1.3.
The readmes use a customized version of Markdown. Most Markdown calls work as expected.
Markdown allows for easy linking in your readme.txt as well. Just write like this to link a word to a URL:
Videos can be put into your readme.txt too. A YouTube or Vimeo link on a line by itself will be auto-embedded. It’s also possible to embed videos hosted on VideoPress using the wpvideo shortcode.
What updates what field #What updates what field
For those who want to know exactly what gets parsed into what:
Author field from the plugin header and Contributors field from the readme file.
Version field from the plugin header.
- Tags (as in categories)
Tags field from the readme file.
- Plugin Name
The Plugin Name from the readme file falling back on the Plugin Name specified in the plugin header.
- Author and Plugin Homepages
The Author URI and Plugin URI fields of the plugin header. The Plugin URI should be unique to each plugin.
- Last updated time
Time of last check in to the appropriate directory after a version number change.
- Creation time
Time of first check in.