remark-directive

What is remark-directive?

The remark-directive package is a plugin for the remark ecosystem that allows you to use custom directives in Markdown. Directives are a way to extend Markdown syntax with additional functionality, such as custom containers, special formatting, or embedding content.

What are remark-directive's main functionalities?

Custom Containers

You can create custom containers to encapsulate content with specific styles or behaviors. In this example, a 'warning' container is created to highlight a warning message.

```markdown
::: warning
This is a warning container.
:::
```

Special Formatting

Directives can be used to apply special formatting to text. In this example, a 'bold' directive is used to make the enclosed text bold.

```markdown
::bold[This text is bold]
```

Embedding Content

Directives can be used to embed external content, such as videos, images, or other resources. In this example, an 'embed' directive is used to include content from an external URL.

```markdown
::embed[https://example.com]
```

Other packages similar to remark-directive

remark-containers

remark-containers is a plugin for creating custom containers in Markdown. It is similar to remark-directive in that it allows you to define custom blocks, but it is more focused on container elements specifically.

remark-custom-blocks

remark-custom-blocks is another plugin that allows you to define custom block-level elements in Markdown. It provides similar functionality to remark-directive but is more specialized in creating custom blocks with specific classes and styles.

remark-shortcodes

remark-shortcodes is a plugin that enables the use of shortcodes in Markdown. It is similar to remark-directive in that it allows for extended syntax, but it focuses on shortcodes rather than directives.

README

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[, options])
  • Options
• Examples
  • Example: YouTube
  • Example: Styled blocks
• Authoring
• HTML
• CSS
• 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.

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.

If you just want to turn markdown into HTML (with maybe a few extensions such as this one), we recommend micromark with micromark-extension-directive instead. If you don’t use plugins and want to access the syntax tree, you can use mdast-util-from-markdown with mdast-util-directive.

Install

This package is ESM only. In Node.js (version 16+), install with npm:

npm install remark-directive

In Deno with esm.sh:

import remarkDirective from 'https://esm.sh/remark-directive@3'

In browsers with esm.sh:

<script type="module">
  import remarkDirective from 'https://esm.sh/remark-directive@3?bundle'
</script>

Use

Say our document example.md contains:

:::main{#readme}

Lorem:br
ipsum.

::hr{.red}

A :i[lovely] language know as :abbr[HTML]{title="HyperText Markup Language"}.

:::

…and our module example.js contains:

/**
 * @import {} from 'mdast-util-directive'
 * @import {} from 'mdast-util-to-hast'
 * @import {Root} from 'mdast'
 */

import {h} from 'hastscript'
import rehypeFormat from 'rehype-format'
import rehypeStringify from 'rehype-stringify'
import remarkDirective from 'remark-directive'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {read} from 'to-vfile'
import {unified} from 'unified'
import {visit} from 'unist-util-visit'

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.
function myRemarkPlugin() {
  /**
   * @param {Root} tree
   *   Tree.
   * @returns {undefined}
   *   Nothing.
   */
  return function (tree) {
    visit(tree, function (node) {
      if (
        node.type === 'containerDirective' ||
        node.type === 'leafDirective' ||
        node.type === 'textDirective'
      ) {
        const data = node.data || (node.data = {})
        const hast = h(node.name, node.attributes || {})

        data.hName = hast.tagName
        data.hProperties = hast.properties
      }
    })
  }
}

…then running node example.js 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[, options])

Add support for generic directives.

Parameters

• options (Options, optional) — configuration

Returns

Nothing (undefined).

Notes

Doesn’t handle the directives: create your own plugin to do that.

Options

Configuration (TypeScript type).

Fields

• collapseEmptyAttributes (boolean, default: true) — collapse empty attributes: get title instead of title=""
• preferShortcut (boolean, default: true) — prefer # and . shortcuts for id and class
• preferUnquoted (boolean, default: false) — leave attributes unquoted if that results in less bytes
• quoteSmart (boolean, default: false) — use the other quote if that results in less bytes
• quote ('"' or "'", default: the quote used by remark-stringify for titles) — preferred quote to use around attribute values

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:

/**
 * @import {} from 'mdast-util-directive'
 * @import {} from 'mdast-util-to-hast'
 * @import {Root} from 'mdast'
 * @import {VFile} from 'vfile'
 */

import {visit} from 'unist-util-visit'

// This plugin is an example to turn `::youtube` into iframes.
function myRemarkPlugin() {
  /**
   * @param {Root} tree
   *   Tree.
   * @param {VFile} file
   *   File.
   * @returns {undefined}
   *   Nothing.
   */
  return (tree, file) => {
    visit(tree, function (node) {
      if (
        node.type === 'containerDirective' ||
        node.type === 'leafDirective' ||
        node.type === 'textDirective'
      ) {
        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(
            'Unexpected `:youtube` text directive, use two colons for a leaf directive',
            node
          )
        }

        if (!id) {
          file.fail('Unexpected missing `id` on `youtube` directive', 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.js 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:

/**
 * @import {} from 'mdast-util-directive'
 * @import {} from 'mdast-util-to-hast'
 * @import {Root} from 'mdast'
 */

import {h} from 'hastscript'
import {visit} from 'unist-util-visit'

// This plugin is an example to turn `::note` into divs,
// passing arbitrary attributes.
function myRemarkPlugin() {
  /**
   * @param {Root} tree
   *   Tree.
   * @returns {undefined}
   *   Nothing.
   */
  return (tree) => {
    visit(tree, (node) => {
      if (
        node.type === 'containerDirective' ||
        node.type === 'leafDirective' ||
        node.type === 'textDirective'
      ) {
        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>

Authoring

When authoring markdown with directives, keep in mind that they don’t work in most places. On your own site it can be great!

HTML

You can define how directives are turned into HTML. If directives are not handled, they do not emit anything.

CSS

How to display directives is left as an exercise for the reader.

Syntax

See Syntax in micromark-extension-directive.

Syntax tree

See Syntax tree in mdast-util-directive.

Types

This package is fully typed with TypeScript. It exports no additional options.

If you’re working with the syntax tree, you can register the new node types with @types/mdast by adding a reference:

/**
 * @import {} from 'mdast-util-directive'
 * @import {Root} from 'mdast'
 */

import {visit} from 'unist-util-visit'

function myRemarkPlugin() {
  /**
   * @param {Root} tree
   *   Tree.
   * @returns {undefined}
   *   Nothing.
   */
  return (tree) => {
    visit(tree, function (node) {
      console.log(node) // `node` can now be one of the nodes for directives.
    })
  }
}

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, remark-directive@3, compatible with Node.js 16.

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 math
• remark-mdx — support MDX (ESM, JSX, expressions)

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