
Security News
Node.js TSC Votes to Stop Distributing Corepack
Corepack will be phased out from future Node.js releases following a TSC vote.
remark-shortcodes
Advanced tools
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.
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" }
}
npm:
npm install --save remark-shortcodes
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" }
}
]
}
Say example2.js
looks as follows:
var unified = require('unified');
var parse = require('remark-parse');
var shortcodes = require('remark-shortcodes');
var ast = {
"type": "root",
"children": [
{
"type": "paragraph",
"children": [{ "type": "text", "value": "Example paragraph" }]
},
{
"type": "shortcode",
"identifier": "MailchimpForm",
"attributes": { "id": "chfk2" }
}
]
};
var tree = unified()
.use(parse)
// Plugin inserted below, with custom options for start/end blocks.
.use(shortcodes, {startBlock: "{{>", endBlock: "<}}"})
.stringify(ast);
console.log(tree);
Running node example2
yields:
Example paragraph\n\n{{> MailchimpForm id="chfk2" <}}
Say example3.js
looks as follows:
var unified = require('unified');
var parse = require('remark-parse');
var shortcodes = require('remark-shortcodes');
var markdown = 'Example paragraph {{> MailchimpForm id="chfk2" <}}'
var tree = unified()
.use(parse)
// Plugin inserted below, with custom options for start/end blocks.
.use(shortcodes, {startBlock: "{{>", endBlock: "<}}", inlineMode: true})
// Turn off position output for legibility below.
.data('settings', {position: false})
.parse(markdown);
console.dir(tree, {depth: null});
Running node example3
yields:
{
"type": "root",
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Example paragraph "
},
{
"type": "shortcode",
"identifier": "MailchimpForm",
"attributes": { "id": "chfk2" }
}
]
}
]
}
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: ]]
.inlineMode
: shortcodes will be parsed inline rather than in block mode. Default: false
.NB: Be careful when using custom start/end blocks, your choices may clash with other markdown syntax and/or other remark plugins.
To run the tests, run:
npm run test-code
To run build, tests & coverage, run:
npm run test
Prepare the commits:
git tag -a v0.1.x -m v0.1.x
git push --tags
Publish to npm:
git checkout tags/v0.1.x
npm login
npm publish
FAQs
Shortcode parser plugin for Remark
The npm package remark-shortcodes receives a total of 1,774 weekly downloads. As such, remark-shortcodes popularity was classified as popular.
We found that remark-shortcodes demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Corepack will be phased out from future Node.js releases following a TSC vote.
Research
Security News
Research uncovers Black Basta's plans to exploit package registries for ransomware delivery alongside evidence of similar attacks already targeting open source ecosystems.
Security News
Oxlint's beta release introduces 500+ built-in linting rules while delivering twice the speed of previous versions, with future support planned for custom plugins and improved IDE integration.