remark-shortcodes

remark-shortcodes

A custom Markdown syntax parser for remark that adds support for shortcodes.

What are shortcodes? They are a way to provide hooks for macros and/or template partials inside a markdown file. They consist of start & end blocks, in between which the shortcode has a name defined and an optional set of key:value attributes in HTML style. They can look like this:

The example below uses the default start & end blocks that
this parser ships with:

[[ MailchimpForm id="chfk2" ]]

But they are configurable, so if you're coming from Hugo say,
you can set them as such:

{{< MailchimpForm id="chfk2" >}}

Why use them? Because sometimes you'd like to insert content inline without copy pasting raw HTML in to your Markdown file. The copy paste approach means that hard-to-modify code is littered throughout your content and is therefore very hard to maintain; whereas the shortcode approach can result in a partial being updated in only one place.

Both Wordpress & Hugo have support for shortcodes; this parser's implementation is much closer to Wordpress's, as it does not support inner content or nested shortcodes like Hugo does - but can actually be used for the simpler partials. It was made for my use, but if you'd like to extend it to support more cases, please feel free! Everyone is welcome.

A parser, not a transformer

This plugin is just a parser and not a transformer; meaning that it allows remark to understand the shortcodes at the block level and converts them to a representation in its Markdown AST (MDAST) - that is where it stops.

To transform that generated AST into HTML will require something more specific to your project: your plugin will have to visit the AST, gather the information off the correct node and then render a template partial in whatever way you please.

For some more advice on building a transformer from these new AST blocks, please take a look at Remarks other plugins to get an idea of what you will need to do.

AST Block: Shortcode

Shortcode (Node) is a simple node that has an identifier and an optional object with string values, respresenting the attributes parsed.

interface Shortcode <: Node {
  type: "shortcode";
  identifier: string;
  attributes: { key: string, ...}
}

For example, the following markdown:

[[ MailchimpForm id="chfk2" ]]

Yields:

{
  type: "shortcode",
  identifier: "MailchimpForm",
  attributes: { id: "chfk2" }
}

Installation

npm:

npm install --save remark-shortcodes

Usage

Say example.js looks as follows:

var unified = require('unified');
var parse = require('remark-parse');
var shortcodes = require('remark-shortcodes');

var markdown = 'Example paragraph\n\n{{> MailchimpForm id="chfk2" <}}'

var tree = unified()
  .use(parse)
  // Plugin inserted below, with custom options for start/end blocks.
  .use(shortcodes, {startBlock: "{{>", endBlock: "<}}"})
  // Turn off position output for legibility below.
  .data('settings', {position: false})
  .parse(markdown);

console.dir(tree, {depth: null});

Running node example yields:

{
  type: "root",
  children: [
    {
      type: "paragraph",
      children: [{ type: "text", value: "Example paragraph" }]
    },
    {
      type: "shortcode",
      identifier: "MailchimpForm",
      attributes: { id: "chfk2" }
    }
  ]
}

API

remark.use(shortcodes, {options})

Where options support the keys:

• startBlock: the start block to look for. Default: [[.
• endBlock: the end block to look for. Default: ]].

NB: Be careful when using custom start/end blocks, your choices may clash with other markdown syntax and/or other remark plugins.

Testing

To run the tests, run:

npm run test-code

To run build, tests & coverage, run:

npm run test

Releasing

TravisCI releases on tag to npm & github releases.

• Bump version in package.json
• Commit and tag with version number (git tag -a v0.1.x -m v0.1.x)
• Push

License

MIT © Darian Moody

With thanks to woorm et. al for remark.