BucketWP
Browse Tools
Menu

Plugin readme.txt Validator and Previewer

Check a plugin readme.txt against what WordPress.org actually reads, and see the plugin page it would build, before you commit it.

Enable JavaScript to check your own readme.txt; the report below is for the example.

Nothing is uploaded. The checking happens in this tab.

3 warnings · 8 notes

  • 1 note Missing Requires PHP. Requires PHP stops the plugin installing where it would fatal.
  • 1 note No == Frequently Asked Questions == section. An FAQ section becomes the FAQ tab.
  • 1 note No == Installation == section. Installation is a tab on the plugin page.
  • 1 note No == Screenshots == section. Screenshot captions come from this section.
  • 3 warning 6 tags given; WordPress.org uses the first 5 and drops the rest.
  • 3 note The tag "wordpress" matches every plugin in the directory, so it sorts nothing.
  • 5 note Tested up to reads the first two numbers, so "6.8.1" is the same as "6.8".
  • 6 note Stable tag: trunk ships every commit. A version number ships only what you tagged.
  • 7 note License is set but License URI is not, so the licence is not linked.
  • 18 warning The changelog has no = version = headings, so no release can be linked to.
  • 22 warning Upgrade Notice needs a = version = heading per release; text on its own is never shown.

Nothing in this readme will render wrong or be dropped.

Contact Bucket

A contact form for WordPress that blocks spam without a captcha, without an account, and without sending anything to a third party.

Contributors
litonarefin
Tags
contact form, spam, honeypot, wordpress, forms, email
Requires at least
6.5
Tested up to
6.8.1
Stable tag
trunk
License
GPLv2 or later

Description

One form, one shortcode, and a honeypot that catches most of it. Nothing leaves the site.

Works in the block editor and in classic themes

Stores entries in the database, not in an external service

Changelog

Fixed the honeypot.

Upgrade Notice

Update if you use the shortcode.

readme-report.txt 
readme.txt — Contact Bucket

Stable tag trunk · Tested up to 6.8.1 · Requires at least 6.5
Sections: Description, Changelog, Upgrade Notice

3 warnings · 8 notes

   1  note     Missing Requires PHP. Requires PHP stops the plugin installing where it would fatal.
   1  note     No == Frequently Asked Questions == section. An FAQ section becomes the FAQ tab.
   1  note     No == Installation == section. Installation is a tab on the plugin page.
   1  note     No == Screenshots == section. Screenshot captions come from this section.
   3  warning  6 tags given; WordPress.org uses the first 5 and drops the rest.
   3  note     The tag "wordpress" matches every plugin in the directory, so it sorts nothing.
   5  note     Tested up to reads the first two numbers, so "6.8.1" is the same as "6.8".
   6  note     Stable tag: trunk ships every commit. A version number ships only what you tagged.
   7  note     License is set but License URI is not, so the licence is not linked.
  18  warning  The changelog has no = version = headings, so no release can be linked to.
  22  warning  Upgrade Notice needs a = version = heading per release; text on its own is never shown.

readme.txt is the only file in a plugin whose mistakes cost something and warn nobody. PHP errors on a typo. theme.json fails schema validation. readme.txt just quietly renders: a short description one character too long is cut mid-word in every search result, a Stable tag that names no tag falls back to trunk, and an Upgrade Notice written as plain text is never shown to anyone.

This checks the file against what WordPress.org reads, and shows the plugin page it would build from it.

How to use

  1. Paste the whole readme.txt, headers and all. The first line has to be === Plugin Name ===; without it nothing below is read as a readme.
  2. Read the report. Problems change what the directory serves or shows. Warnings change the plugin page. Notes are things that work but read badly.
  3. Read the preview underneath. Sections are shown in the order the plugin page puts them, with the markdown flattened to the plain text it renders as, so a heading that did not parse is obvious: it turns up as body text.
  4. Untick Include notes once the problems are gone, to see whether anything is left.

Nothing is uploaded. The file is parsed in the tab, so an unreleased plugin can be checked against the rules without leaving the browser.

Example

A readme that looks finished and is not:

=== Contact Bucket ===
Tags: contact form, spam, honeypot, wordpress, forms, email
Tested up to: 6.8.1
Stable tag: trunk

A contact form.

