remark-directive

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

Important!

This plugin is made for the new parser in remark (micromark, see remarkjs/remark#536). Use this plugin for remark 13+.

Install

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 script, example.js, looks as follows:

var vfile = require('to-vfile')
var report = require('vfile-reporter')
var unified = require('unified')
var parse = require('remark-parse')
var directive = require('remark-directive')
var remark2rehype = require('remark-rehype')
var format = require('rehype-format')
var stringify = require('rehype-stringify')
var visit = require('unist-util-visit')
var h = require('hastscript')

unified()
  .use(parse)
  .use(directive)
  .use(htmlDirectives)
  .use(remark2rehype)
  .use(format)
  .use(stringify)
  .process(vfile.readSync('example.md'), function (err, file) {
    console.error(report(err || file))
    console.log(String(file))
  })

// This plugin is just an example! You can handle directives however you please!
function htmlDirectives() {
  return transform

  function transform(tree) {
    visit(tree, ['textDirective', 'leafDirective', 'containerDirective'], ondirective)
  }

  function ondirective(node) {
    var data = node.data || (node.data = {})
    var 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

remark().use(directive)

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-footnotes — Footnotes
• 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