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:

``html

`

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:

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

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

[html][1] 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

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




API

`js
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 . [HTML5 rules][2]
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][3] 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


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).

$3

__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

$3

`js
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('', {
picture: "assets/picture.jpg"
}));
`

Output:

`html

`

$3

`js
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('# ', { title: "Hello World" }));
`

Output:

`html


Hello World


`

$3

`js
var shortcodes = {
footer: {
render: function (attrs) {
return '

';
}
}
}

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('