== Changelog ==

Fixed the honeypot.

Six things come back, and only one of them is a typo:

  • Tags has six entries. WordPress.org uses the first five and drops the rest, so email never indexes.
  • wordpress as a tag matches every plugin in the directory, so it sorts nothing.
  • Tested up to: 6.8.1 reads as 6.8. The third number is ignored, so the patch release it was actually tested against is not recorded anywhere.
  • Stable tag: trunk ships every commit to every install. A version number ships only what was tagged.
  • Requires at least is missing, so an install on older WordPress is offered an update that may not run.
  • The changelog has no = 1.0 = heading, so there is no release to link to and the Updates screen has nothing to show.

Fixing the changelog is one line:

== Changelog ==

= 1.0.1 =
* Fixed the honeypot.

Pitfalls

The short description is the second paragraph, not the second line. Anything after a blank line is dropped rather than moved into the description, so a two-paragraph opening loses the second half silently.

150 characters is a hard cut. Not a warning, not an ellipsis at a word boundary: WordPress.org truncates the string and that is what appears in search results and in the plugin’s card.

Upgrade Notice needs a = version = heading per release. Without one the text is parsed as the section body and shown nowhere, which is why upgrade notices so often appear to be ignored.

Contributors takes WordPress.org usernames. A display name or an email address links to no profile, and the plugin never appears on anyone’s profile page.

Screenshot captions are matched by number, not by order. 1. is screenshot-1.png. Skip a number in the list and the images shift under the captions.

Headings are closed, not opened. == Description with no trailing == is body text, and the section it was meant to open becomes part of whatever came before it.

Compatibility

The rules here follow the readme format WordPress.org has used since the directory moved to the current plugin pages, and were checked against WordPress 6.5 through 6.8. Header names are matched case-insensitively, as WordPress.org matches them.

Two details are deliberately stricter than the directory: Stable tag: trunk is reported as a note rather than accepted silently, and a missing Requires PHP is mentioned, because without it the plugin installs where it will fatal.

The checking runs in the browser, in any version that ships the Interactivity API runtime WordPress 6.5 introduced. The report is plain text, so it can go straight into a commit message or a code review.

Frequently asked questions

Does this upload my readme.txt anywhere?
No. The parsing happens in the page. The textarea’s contents are never sent to a server, which is the point: an unreleased plugin can be checked before the first commit.
Is a clean report the same as a readme WordPress.org will accept?
No. This checks the format, not the plugin. The review team also reads the description, the licence claim and the code. A clean report means nothing here will render wrong or be dropped.
Why is my Tested up to: 6.8.1 only a note?
Because it works, it just says less than it looks like it does. WordPress.org compares the first two numbers, so 6.8.1 and 6.8 are the same value. If the patch release matters, put it in the changelog where it will be read.
Can I check a theme’s readme.txt with this?
Mostly. Themes use the same header block and section syntax, so the structural checks hold, but a theme readme has no Stable tag and needs no Upgrade Notice, so those two lines can be ignored.
What does the preview leave out?
Inline formatting. Bold, links and inline code are flattened to plain text, with a link’s target shown in brackets after it, because the preview’s job is to show which headings parsed and what order the sections are in.

Related tools

Tools that pair with this one, then more from the same toolbox.

Explore all tools

Tools

Plugin readme.txt Generator

Write the readme.txt WordPress.org reads: header fields, the sections the listing renders, changelog entries and FAQ pairs.

PLUGIN

Plugin Header Generator

Generate the plugin file header WordPress reads, with the version requirements, text domain, update URI and the ABSPATH guard.

PLUGIN

Theme readme.txt Generator

Generate a WordPress.org theme readme.txt: the header block, description, changelog, and the resource attributions the review requires.

THEME

Register & Enqueue Script Generator

Generate wp_enqueue_script() code with dependencies, a cache-busting version, footer loading, conditional context and wp_localize_script data.

PLUGIN

From the people who built this tool

WP Adminify

The WordPress admin, rebuilt: a dashboard worth looking at, menu and column control, a real file manager and the login page your client sees.

See WP Adminify Free version on WordPress.org

Weekly drops

New tools, when there are new tools

One email when something worth using ships. No schedule to fill, so no filler.

Your address goes nowhere else, and one click unsubscribes.