{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…

[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 github repository 

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

[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 

One shortcode can do it all…

[eacReadme plugin='/pluginfolder/readme.txt']Document[/eacReadme] # loads the file and parses the entire document 

Or load the entire file as a single code block…

[eacReadme theme='/themefolder/functions.php']Code File[/eacReadme] 

Shortcode Examples

Get header values…

[eacReadme]Contributors[/eacReadme] [eacReadme]Donate link[/eacReadme] [eacReadme]Requires at least[/eacReadme] [eacReadme]Stable tag[/eacReadme] 

Get unnamed segments…

[eacReadme]Title[/eacReadme] # gets the '=== plugin name ===' line (before headers) [eacReadme]Short Description[/eacReadme] # gets the short description (between headers and first section block) 

Get section blocks…

[eacReadme]Description[/eacReadme] [eacReadme]Installation[/eacReadme] [eacReadme]Screenshots[/eacReadme] [eacReadme]Changelog[/eacReadme] 

Get multiple blocks and/or sub-sections…

[eacReadme plugin='/eacReadme/readme.txt']Short Description,Description[/eacReadme] [eacReadme plugin='/eacReadme/readme.txt']Short Description,Description/Shortcode Examples[/eacReadme] 

Get a file as a code block…

[eacReadme theme='/my-child-theme/functions.js' lang='js']Code File[/eacReadme] [eacReadme theme='/my-child-theme/style.css' lang='css']Code File[/eacReadme] 

Other Options

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

define('EAC_README_CACHE_LIFETIME',$seconds); # default: 1-day (DAY_IN_SECONDS). 

Override the default cache time-to-live

[eacReadme ttl=$seconds ...] # minimum: 1-minute (MINUTE_IN_SECONDS). 

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

define('GITHUB_ACCESS_TOKEN',$token); 

Set/override the GitHub access token

[eacReadme token=$token ...] 

Override option to parse markdown when retrieving a segment

[eacReadme parse='true|false' ...] 

Set class=’language-*’ on code blocks

[eacReadme lang='php|js|css|html' ...] 

Translating Header/Section Names

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

[eacReadme translate='name=newname,...'] [eacReadme translate='Requires at least=Requires WordPress Version,Screenshots=Screen Shots'] 

Erase default translation table

[eacReadme translate='no|none|false'] 

Default translation table

[ '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', ]; 

Readme Format

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

title

header: value header: value short Description<h3>section</h3> = sub-section = 

…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)
  • [email protected] – gravatar profile
  • profileId@wordpress – wordpress profile
  • profileId@gravatar – gravatar profile
  • profileId@github – github profile
  • [display name](mailto:[email protected]) 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> [](//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 …

[eacReadme]All Headers[/eacReadme] or `\eacParseReadme::getAllHeaders()` 

Or when retrieving all sections with …

[eacReadme]All Sections[/eacReadme] or `\eacParseReadme::getAllSections()` 

Or when retrieving the entire document with …

[eacReadme]Document[/eacReadme] or `\eacParseReadme::getDocument()` 

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…

 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 = 

• {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-2024, 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/.