readme.txt

All WordPress plugins contain a main PHP file. And files from the WP directory also include the mandatory file readme.txt. This file contains information about the plugin for the WordPress directory. For example, 90% of the information on a plugin page in the WordPress directory is taken from readme.txt.

Sometimes this file may be used by other parsers, plugins, etc. Therefore one can say that it is an important plugin file if you are creating a public plugin. And even if you do not publish the plugin in the WordPress directory, it would still be useful to create such a file in your plugin.

Useful links:

Contents:

Example of a readme.txt file

https://wordpress.org/plugins/readme.txt

GitHub 
=== Plugin Name ===
Contributors: (this should be a list of wordpress.org userid's)
Donate link: https://example.com/
Tags: tag1, tag2
Requires at least: 4.7
Tested up to: 5.4
Stable tag: 4.3
Requires PHP: 7.0
License: GPLv2 or later
License URI: https://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 wordpress.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*
* Stable tag must indicate the Subversion "tag" of the latest stable version

Note that the `readme.txt` value of stable tag is the one that is the defining one for the plugin.  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.

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, your users may not get the correct version of your code.

== 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). Screenshots are stored in the /assets directory.
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.

== A brief Markdown Example ==

Markdown is what the parser uses to process much of the readme file.

[markdown syntax]: https://daringfireball.net/projects/markdown/syntax

Ordered list:

1. Some feature
1. Another feature
1. Something else about the plugin

Unordered list:

* something
* something else
* third thing

Links require brackets and parenthesis:

Here's a link to [WordPress](https://wordpress.org/ "Your favorite software") and one to [Markdown's Syntax Documentation][markdown syntax]. Link titles are optional, naturally.

Blockquotes are email style:

> Asterisks for *emphasis*. Double it up  for **strong**.

And Backticks for code:

`<?php code(); ?>`

Sections (divisions) of readme.txt

=== Plugin Name ===

The headings of readme.txt consist of the following data:

