markdown-it-shortcode-tag

With this plugin you can define shortcodes for arbitrary content to be rendered when parsing markdown. The shortcodes take the form of self-closing HTML5 tags:

<custom first second="string" third=3.7 fourth=#{myvar} >

You cannot write closing tags and consequently no inner content. Attributes are either interpolated using a marker #{ } or passed directly to a rendering function you define for every tag to be interpreted:

const indirect = shortcodes.custom.interpolator("myvar", env)

shortcodes.custom.render({
    first: true,
    second: "string",
    third: 3.7
    fourth: indirect
}, env)

html must be enabled in markdown-it options. Otherwise, the tag will be rendered in escaped form. With this option, unknown tags (or all, if the plugin is not active) are passed through. This means that, as long as the tag is not defined in HTML5, it is ignored by browsers.

Installation

$ npm install markdown-it-shortcode-tag --save

API

var shortcodes = {
    tag: {
        render: function (attrs, env) {...} [,
        inline: true ]
    } [,
    ...]
}

var options = {
    interpolator: function(expr, env) { ... }
}

var md = require('markdown-it')({html: true})
        .use(require('markdown-it-shortcode-tag'), shortcodes, options);


md.render(content, env);

shortcodes

• tag - set a property name to identify shortcodes of the form <tag ...>. HTML5 rules for tag names apply.
• render - function that returns the rendered shortcode
  • attrs - Object with name-value pairs for all attributes listed in the tag. HTML5 rules for attribute syntax apply. See below for the relation between tag attributes and object property values.
  • env - the enviroment variable passed to markdown-it in a md.render(content, env).
• inline - optional, if true the shortcode is always rendered inline (surrounded by <p></p> tags), even if stands on its own separated line

options

• interpolator - optional, function that interpolates an attribute value given unquoted and surrounded by an interpolation marker #{ }.
  Defaults to looking up the enviroment value: (expr, env) => env[expr].
  • expr - string content of the curly braces.
  • env - the enviroment variable passed to markdown-it in a md.render(content, env).

Translation from tag attributes to attrs object properties

name
Attributes without values are represented as boolean true:

attrs.name = true

name=3.7
Unquoted values are converted to numbers using parseFloat():

attrs.name = 3.7

name=#{expr}
Values surrounded by the interpolation marker are passed to the options.interpolator function:

attrs.name = options.interpolator("expr", env)

or, if missing, to its default:

attrs.name = env["expr"]

Note that for this syntax whitespace inside the curly braces is not allowed, as per HTML attribute syntax rules.

name="value"
strings are copied to the property:

attrs.name = "value"

name="val1#{expr}val2"
In strings that contain an interpolation marker #{ }, the marker is exchanged for the string value of the contained enviroment variable:

attrs.name = "val1" + env["expr"] + "val2"

Examples

Style subcontent layout

var supported = ['img', 'video', 'iframe'];

var shortcodes = {
    media: {
        render: function (attrs, env) {
            if (supported.indexOf(attrs.method) < 0) {
                throw new Error('unsupported medium');
            }
            var out = '<' + attrs.method;
            out += ' src="' + (attrs.src || '') + '"';
            out += ' alt="' + (attrs.alt || '') + '"';
            if (attrs.width) out += ' width="' + attrs.width + '"';
            if (attrs.side) out += ' style="float:' + attrs.side + '"';
            return out + '>';
        }
    }
}

var md = require('markdown-it')({html: true})
        .use(require('markdown-it-shortcode-tag'), shortcodes);

console.log(md.render('<media method="img" src={picture} width=400 side="left">', {
    picture: "assets/picture.jpg"
}));

Output:

<img src="assets/picture.jpg" alt="" width="400" style="float:left">

Render an enviroment variable using shortcodes

var shortcodes = {
    variable: {
        render: function (attrs, env) {
            var name = Object.getOwnPropertyNames(attrs)[0];
            return env[name];
        }
    }
}

var md = require('markdown-it')({html: true})
        .use(require('markdown-it-shortcode-tag'), shortcodes);

console.log(md.render('# <variable title>', { title: "Hello World" }));

Output:

<h1>Hello World</h1>

Render an environment variable using interpolation

var shortcodes = {
    footer: {
        render: function (attrs) {
            return '<footer><p>' + attrs[meta] + '</p></footer>';
        }
    }
}

var options = {
    interpolator: function (expr, env) {
        return 'Authored by ' + env[expr].author + ' on ' +
               Date(env[expr].date).toLocaleDateString(env.locale) + '.';
    }
}

var md = require('markdown-it')({html: true})
        .use(require('markdown-it-shortcode-tag'), shortcodes, options);

console.log(md.render('<footer meta=#{lastpost} >', {
    lastpost: {
        author: "Janet",
        date: "2018-01-03"
    },
    locale: "en_US"
}));

Output:

<footer><p>Authored by Janet on 2018/3/1</p></footer>

License

see LICENSE