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.
Any idea if upper-cased
README.mdis supported in addition to lower-cased
I don’t know, sorry!
It looks like the answer is yes! I just tried it with https://wordpress.org/plugins/lazy-loading-oembed-iframes/
Only README.md is committed: https://plugins.trac.wordpress.org/browser/lazy-loading-oembed-iframes/trunk
Thank you for sharing. I was wondering for quite a while why we need to keep both README.md and readme.txt in the Gutenberg plugin. Now, there is hope we could consolidate it.
We have both in Jetpack since they serve different audiences. We kept the `.txt` focused on what we’d want someone browsing via w.org or wp-admin to see and `.md` has more developer-focused material.
As we’re putting together some skeletons for future projects, though, on the fence about needing to continue that or not.
How does your changelog get generated? I see in your readme.md on github, but the SVN repo has the full list: https://plugins.svn.wordpress.org/user-switching/trunk/readme.md
The readme.md contains an HTML comment at the bottom that gets replaced with the release notes that are fetched from the GitHub API. Details here: