{eac}Doojigger Readme Extension for WordPress

{eac}Readme is an {eac}Doojigger extension which loads and translates a WordPress markdown ‘readme.txt’ file providing shortcodes to access header lines and section blocks.

Shortcode Usage

The first used shortcode must indicate the file to load…

After which, headers and sections may be pulled from that file…

One shortcode can do it all…

Or load the entire file as a single code block…

Shortcode Examples

Get header values…

Get unnamed segments…

Get section blocks…

Get multiple blocks and/or sub-sections…

Get a file as a code block…

Other Options

Change the default cache time-to-live by adding to wp-config.php:

Override the default cache time-to-live

Set the default GitHub access token (for private repositories):

Set/override the GitHub access token

Override option to parse markdown when retrieving a segment

Set class=’language-*’ on code blocks

Translating Header/Section Names

Translate header/section names when retrieving All Headers, All Sections, or Document

Erase default translation table

Default translation table

Readme Format

{eac}Readme expects a well-formed readme.txt file that follows the WordPress readme file standard…

title

…but supports some extensions to that standard:

• Author & Author URI

  • Author header may be a simple name or a markdown link:
    • [Author](Author URI).
  • The Author & Author URI headers, if present, are combined as a markdown [Author](Author URI).

• Homepage

  • Looks for Homepage or Plugin URI.

• Version

  • Looks for Version or Stable tag.

• Contributors

  • profileId – wordpress profile (standard)
  • profileId@youremaildomain.com – gravatar profile
  • profileId@wordpress – wordpress profile
  • profileId@gravatar – gravatar profile
  • profileId@github – github profile
  • [display name](mailto:email@address.com) or [display name](http://www.gravatar.com/profileId/)
  • [display name](https://profiles.wordpress.org/profileId/)
  • [your name]((http://your/profile/url)

• A “banner” section may be included between the top title line and the first header line.

  <h3>title</h3> [![banner](//image_url)](//link_url)
header: value
header: value
short Description<h3>section</h3> = sub-section =

• The header block may be enclosed in an html <header> or <details> 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 {eac}Readme on Github.

Note: these extensions are not supported by the WordPress Plugin Repository.

{eac}Readme supports standard markdown (readme.md) formatting for section identification.
+ === title === and ## title are equivalent
+ == section == and ### section are equivalent
+ = sub-section = and #### sub-section are equivalent

Output HTML

When retrieving the header block with …

Or when retrieving all sections with …

Or when retrieving the entire document with …

Additional html tags and classes are added, including wrapping blocks within a <details> tags, adding readme-* class names, and adding <a> anchor links.

WordPress Actions

3rd-party actors may load and use the parser class included in {eac}Readme…

• {eac}Readme is an extension plugin to and requires installation and registration of {eac}Doojigger.
• {eac}Readme uses Parsedown 1.7.4, Copyright (c) 2013-2018 Emanuil Rusev

• {eac}Readme uses Prism syntax highlighter, Copyright (c) 2012 Lea Verou

• The {eac}SoftwareRegistry Software Product Taxonomy 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.

Copyright

Copyright ? 2019-2025, EarthAsylum Consulting, distributed under the terms of the GNU GPL.

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 https://www.gnu.org/licenses/.