A WordPress readme.txt is the file that controls how your plugin appears on WordPress.org, so getting its format right matters before you submit. It uses a markdown-like syntax that is not standard markdown, and a single broken line can mangle your listing page. Here is how to write one correctly and check it first.
The readme.txt header block
Every readme starts with a plugin name as an === Plugin Name === line, followed by a header block of field-value pairs. The important fields are:
- Contributors: comma-separated WordPress.org usernames, not display names.
- Tags: a few relevant terms (keep it short, the directory limits how many it shows).
- Requires at least: the oldest WordPress version your plugin supports.
- Tested up to: the latest WordPress version you have tested against.
- Stable tag: the version in your SVN trunk or tags folder that users actually download.
- License and License URI: usually GPLv2 or later.
Two of these decide a lot. Stable tag tells WordPress.org which version to serve, so if it points at the wrong tag, users get the wrong code. Tested up to signals compatibility, and an outdated value makes your plugin look abandoned and can trigger a warning on the listing.
The required sections
Below the header come sections, each marked by == Section Name ==. The directory expects:
== Description ==== Installation ==== Frequently Asked Questions ==== Screenshots ==== Changelog ==
A short summary line under the header (160 characters or less) becomes the tagline shown in search results. Inside sections you can use a limited markup: = headings, * bullet lists, backticks for inline code, and links. This is its own format, not full markdown, so things like tables or fenced code blocks will not render the way you expect.
Preview before you submit
The fastest way to catch a malformed header or a section that will not render is to preview the file before it goes live. Paste your readme into the WordPress Readme Preview and check that the header fields parse, the sections appear in order, and your changelog reads cleanly.
- Open the WordPress Readme Preview and paste your full readme.txt.
- Confirm the header block parses and Stable tag, Tested up to, and Requires at least all show the right values.
- Check each
== Section ==renders as its own block with no leftover markup characters. - Fix anything that looks off, then copy the corrected text back into your file.
Everything runs in your browser, so your readme never leaves your device.
Common mistakes to avoid
- Writing display names instead of usernames in Contributors.
- Forgetting to bump Tested up to after a new WordPress release.
- Using
#markdown headings instead of the=and==style. - A Stable tag that does not match an actual tag in your SVN.
Related tools
- Markdown to HTML: convert real markdown when you need actual HTML output.
- Markdown Viewer: render and read standard markdown files in the browser.
- WordPress Snippet Generator: scaffold the PHP that ships alongside your plugin.
Write it once, preview it before you submit, and your plugin page lands clean on the first try.