=== Plugin Name ===
Stable tag:        4.3
Tested up to:      3.4
Contributors:      (this should be a list of wordpress.org userid's)
Donate link:       http://example.com/
Tags:              comments, spam
License:           GPLv2 or later
License URI:       http://www.gnu.org/licenses/gpl-2.0.html
WC requires at least: 3.0
WC tested up to:      3.5

Here is a short description of the plugin. This should be no more than 150 characters. No markup here.

Since WP 5.8 the headers Requires at least: and Requires PHP: have been moved to the main plugin file.

Plugin Name
Plugin name. Replace with the name of your plugin.
Stable tag
The stable version of the plugin – the latest version you consider stable. This is a very important tag because it determines which version of the plugin will be downloaded from the repository. See more below in the section How readme is parsed.
Tested up to
The highest major WP version the plugin has been tested with. You should specify only numbers: 4.9, and not WP 4.9.
Requires PHP(OPTIONAL)
Minimum PHP version required to use this plugin. Here you should put only numbers: 7.0, and not PHP 7.0.
WC Requires at least
WC Tested up to
Similar fields for the WooCommerce plugin. When creating a plugin for the WC plugin.
Contributors
This is a list (comma-separated) of names from WordPress.org (case-sensitive) who have worked on the plugin in some way. Developers may ask to be removed from the list because they do not want the plugin to appear on their profile page. If you use a name not from WordPress.org, it will appear without a profile link and without gravatar. If you want to change the displayed name (shown on the plugin page), edit your profile https://wordpress.org/support/users/YOUR_ID/edit/.
Tags
Tags (comma-separated) that correspond to your plugin and its purpose. Tags are important because they help users find the plugin in the repository (for those who like browsing by tags). You can also include your company name in the tags to filter plugins and, for example, show to clients.
Donate link
Creates a “Donate to this plugin” link in the directory sidebar. It can be omitted.

At the end there is a place for a short description of the plugin. It is recommended to be no more than 150 characters and not to use markup. This line is a one-line description of the plugin that appears directly under the plugin name. If it is longer than 150 characters, it will be truncated, so keep it short.

Requires at least (not working with WP 5.8)
Used to check compatibility with WordPress core. For example, if the required version 4.4 is specified, users with versions below 4.4 will not receive update notifications.

== Description ==

Detailed description of the plugin (Markdown can be used, see below).

== Frequently Asked Questions ==

This section contains a list of frequently asked questions.

The list is created in the following format:

= Question title 1 =
Answer to question 1.

= Question title 2 =
Answer to question 2.

== Installation ==

This section is usually created when installing the plugin requires any additional steps. If the plugin is installed and does not require any additional configuration, this section can be omitted.

== Screenshots ==

Screenshots of the plugin. In the format:

1. Description of screenshot one
2. Description of screenshot two

Screenshot files should be placed in the WP directory, in the common /assets folder or in the root of the stable version of the plugin. The file name will be: screenshot-NUMBER.png|jpg|jpeg|gif. For example: screenshot-1.jpg and sreenshot-2.png.

Files in the main /assets folder have higher priority. For example, /assets/screenshot-1.png will win over /tags/4.3/screenshot-1.(png|jpg|jpeg|gif).

The descriptions of list items will become captions for the image. The description can include URLs if needed.

== Upgrade Notice ==

Important notes for updates. The changelog is kept in the changelog section, and in this section it is recommended to write very important notes, for example when incompatible changes with the previous version were made or when after updating you need to do something to make the plugin continue to work as intended.

Recommended format:

= 1.3 =
In version 1.3 the `foo()` function was banned, replace it with `bar()` in your projects.

= 1.0 =
The plugin table name changed from `wp_foo` to `wp_myplug`.

This section is not visible on the plugin's main repository page. This content will be visible in the WordPress admin (by clicking the “Details” link on the page wp-admin/plugins.php or wp-admin/update-core.php).

== Changelog ==

List of changes, recommended in a list format:

= 1.0 =
* A change since the previous version.
* Another change.

= 0.5 =
* List versions from most recent at top to oldest at bottom.

== Proizvolnaya sektsiya ==

In readme you can specify any sections. It is not recommended to create many sections. Ideally you should limit to basic sections to maintain the usual plugin description standard.

Examples of arbitrary sections:

== Translations ==

* English - default, always included
* German: Deutsch - immer dabei!

*Note:* All my plugins are localized/ translateable by default. For translating I recommend the awesome plugin [Code Localization](http://site.org/code-localization/).

== Additional Info ==
**Idea Behind / Philosophy:** Just a little lightweight plugin...

== Credits ==
* Thanks to [Dominik Schilling](http://wpgrafie.de/) [@ocean90](http://twitter.com/#!/ocean90) for great help with the CSS for the first level icon in WordPress 3.3!

How readme is parsed

The WordPress.org Plugin Directory works based on information found in the field Stable Tag in the readme.txt file. WordPress.org reads readme.txt in the directory /trunk (in the plugin directory), reads the value of the Stable Tag field. When the Stable Tag is missing or equal to trunk, the stable version of the plugin is considered to be the code in the /trunk folder. If a specific version is set for the Stable Tag, that version will be checked (must be located) in the /tags/ directory. For example, if version 1.2.3 is specified, all plugin data will be taken from the /tags/1.2.3/ folder. There are two possible scenarios here:

  • /tags/1.2.3/ exists — /trunk will not be used for any analysis. For example, if you try to modify the plugin description in /trunk/readme.txt, but the Stable Tag is not equal to trunk, the changes will not affect the plugin page because the data will be taken from readme.txt pointed to by the Stable Tag.

  • /tags/1.2.3/ DOES NOT exist — the analysis will use the /trunk folder.

If the Stable Tag is not specified, it defaults to trunk.

Stable Tag points to a subdirectory under the /tags directory, but the plugin version is NOT taken from the folder name. It is taken from the main plugin file. So, for example, if you change the Stable Tag to 1.4, but the PHP file of the plugin still specifies 1.3, then the version will be 1.3.

The WordPress.org directory reads the main PHP file of the plugin to obtain: plugin name, plugin URI, version number. The download button on the plugin page uses the version specified in the main plugin file (not from readme)!

Markdown

The readme uses a slightly modified version of Markdown. 90% of Markdown syntax works as expected.

You can use Markdown links. They have standard syntax:

[WordPress](http://wordpress.org)

Example Markdown markup for other elements:

Numbered list:

1. Some feature
1. Another feature
1. Something else about the plugin

Unnumbered list:

* something
* something else
* third thing

Multilevel unordered list:

* First item
* Second item
  * Third item (2 level)
  * Fourth item (2 level)
* Fifth item (1 level)
* etc.

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 ?>`

Video

You can embed videos from YouTube, Vimeo and other services from WordPress's whitelist.

The video is inserted as a link to the video on a separate line in the readme file.

It is not recommended to add a link on the last line of the file, because sometimes the formatting may break and the link will not be converted into a video code.

File size

A file larger than 10k may cause errors. The readme should be as concise as possible. Do not put everything in the readme; use links, for example, links to your plugin description on your site.

A large changelog can be placed in a separate file, for example changelog.txt, and the readme can include a link to this file. This keeps the readme orderly.