Using readme.md for a plugin on WordPress.org

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.

Example readme.md

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.

7 replies on “Using readme.md for a plugin on WordPress.org”

  1. Any idea if upper-cased README.md is supported in addition to lower-cased readme.md?

  2. 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.

    1. 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.

Comments are closed.