remark-directive
remark plugin to support the generic directives proposal
(:cite[smith04]
, ::youtube[Video of a cat in a box]{v=01ab2cd3efg}
, and
such).
Contents
- What is this?
- When should I use this?
- Install
- Use
- API
- Examples
- Syntax
- Syntax tree
- Types
- Compatibility
- Security
- Related
- Contribute
- License
What is this?
This package is a unified (remark) plugin to add support for directives: one syntax for arbitrary extensions in markdown. You can use this with some more code to match your specific needs, to allow for anything from callouts, citations, styled blocks, forms, embeds, spoilers, etc.
unified is a project that transforms content with abstract syntax trees (ASTs). remark adds support for markdown to unified. mdast is the markdown AST that remark uses. micromark is the markdown parser we use. This is a remark plugin that adds support for the directives syntax and AST to remark.
When should I use this?
Directives are one of the four ways to extend markdown: an arbitrary extension syntax (see Extending markdown in micromarkβs docs for the alternatives and more info). This mechanism works well when you control the content: who authors it, what tools handle it, and where itβs displayed. When authors can read a guide on how to embed a tweet but are not expected to know the ins and outs of HTML or JavaScript. Directives donβt work well if you donβt know who authors content, what tools handle it, and where it ends up. Example use cases are a docs website for a project or product, or blogging tools and static site generators.
Install
This package is ESM only. In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:
npm install remark-directive
In Deno with esm.sh
:
import remarkDirective from 'https://esm.sh/remark-directive@2'
In browsers with esm.sh
:
<script type="module">
import remarkDirective from 'https://esm.sh/remark-directive@2?bundle'
</script>
Use
Say we have the following file, example.md
:
:::main{#readme}
Lorem:br
ipsum.
::hr{.red}
A :i[lovely] language know as :abbr[HTML]{title="HyperText Markup Language"}.
:::
And our module, example.js
, looks as follows:
import {read} from 'to-vfile'
import {unified} from 'unified'
import remarkParse from 'remark-parse'
import remarkDirective from 'remark-directive'
import remarkRehype from 'remark-rehype'
import rehypeFormat from 'rehype-format'
import rehypeStringify from 'rehype-stringify'
import {visit} from 'unist-util-visit'
import {h} from 'hastscript'
main()
async function main() {
const file = await unified()
.use(remarkParse)
.use(remarkDirective)
.use(myRemarkPlugin)
.use(remarkRehype)
.use(rehypeFormat)
.use(rehypeStringify)
.process(await read('example.md'))
console.log(String(file))
}
// This plugin is an example to let users write HTML with directives.
// Itβs informative but rather useless.
// See below for others examples.
/** @type {import('unified').Plugin<[], import('mdast').Root>} */
function myRemarkPlugin() {
return (tree) => {
visit(tree, (node) => {
if (
node.type === 'textDirective' ||
node.type === 'leafDirective' ||
node.type === 'containerDirective'
) {
const data = node.data || (node.data = {})
const hast = h(node.name, node.attributes)
data.hName = hast.tagName
data.hProperties = hast.properties
}
})
}
}
Now, running node example
yields:
<main id="readme">
<p>Lorem<br>ipsum.</p>
<hr class="red">
<p>A <i>lovely</i> language know as <abbr title="HyperText Markup Language">HTML</abbr>.</p>
</main>
API
This package exports no identifiers.
The default export is remarkDirective
.
unified().use(remarkDirective)
Configures remark so that it can parse and serialize directives. Doesnβt handle the directives: create your own plugin to do that.
Examples
Example: YouTube
This example shows how directives can be used for YouTube embeds.
Itβs based on the example in Use above.
If myRemarkPlugin
was replaced with this function:
// This plugin is an example to turn `::youtube` into iframes.
/** @type {import('unified').Plugin<[], import('mdast').Root>} */
function myRemarkPlugin() {
return (tree, file) => {
visit(tree, (node) => {
if (
node.type === 'textDirective' ||
node.type === 'leafDirective' ||
node.type === 'containerDirective'
) {
if (node.name !== 'youtube') return
const data = node.data || (node.data = {})
const attributes = node.attributes || {}
const id = attributes.id
if (node.type === 'textDirective') file.fail('Text directives for `youtube` not supported', node)
if (!id) file.fail('Missing video id', node)
data.hName = 'iframe'
data.hProperties = {
src: 'https://www.youtube.com/embed/' + id,
width: 200,
height: 200,
frameBorder: 0,
allow: 'picture-in-picture',
allowFullScreen: true
}
}
})
}
}
β¦and example.md
contains:
# Cat videos
::youtube[Video of a cat in a box]{#01ab2cd3efg}
β¦then running node example
yields:
<h1>Cat videos</h1>
<iframe src="https://www.youtube.com/embed/01ab2cd3efg" width="200" height="200" frameborder="0" allow="picture-in-picture" allowfullscreen>Video of a cat in a box</iframe>
Example: Styled blocks
Note: This is sometimes called admonitions, callouts, etc.
This example shows how directives can be used to style blocks.
Itβs based on the example in Use above.
If myRemarkPlugin
was replaced with this function:
// This plugin is an example to turn `::note` into divs, passing arbitrary
// attributes.
/** @type {import('unified').Plugin<[], import('mdast').Root>} */
function myRemarkPlugin() {
return (tree) => {
visit(tree, (node) => {
if (
node.type === 'textDirective' ||
node.type === 'leafDirective' ||
node.type === 'containerDirective'
) {
if (node.name !== 'note') return
const data = node.data || (node.data = {})
const tagName = node.type === 'textDirective' ? 'span' : 'div'
data.hName = tagName
data.hProperties = h(tagName, node.attributes).properties
}
})
}
}
β¦and example.md
contains:
# How to use xxx
You can use xxx.
:::note{.warning}
if you chose xxx, you should also use yyy somewhereβ¦
:::
β¦then running node example
yields:
<h1>How to use xxx</h1>
<p>You can use xxx.</p>
<div class="warning">
<p>if you chose xxx, you should also use yyy somewhereβ¦</p>
</div>
Syntax
This plugin applies a micromark extensions to parse the syntax. See its readme for parse details:
Syntax tree
This plugin applies one mdast utility to build and serialize the AST. See its readme for the node types supported in the tree:
Types
This package is fully typed with TypeScript. If youβre working with the syntax tree, make sure to import this plugin somewhere in your types, as that registers the new node types in the tree.
/** @typedef {import('remark-directive')} */
import {visit} from 'unist-util-visit'
/** @type {import('unified').Plugin<[], import('mdast').Root>} */
export default function myRemarkPlugin() {
return (tree) => {
visit(tree, (node) => {
// `node` can now be one of the nodes for directives.
})
}
}
Compatibility
Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 12.20+, 14.14+, and 16.0+. Our projects sometimes work with older versions, but this is not guaranteed.
This plugin works with unified version 9+ and remark version 14+.
Security
Use of remark-directive
does not involve rehype
(hast) or user content so there are no openings for cross-site
scripting (XSS) attacks.
Related
remark-gfm
β support GFM (autolink literals, footnotes, strikethrough, tables, tasklists)remark-frontmatter
β support frontmatter (YAML, TOML, and more)remark-math
β support mathremark-mdx
β support MDX (JSX, expressions, ESM)
Contribute
See contributing.md
in remarkjs/.github
for ways
to get started.
See support.md
for ways to get help.
This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.
License
MIT Β© Titus Wormer