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

Kevin Burkholder

<p><em>{eac}Readme</em> 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.</p>
<h4>Shortcode Usage</h4>
<p>The first used shortcode must indicate the file to load…</p>
<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>
<p>After which, headers and sections may be pulled from that file…</p>
<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>
<p>One shortcode can do it all…</p>
<pre><code>[eacReadme plugin='/pluginfolder/readme.txt']Document[/eacReadme]    # loads the file and parses the entire document
</code></pre>
<p>Or load the entire file as a single code block…</p>
<pre><code>[eacReadme theme='/themefolder/functions.php']Code File[/eacReadme]
</code></pre>
<h4>Shortcode Examples</h4>
<p>Get header values…</p>
<pre><code>[eacReadme]Contributors[/eacReadme]
[eacReadme]Donate link[/eacReadme]
[eacReadme]Requires at least[/eacReadme]
[eacReadme]Stable tag[/eacReadme]
</code></pre>
<p>Get unnamed segments…</p>
<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>
<p>Get section blocks…</p>
<pre><code>[eacReadme]Description[/eacReadme]
[eacReadme]Installation[/eacReadme]
[eacReadme]Screenshots[/eacReadme]
[eacReadme]Changelog[/eacReadme]
</code></pre>
<p>Get multiple blocks and/or sub-sections…</p>
<pre><code>[eacReadme plugin='/eacReadme/readme.txt']Short Description,Description[/eacReadme]
[eacReadme plugin='/eacReadme/readme.txt']Short Description,Description/Shortcode Examples[/eacReadme]
</code></pre>
<p>Get a file as a code block…</p>
<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>
<p>Change the default cache time-to-live by adding to wp-config.php:</p>
<pre><code>define('EAC_README_CACHE_LIFETIME',$seconds);   # default: 1-day (DAY_IN_SECONDS).
</code></pre>
<p>Override the default cache time-to-live</p>
<pre><code>[eacReadme ttl=$seconds ...]                    # minimum: 1-minute (MINUTE_IN_SECONDS).
</code></pre>
<p>Set the default GitHub access token (for private repositories):</p>
<pre><code>define('GITHUB_ACCESS_TOKEN',$token);
</code></pre>
<p>Set/override the GitHub access token</p>
<pre><code>[eacReadme token=$token ...]
</code></pre>
<p>Override option to parse markdown when retrieving a segment</p>
<pre><code>[eacReadme parse='true|false' ...]
</code></pre>
<p>Set class=’language-*’ on code blocks</p>
<pre><code>[eacReadme lang='php|js|css|html' ...]
</code></pre>
<h4>Translating Header/Section Names</h4>
<p>Translate header/section names when retrieving <em>All Headers</em>, <em>All Sections</em>, or <em>Document</em></p>
<pre><code>[eacReadme translate='name=newname,...']
[eacReadme translate='Requires at least=Requires WordPress Version,Screenshots=Screen Shots']
</code></pre>
<p>Erase default translation table</p>
<pre><code>[eacReadme translate='no|none|false']
</code></pre>
<p>Default translation table</p>
<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>
<p>{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.</p>
<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>
<p>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.</p>
<p>Files can be embedded from your site, from the WordPress repository or from Github. Embedded URLs are transformed internally to the appropriate format.</p>
<p><em>From your site</em></p>
<pre><code>https://<your_site_url>/plugins/<plugin_slug>/readme.txt
https://<your_site_url>/themes/<theme_name>/readme.txt
</code></pre>
<p><em>From the WordPress Repository</em></p>
<pre><code>https://ps.w.org/<plugin_slug>/readme.txt
https://plugins.svn.wordpress.org/<plugin_slug>/readme.txt
</code></pre>
<p><em>From a GitHub Repository</em></p>
<pre><code>https://github.com/<owner>/<repository>/blob/main/readme.md
https://github.com/<owner>/<repository>/main/readme.md
</code></pre>
<p><em>To load only specific sections of the readme file, append a fragment to the url:</em></p>
<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>
<p>{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>…</p>
<h3>title</h3>
<pre><code>header: value
header: value
short Description<h3>section</h3>    = sub-section =
</code></pre>
<p>…but supports some extensions to that standard:</p>
<ul>
<li>
<p>Author & Author URI</p>
<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>
<p>Homepage</p>
<ul>
<li>Looks for <code>Homepage</code> or <code>Plugin URI</code>.</li>
</ul>
</li>
<li>
<p>Version</p>
<ul>
<li>Looks for <code>Version</code> or <code>Stable tag</code>.</li>
</ul>
</li>
<li>
<p>Contributors</p>
<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>
<p>A “banner” section may be included between the top title line and the first header line.</p>
<p><code><h3>title</h3>   [![banner](//image_url)](//link_url)<br />
header: value<br />
header: value<br />
short Description<h3>section</h3>    = sub-section =</code></p>
</li>
<li>
<p>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>.</p>
</li>
</ul>
<blockquote>
<p>Note: these extensions are not supported by the WordPress Plugin Repository.</p>
</blockquote>
<p>{eac}Readme supports standard markdown (readme.md) formatting for section identification.<br />
+   <code>=== title ===</code> and <code>## title</code> are equivalent<br />
+   <code>== section ==</code> and <code>### section</code> are equivalent<br />
+   <code>= sub-section =</code> and <code>#### sub-section</code> are equivalent</p>
<h4>Output HTML</h4>
<p>When retrieving the header block with …</p>
<pre><code>[eacReadme]All Headers[/eacReadme] or `\eacParseReadme::getAllHeaders()`
</code></pre>
<p>Or when retrieving all sections with …</p>
<pre><code>[eacReadme]All Sections[/eacReadme] or `\eacParseReadme::getAllSections()`
</code></pre>
<p>Or when retrieving the entire document with …</p>
<pre><code>[eacReadme]Document[/eacReadme] or `\eacParseReadme::getDocument()`
</code></pre>
<p>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.</p>
<h4>WordPress Actions</h4>
<p>3rd-party actors may load and use the parser class included in {eac}Readme…</p>
<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>
<p>{eac}Readme uses <a href="https://prismjs.com/" rel="nofollow ugc">Prism syntax highlighter</a>, Copyright (c) 2012 Lea Verou</p>
</li>
<li>
<p>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.</p>
</li>
</ul>
<h3>Copyright</h3>
<h4>Copyright © 2019-2025, EarthAsylum Consulting, distributed under the terms of the GNU GPL.</h4>
<p>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.</p>
<p>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.</p>
<p>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>.</p>


Alternatives to {eac}Doojigger Readme Extension for WordPress

Top alternatives