Using for a plugin on

Did you know that a plugin hosted on the Plugin Directory can use a markdown file instead of readme.txt? If you manage your plugin on GitHub or GitLab and use a file there’s no need to maintain or generate a separate readme.txt file — just send the file straight to

There are some caveats:

  • GitHub flavoured markdown isn’t supported – use regular markdown.
  • Status badges get (correctly) stripped out on, 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
  • 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 file that is used directly on 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 for a plugin on”

  1. Any idea if upper-cased is supported in addition to lower-cased

  2. Thank you for sharing. I was wondering for quite a while why we need to keep both 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 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.