David Artiss

WordPress README files are formatted using a version of the Markdown language. This plugin can be used to convert these to XHTML and display on a post or page of your site.
It’s ideal for plugin developers who wish to add instructions to their own site without having to duplicate effort.
Key features include…
<ul>
<li>Convert your markdown README to XHTML and display in any post or page</li>
<li>Use shortcodes or a direct PHP function call</li>
<li>Responsive output of screenshots</li>
<li>Output is cached for maximum performance</li>
<li>Links automatically added to author and tag information</li>
<li>Download links added</li>
<li>Ability to specify which sections of the readme to exclude</li>
<li>Can also omit specific lines of text</li>
<li>Extra shortcodes available to display plugin banners and to return specific plugin data (download link, version number, etc)</li>
<li>Google Translation suppressed on code output</li>
<li>And much, much more!</li>
</ul>
Iconography is courtesy of <a href="https://www.freepik.com/flatart" rel="nofollow ugc">Flatart</a> ♥️
👉 Please visit the <a href="https://github.com/morehawes/plugin-readme-parser" title="Github" rel="nofollow ugc">Github page</a> for the latest code development, planned enhancements and known issues 👈
<h3>Getting Started</h3>
To use, simply add the <code>[readme]</code> shortcode to any post or page. An example of use would be…
<pre><code>[readme]WP README Parser[/readme]
</code></pre>
This would fetch and display the README for this plugin. You can also specify a filename instead.
The first heading, which is the name of the plugin, will be automatically suppressed as it is assumed that you have already added this to your post/page or are using it as the title.
<h3>Additional Shortcode Parameters</h3>
exclude
Each README is divided into a number of sections. If you wish to exclude any from the output then use this parameter to list them.
Before the first section (usually “Description”) is a number of pieces of “meta data” about the plugin, including tags, etc. Links are automatically added to these. If, however, you wish to just exclude this data then you should use the section name of “meta”. Underneath this data is a short description which will remain in this case. If you want to remove this description and the meta data then use the section name of “head”. If you wish to just remove a particular bit of meta data then specify <code>contributors</code>, <code>donate</code>, <code>tags</code>, <code>requires</code>, <code>license</code>, <code>license uri</code>, <code>tested</code> or <code>stable</code>.
For example…
<pre><code>[readme exclude="Meta,Changelog"]WP README Parser[/readme]
</code></pre>
This will display the entire README with the exception of the Changelog and the Plugin meta.
include
The opposite of <code>exclude</code> this allows you to specify ONLY the section that you wish to appear. So, using the example from above…
<pre><code>[readme include="Meta,Changelog"]WP README Parser[/readme]
</code></pre>
This will ONLY show the Meta and Changelog sections of the README file.
The only difference to the exclude command is that you can’t include just specific sections of the meta. If you believe that this option is required then please get in touch via the forum.
ignore
Different from <code>exclude</code> this allows to ignore specific lines of the README. Multiple lines should be separated by double commas (to allow single commas to be be used in the actual line to be ignored). For example…
<pre><code>[readme ignore="this line,,and this line"]WP README Parser[/readme]
</code></pre>
target
Any links will have a target of <code>_blank</code>. If you wish this to be anything else then change it with this parameter. For example…
<pre><code>[readme target="_self"]WP README Parser[/readme]
</code></pre>
nofollow
If you wish a link to have a nofollow option (i.e. the tag of <code>rel="nofollow"</code>) then specify this as “Yes”. By default it won’t. For example…
<pre><code>[readme nofollow="Yes"]WP README Parser[/readme]
</code></pre>
cache
This allows you to specify how long output should be cached for, in minutes. By default caching is set to 60 minutes. For example, to cache for 24 hours…
<pre><code>[readme cache=1440]WP README Parser[/readme]
</code></pre>
version
If you wish to display a specific version of the README, use this parameter to request it. For example…
<pre><code>[readme version=1.0]WP README Parser[/readme]
</code></pre>
mirror
If your plugin is hosted at a number of other locations then you can use this to specify alternative download URLs other than the WordPress repository. Simply seperate multiple URLs with double commas (i.e. ,,). For example…
<pre><code>[readme mirror="http://www.example1.com,,http://www.example2.com"]WP README Parser[/readme]
</code></pre>
links
By default download and other links will be added to the bottom of the README output. By specifying a section name via this parameter, however, then the links will appear before that section. For example, to appear before the description you’d put…
<pre><code>[readme links="description"]WP README Parser[/readme]
</code></pre>
name
If you specify a README filename instead a name then it will be assumed that the plugin name at the top of the README is the correct one. This may not be the case, however, if you’ve renamed your plugin (as is the case for this plugin). You can therefore use the <code>name</code> parameter to override this.
<pre><code>[readme name="WP README Parser"]https://plugins.svn.wordpress.org/wp-readme-parser/trunk/readme.txt[/readme]
</code></pre>
ext
The extension that your screenshots are stored as – i.e. PNG or JPG.
assets
Storing your screenshots in your assets folder? Then set this to ‘yes’ for them to be read from there. For example…
<pre><code>[readme assets="yes"]WP README Parser[/readme]<h3>Using Content Reveal</h3>
</code></pre>
If you also have the plugin <a href="https://wordpress.org/plugins/simple-content-reveal/" title="Content Reveal" rel="ugc">Content Reveal</a> installed, then each section of the README will be collapsable – that is, you can click on the section heading to hide the section content.
By default, all sections of the output will be revealed.
You may now use 3 further parameters when using the <code>[readme]</code> shortcode…
hide
Use this parameter to hide sections automatically – simply click on them to reveal them again.
For example…
<pre><code>[readme hide="Changelog"]WP README Parser[/readme]
</code></pre>
scr_url
If you wish to supply your own hide/reveal images then you can specify your own folder here.
The two images (one for when the content is hidden, another for when it’s shown) must be named image1 and image2. They can either by GIF or PNG images (see the next parameter).
For example…
<pre><code>[readme scr_url="https://artiss.blog”]WP README Parser[/readme]
</code></pre>
scr_ext
Use this specify whether you wish to use PNG or GIF images for your own hide/reveal images. If you do not specify it, GIF will be used.
For example…
<pre><code>[readme scr_url="https://artiss.blog" scr_ext="png"]WP README Parser[/readme]<h3>Using a Function Call</h3>
</code></pre>
If you wish to code a direct PHP call to the plugin, you can do. The function is named <code>readme_parser</code> and accepts 2 parameters. The first is an array of all the options, the same as the shortcode. The second parameter is the README name or filename.
For example…
<pre><code>echo readme_parser( array( 'exclude' => 'meta,upgrade notice,screenshots,support,changelog,links,installation,licence', 'ignore' => 'For help with this plugin,,for more information and advanced options ' ), 'YouTube Embed' );
</code></pre>
This may be of particular use to plugin developers as they can then display the README for their plugins within their administration screens.
<h3>Displaying the plugin banner</h3>
Some plugins have banners assigned to them. The shortcode <code>[readme_banner]</code> can be used to output them (responsively too). Between the opening and closing shortcode you must specify a plugin name (a URL can’t be used) and that’s it. For example…
<pre><code>[readme_banner]YouTube Embed[/readme_banner]
</code></pre>
If no banner image exists then nothing will be output.
<h3>Display specific README information</h3>
You may wish to add your own section to the output to provide download links, etc. In which case you can suppress this section and then use an additional shortcode to retrieve the information that you need.
Use the shortcode <code>[readme_info]</code> to return one of a number of different pieces of information. Use the required parameter <code>data</code> to specify what you need – this can b…
<ul>
<li>download – Display a download link</li>
<li>version – Output the current version number</li>
<li>forum – Display a link to the forum</li>
<li>wordpress – Display a link to the plugin in the WordPress.org repository</li>
</ul>
In the cases of the links you must specify text between the opening and closing shortcodes to link to.
There are 4 additional parameters…
<ul>
<li>name – Use this to specify the plugin name. This is a require parameter</li>
<li>target – If outputting a link this will assign a target to the output (default is _blank)</li>
<li>nofollow – If <code>Yes</code> then this will be a <code>nofollow</code> link. By default it won’t be</li>
<li>cache – By default any output will be cached for 50 minutes so that if you use this shortcode multiple times on a page the data will only be fetched once. Specify a different number (in minutes) to adjust this. Set to <code>No</code> to switch off caching entirely</li>
</ul>
An example of usage may be…
`[readme_info name=”YouTube Embed” data=”download”]Download YouTube Embed[/readme_info]’
<h3>Reviews & Mentions</h3>
<a href="http://wpcandy.com/reports/wp-readme-parser-plugin-converts-plugins-readme-into-blog-ready-xhtml?utm_source=feedburner&utm_medium=feed&utm_campaign=Feed%3A+wpcandy+%28WPCandy+-+The+Best+of+WordPress%29" title="WPCandy" rel="nofollow ugc">WPCandy</a> – WP README Parser Plugin converts Plugin’s readme into blog-ready XHTML
<h3>Acknowledgements</h3>
Plugin README Parser uses <a href="http://michelf.com/projects/php-markdown/extra/" title="PHP Markdown Extra" rel="nofollow ugc">PHP Markdown Extra</a> by Michel Fortin.

Plugin README Parser

Sooner or later, if you develop WordPress plugins that are being offered here at the Plugin Library, you will need this plugin — simply because it makes it so easy to include those Markdown-based READMEs as part of your own website.

Sooner or later, someone will contact you with lots of questions about your own plugins, and you'll want to let them know, on your own website, what you have developed so far.

Sure, you can always do a copy & paste; sure, recent versions of WordPress are sort-of-able to parse Markdown, so, strictly speaking, you could do everything manually.

But with the Plugin README Parser, everything happens automagically. No need to set a reminder to yourself to update your own pages on your site — this plugin will automatically contact the Plugin Library and regenerate those pages based on the latest and greatest version of the README.

And, as a bonus, it even retrieves most of the assets — such as images etc. — that are used by the README to illustrate, for example, how your plugin installation works. This is not 100% trivial to do manually. It's good to have a fully automated tool that does all the homework on your behalf!

A must for WordPress plugin developers, amateurs or pros!


I use the plugin to display a the changelog from my plugin readme on my site's changes page very handy to only have one changelog to update!



Thanks,



Joe


Very Handy!


Works fine again!Thanks for keeping it up-to-date


Great plugin!

Kevin Burkholder

{eac}Readme is an <a href="https://eacDoojigger.earthasylum.com/" rel="nofollow ugc">{eac}Doojigger</a> extension which loads and translates a WordPress markdown ‘readme’ file providing shortcodes and embedding URLs to access header lines and section blocks.
<h4>Shortcode Usage</h4>
The first used shortcode must indicate the file to load…
<pre><code>[eacReadme file='/docfolder/readme.txt'] # file is relative to the WordPress document root folder
[eacReadme content='/contentfolder/readme.txt'] # content file is relative to the WordPress content folder (wp-content/)
[eacReadme plugin='/pluginfolder/readme.txt'] # plugin file is relative to the WordPress plugins folder (wp-content/plugins/)
[eacReadme theme='/themefolder/readme.txt'] # theme file is relative to the WordPress themes folder (wp-content/themes/)
[eacReadme wpsvn='/slugname/trunk/readme.txt'] # load file from WordPress SVN repository
[eacReadme github='/owner/repository/main/readme.txt'] # load file from a github repository
</code></pre>
After which, headers and sections may be pulled from that file…
<pre><code>[eacReadme]All Headers[/eacReadme] # parses all header lines
[eacReadme]headerName[/eacReadme] # gets the value of the named header line

[eacReadme]All Sections[/eacReadme] # parses all section blocks
[eacReadme]sectionName[/eacReadme] # parses the content of the named section block
[eacReadme]sectionName/sub-section[/eacReadme] # parses the content of the named sub-section within section block
</code></pre>
One shortcode can do it all…
<pre><code>[eacReadme plugin='/pluginfolder/readme.txt']Document[/eacReadme] # loads the file and parses the entire document
</code></pre>
Or load the entire file as a single code block…
<pre><code>[eacReadme theme='/themefolder/functions.php']Code File[/eacReadme]
</code></pre>
<h4>Shortcode Examples</h4>
Get header values…
<pre><code>[eacReadme]Contributors[/eacReadme]
[eacReadme]Donate link[/eacReadme]
[eacReadme]Requires at least[/eacReadme]
[eacReadme]Stable tag[/eacReadme]
</code></pre>
Get unnamed segments…
<pre><code>[eacReadme]Title[/eacReadme] # gets the '=== plugin name ===' line (before headers)
[eacReadme]Short Description[/eacReadme] # gets the short description (between headers and first section block)
</code></pre>
Get section blocks…
<pre><code>[eacReadme]Description[/eacReadme]
[eacReadme]Installation[/eacReadme]
[eacReadme]Screenshots[/eacReadme]
[eacReadme]Changelog[/eacReadme]
</code></pre>
Get multiple blocks and/or sub-sections…
<pre><code>[eacReadme plugin='/eacReadme/readme.txt']Short Description,Description[/eacReadme]
[eacReadme plugin='/eacReadme/readme.txt']Short Description,Description/Shortcode Examples[/eacReadme]
</code></pre>
Get a file as a code block…
<pre><code>[eacReadme theme='/my-child-theme/functions.js' lang='js']Code File[/eacReadme]
[eacReadme theme='/my-child-theme/style.css' lang='css']Code File[/eacReadme]
</code></pre>
<h4>Other Options</h4>
Change the default cache time-to-live by adding to wp-config.php:
<pre><code>define('EAC_README_CACHE_LIFETIME',$seconds); # default: 1-day (DAY_IN_SECONDS).
</code></pre>
Override the default cache time-to-live
<pre><code>[eacReadme ttl=$seconds ...] # minimum: 1-minute (MINUTE_IN_SECONDS).
</code></pre>
Set the default GitHub access token (for private repositories):
<pre><code>define('GITHUB_ACCESS_TOKEN',$token);
</code></pre>
Set/override the GitHub access token
<pre><code>[eacReadme token=$token ...]
</code></pre>
Override option to parse markdown when retrieving a segment
<pre><code>[eacReadme parse='true|false' ...]
</code></pre>
Set class=’language-*’ on code blocks
<pre><code>[eacReadme lang='php|js|css|html' ...]
</code></pre>
<h4>Translating Header/Section Names</h4>
Translate header/section names when retrieving All Headers, All Sections, or Document
<pre><code>[eacReadme translate='name=newname,...']
[eacReadme translate='Requires at least=Requires WordPress Version,Screenshots=Screen Shots']
</code></pre>
Erase default translation table
<pre><code>[eacReadme translate='no|none|false']
</code></pre>
Default translation table
<pre><code>[
 'Headers' => 'Document Header',
 'Plugin URI' => 'Homepage',
 'Stable tag' => 'Current Version',
 'Requires at least' => 'Requires WordPress Version',
 'Tested up to' => 'Compatible up to',
 'Requires PHP' => 'Requires PHP Version',
 'WC requires at least' => 'Requires WooCommerce',
 'Requires EAC' => 'Requires {eac}Doojigger',
 'Changelog' => 'Change Log',
 'Screenshots' => 'Screen Shots',
];
</code></pre>
<h4>Embedding</h4>
{eac}Readme can also be used to embed URLs in a WordPress Post or Page. Simply paste the url in the <code>Embed</code> URL block.
<ul>
<li>Navigate to the post or page where the readme content is to be embedded.</li>
<li>Click the ‘+’ (Block Inserter) icon and search for “Embed” or type /embed.</li>
<li>Select the “Embed” block.</li>
<li>Paste the URL to the readme file into the provided field.</li>
<li>Click the “Embed” button. WordPress will automatically display the unformatted content.</li>
</ul>
The shortcut to this is to simply paste the URL at the end of the page/post where it says “Type / to choose a block”. WordPress will automatically convert your URL to an embed block.
Files can be embedded from your site, from the WordPress repository or from Github. Embedded URLs are transformed internally to the appropriate format.
From your site
<pre><code>https://<your_site_url>/plugins/<plugin_slug>/readme.txt
https://<your_site_url>/themes/<theme_name>/readme.txt
</code></pre>
From the WordPress Repository
<pre><code>https://ps.w.org/<plugin_slug>/readme.txt
https://plugins.svn.wordpress.org/<plugin_slug>/readme.txt
</code></pre>
From a GitHub Repository
<pre><code>https://github.com/<owner>/<repository>/blob/main/readme.md
https://github.com/<owner>/<repository>/main/readme.md
</code></pre>
To load only specific sections of the readme file, append a fragment to the url:
<pre><code>https://<your_site_url>/plugins/<plugin_slug>/readme.txt#allheaders
https://ps.w.org/<plugin_slug>/readme.txt#description
https://github.com/<owner>/<repository>/main/readme.md#screenshots
</code></pre>
<h4>Readme Format</h4>
{eac}Readme expects a well-formed readme.txt file that follows the <a href="https://developer.wordpress.org/plugins/wordpress-org/how-your-readme-txt-works" rel="nofollow ugc">WordPress readme file standard</a>…
<h3>title</h3>
<pre><code>header: value
header: value
short Description<h3>section</h3> = sub-section =
</code></pre>
…but supports some extensions to that standard:
<ul>
<li>
Author & Author URI
<ul>
<li><code>Author</code> header may be a simple name or a markdown link:
<ul>
<li><code>[Author](Author URI)</code>.</li>
</ul>
</li>
<li>The <code>Author</code> & <code>Author URI</code> headers, if present, are combined as a markdown <code>[Author](Author URI)</code>.</li>
</ul>
</li>
<li>
Homepage
<ul>
<li>Looks for <code>Homepage</code> or <code>Plugin URI</code>.</li>
</ul>
</li>
<li>
Version
<ul>
<li>Looks for <code>Version</code> or <code>Stable tag</code>.</li>
</ul>
</li>
<li>
Contributors
<ul>
<li><code>profileId</code> – wordpress profile (standard)</li>
<li><code>profileId@youremaildomain.com</code> – gravatar profile</li>
<li><code>profileId@wordpress</code> – wordpress profile</li>
<li><code>profileId@gravatar</code> – gravatar profile</li>
<li><code>profileId@github</code> – github profile</li>
<li><code>[display name](mailto:email@address.com)</code> or <code>[display name](http://www.gravatar.com/profileId/)</code></li>
<li><code>[display name](https://profiles.wordpress.org/profileId/)</code></li>
<li><code>[your name]((http://your/profile/url)</code></li>
</ul>
</li>
<li>
A “banner” section may be included between the top title line and the first header line.
<code><h3>title</h3> [![banner](//image_url)](//link_url) 
header: value 
header: value 
short Description<h3>section</h3> = sub-section =</code>
</li>
<li>
The header block may be enclosed in an html <code><header></code> or <code><details></code> tag, opening and closing each on a single line. These tags are ignored by the eacParseReadme parser but may be beneficial if posting your readme file elseware. See <a href="https://github.com/EarthAsylum/eacReadme" rel="nofollow ugc">{eac}Readme on Github</a>.
</li>
</ul>
<blockquote>
Note: these extensions are not supported by the WordPress Plugin Repository.
</blockquote>
{eac}Readme supports standard markdown (readme.md) formatting for section identification. 
+ <code>=== title ===</code> and <code>## title</code> are equivalent 
+ <code>== section ==</code> and <code>### section</code> are equivalent 
+ <code>= sub-section =</code> and <code>#### sub-section</code> are equivalent
<h4>Output HTML</h4>
When retrieving the header block with …
<pre><code>[eacReadme]All Headers[/eacReadme] or `\eacParseReadme::getAllHeaders()`
</code></pre>
Or when retrieving all sections with …
<pre><code>[eacReadme]All Sections[/eacReadme] or `\eacParseReadme::getAllSections()`
</code></pre>
Or when retrieving the entire document with …
<pre><code>[eacReadme]Document[/eacReadme] or `\eacParseReadme::getDocument()`
</code></pre>
Additional html tags and classes are added, including wrapping blocks within a <code><details></code> tags, adding <code>readme-*</code> class names, and adding <code><a></code> anchor links.
<h4>WordPress Actions</h4>
3rd-party actors may load and use the parser class included in {eac}Readme…
<pre><code> do_action('eacReadme_load_parser'); // loads \eacParseReadme static class
 if (class_exists('\eacParseReadme'))
 {
 \eacParseReadme::loadFile($readme,$context);
 $html_document = \eacParseReadme::getDocument();
 $title = \eacParseReadme::getTitle();
 $version = \eacParseReadme::getVersion();
 $donations = \eacParseReadme::getHeader('donate_link');
 $description = \eacParseReadme::getSection('description');
 }= Additional Information =
</code></pre>
<ul>
<li>{eac}Readme is an extension plugin to and requires installation and registration of <a href="https://eacDoojigger.earthasylum.com/" rel="nofollow ugc">{eac}Doojigger</a>.</li>
<li>{eac}Readme uses <a href="http://parsedown.org/" rel="nofollow ugc">Parsedown 1.7.4</a>, Copyright (c) 2013-2018 <a href="erusev.com" rel="nofollow ugc">Emanuil Rusev</a></li>
<li>
{eac}Readme uses <a href="https://prismjs.com/" rel="nofollow ugc">Prism syntax highlighter</a>, Copyright (c) 2012 Lea Verou
</li>
<li>
The <a href="https://swregistry.earthasylum.com/software-taxonomy/" rel="nofollow ugc">{eac}SoftwareRegistry Software Product Taxonomy</a> plugin uses {eac}Readme to parse readme markdown files hosted on Github to provide plugin information and automated updates to WordPress for self-hosted plugins.
</li>
</ul>
<h3>Copyright</h3>
<h4>Copyright © 2019-2025, EarthAsylum Consulting, distributed under the terms of the GNU GPL.</h4>
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should receive a copy of the GNU General Public License along with this program. If not, see <a href="https://www.gnu.org/licenses/" rel="nofollow ugc">https://www.gnu.org/licenses/</a>.

{eac}Doojigger Readme Extension for WordPress

{eac}Readme loads and translates a WordPress markdown 'readme' file providing shortcodes and embedding URLs to access header lines and section blocks.

Plugin README Parser vs {eac}Doojigger Readme Extension for WordPress