The WordPress plugin readme.txt

Every plugin in the WordPress.org directory has a readme.txt. WordPress.org builds the plugin page from it: the name, short description, tags, compatibility, and the Description, Installation, FAQ, Screenshots and Changelog tabs. This page covers the format field by field, gives you a template that passes the validator, and explains each validator message.

A readme.txt template

Copy this into readme.txt in your plugin's root folder and replace the text. As written, it passes the WordPress.org validator with no errors, warnings or notes.

=== Readme Example ===
Contributors: wordpressdotorg
Donate link: https://example.com/donate
Tags: readme, documentation, example
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

One sentence that says what the plugin does, in 150 characters or fewer, without markup.

== Description ==

What the plugin does and who it is for. This is the first thing people read on the plugin page.

* A list of features
* Written as **Markdown**
* With [links](https://example.com/) where they help

https://www.youtube.com/watch?v=aqz-KE-bpKQ

= A subheading =

Subheadings inside a section use single equals signs.

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/`, or install it from the Plugins screen.
2. Activate the plugin through the Plugins screen.
3. Open Settings → Readme Example to configure it.

== Frequently Asked Questions ==

= Does it work with multisite? =

Yes. Each question is a line wrapped in single equals signs, followed by its answer.

= Where do I report a bug? =

In the plugin's support forum on WordPress.org.

== Screenshots ==

1. The caption for screenshot-1.png in the plugin's SVN assets folder.
2. The caption for screenshot-2.png.

== Changelog ==

= 1.0.0 =
* First release.

== Upgrade Notice ==

= 1.0.0 =
First release.

The file starts with the plugin name between triple equals signs, then one field per line. Field names are not case-sensitive.

=== Readme Example ===: The name shown on the plugin page. Leaving the literal text Plugin Name is an error. Names containing restricted terms, such as plugin, WordPress or another company's trademark, are flagged as errors.
Contributors: wordpressdotorg: Comma-separated WordPress.org usernames. They are case-sensitive, and names that aren't WordPress.org users are dropped.
Donate link: https://example.com/donate: Optional. Adds a donate link to the plugin page.
Tags: forms, contact, email: Up to 5 comma-separated tags; WordPress.org ignores the rest. The tags plugin and wordpress are always ignored. Don't use other plugins' names as tags.
Requires at least: 6.5: The oldest WordPress version the plugin supports, as a number only. It can also be set in the main plugin file instead.
Tested up to: 7.1: The newest WordPress version you have tested with, as a number only (7.1, not WP 7.1). Use the major version; minor releases count automatically. A version newer than the next WordPress release is ignored.
Requires PHP: 7.4: The oldest PHP version the plugin supports, as a number only. It can also be set in the main plugin file instead.
Stable tag: 1.0.0: The plugin version users should get: the name of a folder under /tags/ in your SVN repository. Use digits and dots. trunk is not allowed for new plugins.
License: GPLv2 or later: A license compatible with GPLv2 or later. A missing or unrecognized license is flagged.
License URI: https://www.gnu.org/licenses/gpl-2.0.html: Optional. A link to the license text; worth adding for less common licenses.

The version number on the download button doesn't come from the readme: WordPress.org reads it from the Version header in your main plugin file.

The short description

The first line after the header is the short description, shown under the plugin name and in search results. Keep it to 150 characters or fewer and leave out markup: WordPress.org strips HTML from it and cuts anything longer. Without one, WordPress.org uses the start of the Description section instead.

Sections

Sections start with a line in double equals signs, such as == Description ==. Markdown-style ## Description works too.

== Description ==: What the plugin does and who it is for. It becomes the main tab of the plugin page.
== Installation ==: Setup steps. Optional when installing needs nothing beyond activating the plugin.
== Frequently Asked Questions ==: Each question goes on its own line between single equals signs (= Does it work with multisite? =), followed by its answer. == FAQ == works too.
== Screenshots ==: A numbered list of captions. Caption 1 belongs to screenshot-1.png (or .jpg) in your SVN assets folder, caption 2 to screenshot-2.png, and so on.
== Changelog ==: One subheading per version (= 1.0.1 =) with a list of changes. Keep recent releases here and move older ones to a separate changelog.txt.
== Upgrade Notice ==: One subheading per version with a sentence on why to upgrade. WordPress shows it next to the update in the Plugins screen, so keep it short.

Any other section, such as == Credits ==, appears under Other Notes. Use custom sections sparingly: people expect plugin pages to look alike.

Formatting

Sections use a Markdown variant: lists, **bold**, *italic*, `code`, code blocks indented by four spaces, and links written as [text](https://example.com/).
Subheadings inside a section use single equals signs: = Subheading =.
A YouTube or Vimeo URL alone on its own line becomes an embedded video. Avoid making a video the last line of an FAQ answer.

Which readme WordPress.org reads

WordPress.org first reads trunk/readme.txt, but only for its Stable tag. If that says 1.2.3 and tags/1.2.3/ exists, the plugin page comes from tags/1.2.3/readme.txt. Editing the readme in trunk alone then changes nothing on the plugin page. To update a released readme, change it in both trunk and the current tag, and keep the Stable tag the same in both.

Validator messages and how to fix them

These are the messages the WordPress.org readme validator shows, word for word. Errors keep a readme from working properly, warnings mean WordPress.org ignored or changed something, and notes point at optional parts. WPreadme.com shows the same messages in its Issues tab as you type.

Message	Fix
Error We cannot find a plugin name in your readme. Plugin names look like: `=== Plugin Name ===`. Please change `Plugin Name` to reflect the actual name of your plugin.	Put your plugin's real name on the first line: `=== Readme Example ===`.
Error Your chosen plugin name - `My Plugin` - contains the restricted term "`plugin`", which cannot be used at all in your plugin permalink nor the display name.	Rename the plugin without that term. Trademarks such as `WordPress`, `WooCommerce` or `Jetpack` trigger the same error.
Error The `License` field appears to be invalid. A GPLv2 or later compatible license should be specified.	Use a GPL-compatible license name, such as `License: GPLv2 or later`.
Warning The `License` field is missing. A GPLv2 or later compatible license should be specified.	Add `License: GPLv2 or later` to the header.
Warning The `Tested up to` field is missing.	Add `Tested up to: 7.1`, or the newest WordPress version you have tested with.
Warning The `Tested up to` field was ignored. This field should only contain a valid WordPress version such as `7.1` …	Use a plain version number that exists, or is the next release. `WP 6.8`, `latest` and future versions are ignored.
Warning The `Requires at least` field was ignored. This field should only contain a valid WordPress version …	Write the version as a number only, such as `6.5`.
Warning The `Requires PHP` field was ignored. This field should only contain a PHP version such as `7.0` or `8.2`.	Write the version as a number only: `7.4`, not `PHP 7.4`.
Warning The `Stable tag` field is missing or invalid. Note: We ask you no longer attempt to use `/trunk/` as stable, so that all plugins can be rolled back.	Set `Stable tag` to your released version, such as `1.0.0`, and make sure `tags/1.0.0/` exists in SVN.
Warning One or more tags were ignored: `security`. Please limit your plugin to 5 tags.	Keep your 5 most relevant tags; only the first 5 are used.
Warning One or more tags were ignored. The following tags are not permitted: `plugin`	Remove `plugin` and `wordpress` from Tags; every plugin has them.
Warning The `Short Description` section is too long and was truncated. A maximum of 150 characters is supported.	Shorten the line under the header to 150 characters or fewer.
Warning The `Description` section is too long and was truncated. A maximum of 2,500 words is supported.	Trim the section. Changelog and FAQ allow 5,000 words; move older changelog entries to `changelog.txt`.
Warning The following contributors listed were ignored, as the WordPress.org user could not be found. … The `Contributors` field should only contain WordPress.org usernames.	Use WordPress.org usernames, not display names or emails. Check each at `profiles.wordpress.org/username`.
Note The `Requires at least` field is missing. It should be defined here, or in your main plugin file.	Fine if your main plugin file has a `Requires at least:` header; otherwise add it to either file. `Requires PHP` works the same way.
Note The `Short Description` section is missing. An excerpt was generated from your main plugin description.	Add a one-line summary right after the header fields.
Note No `== Frequently Asked Questions ==` section was found	Optional. The same note appears for Changelog, Upgrade Notice and Screenshots; add them when you have something to put there.
Note No donate link was found	Optional. Add `Donate link:` if you accept donations.

Limits at a glance

Short description	150 characters
Tags	5
Each section	2,500 words
FAQ and Changelog	5,000 words each
Whole file	Keep it under about 10 KB; larger readmes may cause errors.

Sources: the WordPress.org plugin directory's readme parser and validator, which WPreadme.com runs, and How Your Readme.txt Works in the Plugin Handbook.