TineL Markdown Macros

A Pico CMS plugin to allow you to create powerful macros that can be embedded in Markdown pages.

It simplifies writing a bunch of repetitive HTML code with a custom tag.

This plugin has been inspired by MarkdownMacros. Thanks!

Description

This plugin adds a possibility to create any custom 'tag' for Markdown. The tag is a regular expression pattern, which is replaced with any code (presumably HTML but can be Markdown too) you specify in a separate configuration, after the page content has been loaded and before it is prepared.

The fact that tags are regular expressions gives you the ability to write powerful patterns and replacements.

Usage

Each line in the tinel_markdown_macros setting represents one macro. Each line is actually an entry in the YAML map with tag being the key and replacement code being the value.

The syntax of the tag can be whatever you want as long as it compiles to a regular expression pattern. The known regex characters have to be escaped.

See this example:

# Map of Markdown macros: the key is a regex search pattern, which is matched with the whole content of page and is replaced (applying regex) with the value
tinel_markdown_macros:
  '{m:infobox}': '<div class="tlNotices blue">'
  '{\/m:infobox}': '</div>'
  '{m:reflink=([^}]+)}': '<sup>\[[$1](#reference:$1)\]</sup>'
  '{m:refid=([^}]+)}': '<a id="reference:$1" href="#reference:$1">$1</a>'
  '{m:imgprev=([^}]+)}': '[![]($1){.imgprev}]($1)'
  '{m:color=([^}]+)}': '<span style="color:$1">'
  '{\/m:color}': '</span>'
  '{m:ghlink=([^}]+), t=([^}]+)}': '<a href="https://github.com/$1" target="_blank"><img src="%theme_url%/icon/octicon.png" alt=""/>$2</a>'

In this example, I have chosen a specific syntax, starting with "m:" for the opening tag and "/m:" for the closing tag, wrapped with curly brackets. I recommend sticking to the familiar syntax to prevent conflicts with other tags from other languages and plugins.

If you write something like this in your Markdown page:

# My Example

{m:infobox}
This example{m:reflink=MyReferenceLink} is {m:color=red}fantastic{/m:color}!
{/m:infobox}

Please, look at my example photo:
{m:imgprev=%assets_url%/example.jpg}

My GitHub project:
{m:ghlink=tinelstudio/pico-markdown-macros, t=TineL Markdown Macros}

{m:refid:MyReferenceLink}
: Example as a showcase

the result will be:

# My Example

<div class="tlNotices blue">
This example<sup>\[[MyReferenceLink](#reference:MyReferenceLink)\]</sup> is <span style="color:red">fantastic</span>!
</div>

Please, look at my example photo:
[![](%assets_url%/example.jpg){.imgprev}](%assets_url%/example.jpg)

My GitHub project:
<a href="https://github.com/tinelstudio/pico-markdown-macros" target="_blank"><img src="%theme_url%/icon/octicon.png" alt=""/>TineL Markdown Macros</a>

<a id="reference:MyReferenceLink" href="#reference:MyReferenceLink">MyReferenceLink</a>
: Example as a showcase

Note that variables like %assets_url% and %theme_url% are resolved afterwards.

Installation

With Composer (recommended)

composer require tinelstudio/pico-markdown-macros

Pico installs plugins through picocms/composer-installer, which places this package in Pico's plugins/ directory rather than in vendor/. If your site does not have it yet, add it once:

composer require picocms/composer-installer

Composer 2 also needs the installer allowed in your root composer.json:

"config": {
    "allow-plugins": {
        "picocms/composer-installer": true
    }
}

By hand

Copy TineLMarkdownMacros.php into Pico's plugins/ directory, in a folder named TineLMarkdownMacros. Pico loads plugins from there directly, no autoloader involved.

Configuration

Add the settings below to config/config.yml, or to a file of your own inside Pico's config/ directory - for example config/tinel-markdown-macros.yml. Pico reads every .yml file in that directory automatically, so a separate file keeps this plugin's settings together and out of your main config.

License

MIT - see LICENSE.