Did you know that a plugin hosted on the WordPress.org Plugin Directory can use a
readme.md markdown file instead of
readme.txt? If you manage your plugin on GitHub or GitLab and use a
readme.md file there’s no need to maintain or generate a separate
readme.txt file — just send the
readme.md file straight to wordpress.org.
There are some caveats:
- GitHub flavoured markdown isn’t supported – use regular markdown.
- Status badges get (correctly) stripped out on wordpress.org, but they need to come below the short description otherwise everything breaks.
- You need to format your screenshot headings correctly (see example below).
- Backticks for code blocks won’t work, but indentation for code blocks will. Tilde (
~~~) fenced code blocks also work, and the syntax highlighting marker can be added as it is ignored on wordpress.org.
- Don’t forget two spaces need to come at the end of each of the headers at the top (“
Stable tag:” etc) so line breaks appear correctly on GitHub.
My User Switching repo uses a
readme.md file that is used directly on WordPress.org. Take a look at its formatting (via the “Raw” button) if you get stuck.
Why isn’t this documented in the Plugin Directory handbook?
I don’t know. This is a question for the WordPress meta team. This support was added way back in 2015 but hasn’t been publicised. There may be issues with certain markdown formatting and the team have a lot on their plates.