remark-directive/readme.md

remark-directive

remark plugin to support the generic directives proposal (:cite[smith04], ::youtube[Video of a cat in a box]{v=01ab2cd3efg}, and such).

What is this?

This is a plugin that works with unified (specifically, remark, for markdown). It adds support for a syntax that allows arbitrary extensions in markdown. You use it with some code specific to match your needs, to allow for anything from callouts, specifically styled blocks, forms, spoilers, anything!

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 {readSync} from 'to-vfile'
import {reporter} from 'vfile-reporter'
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'

const file = readSync('example.md')

unified()
  .use(remarkParse)
  .use(remarkDirective)
  .use(customPlugin)
  .use(remarkRehype)
  .use(rehypeFormat)
  .use(rehypeStringify)
  .process(file)
  .then((file) => {
    console.error(reporter(file))
    console.log(String(file))
  })

// This plugin is just an example! You can handle directives however you please!
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:

example.md: no issues found

example.md: no issues found
<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.

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