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
  • unified().use(remarkDirective)
• Examples
  • Example: YouTube
  • Example: Styled blocks
• Security
• Related
• Contribute
• License

What is this?

This is a plugin that works with unified (specifically remark for markdown). That means it’s easier to use than lower-level tools such as micromark or mdast, which are abstracted away.

It adds support for a syntax that allows 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!

When should I use this?

This is 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. 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: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install remark-directive

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(customPlugin)
    .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 customPlugin() {
  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. See the micromark extension for the syntax and the mdast utility for the syntax tree.

Examples

Example: YouTube

This example shows how directives can be used for YouTube embeds. It’s based on the example in Use above.

If example.md is:

# Cat videos

::youtube[Video of a cat in a box]{#01ab2cd3efg}

Then, replacing customPlugin with this function:

// This plugin is an example to turn `::youtube` into iframes.
/** @type {import('unified').Plugin<[], import('mdast').Root>} */
function customPlugin() {
  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 + '?feature=oembed',
          width: 200,
          height: 200,
          frameBorder: 0,
          allow: 'accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture',
          allowFullScreen: true
        }
      }
    })
  }
}

Now, running node example yields:

<h1>Cat videos</h1>
<iframe src="https://www.youtube.com/embed/01ab2cd3efg?feature=oembed" width="200" height="200" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; 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 example.md is:

# How to use xxx

You can use xxx.

:::note{.warning}
if you chose xxx, you should also use yyy somewhere…
:::

Then, replacing customPlugin with this function:

// This plugin is an example to turn `::note` into divs, passing arbitrary
// attributes.
/** @type {import('unified').Plugin<[], import('mdast').Root>} */
function customPlugin() {
  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
      }
    })
  }
}

Now, 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>

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 — GFM
• remark-github — Autolink references like in GitHub issues, PRs, and comments
• remark-frontmatter — Frontmatter (YAML, TOML, and more)
• remark-math — Math

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