remark-directive-rehype

remark plugin to integrate remark-directive with remark-rehype.

What is this?

This package is a unified (remark) plugin to enable Markdown directives to be parsed as HTML when using remark-rehype. Markdown directives are first parsed with remark-directive which needs to be used before this plugin.

unified is a project that transforms content with abstract syntax trees (ASTs). remark adds support for markdown to unified. rehype adds support for HTML to unified. mdast is the markdown AST that remark uses. hast is the markdown AST that rehype uses. This is a remark plugin that transforms mdast.

When should I use this?

This project is useful when you want directives parsed by remark-directive to be later parsed as HTML (hast nodes) when using remark-rehype. This is specifically useful when one wants to convert Markdown directives into HTML tags that can be outputted as components with react-markdown.

Installation

This package is ESM only. In Node.js (version 12.20+, 14.14+, or 16.0+), install with yarn or npm :

1yarn add remark-directive-rehype
2npm install remark-directive-rehype

In Deno with Skypack:

1import remarkDirectiveRehype from 'https://cdn.skypack.dev/remark-directive-rehype'

In browsers with Skypack:

1<script type="module">
2  import remarkDirectiveRehype from 'https://cdn.skypack.dev/remark-directive-rehype?min'
3</script>

Usage

Say we have the following file, example.md:

1:::documentation-page{title="Welcome"}
2
3Please install :inline-code[unified]!
4
5::copyright-notice{year="2020"}
6
7:::

And our module example.js looks as follows:

1import {read} from 'to-vfile'
2import {unified} from 'unified'
3import remarkParse from 'remark-parse'
4import remarkDirective from 'remark-directive'
5import remarkDirectiveRehype from 'remark-directive-rehype'
6import remarkRehype from 'remark-rehype'
7import rehypeStringify from 'rehype-stringify'
8
9main()
10
11async function main() {
12  const file = await unified()
13    .use(remarkParse)
14    .use(remarkDirective)
15    .use(remarkDirectiveRehype)
16    .use(remarkRehype)
17    .use(rehypeStringify)
18    .process(await read('example.md'))
19
20  console.log(String(file))
21}

Now running node example yields:

1<documentation-page title="Welcome">
2  <p>Please install <inline-code>unified</inline-code>!</p>
3  <copyright-notice year="2020"></copyright-notice>
4</documentation-page>

Examples

Example: react-markdown

You can use it with react-markdown to render custom React components for each defined directive.

1import React from 'react'
2import ReactDom from 'react-dom'
3import ReactMarkdown from 'react-markdown'
4import remarkDirective from 'remark-directive'
5import remarkDirectiveRehype from 'remark-directive-rehype'
6
7const markdown = `
8# Cat videos
9
10::youtube-video[Video of a cat in a box]{#01ab2cd3efg}
11`
12
13const YouTubeVideo = ({id, children}) => (
14  <iframe
15    src={'https://www.youtube.com/embed/' + id}
16    width="200"
17    height="200"
18  >
19    {children}
20  </iframe>
21)
22
23ReactDom.render(
24  <ReactMarkdown
25    children={markdown}
26    remarkPlugins={[remarkDirective, remarkDirectiveRehype]}
27    components={{
28      'youtube-video': YouTubeVideo
29    }}
30  />,
31  document.body
32)

Yields:

1<h1>Cat videos</h1>
2<iframe src="https://www.youtube.com/embed/01ab2cd3efg" width="200" height="200">Video of a cat in a box</iframe>

Example: rehype-components

You can use in conjunction with rehype-components to render components made with hastscript.

1// …
2
3const file = await unified()
4  .use(remarkParse)
5  .use(remarkDirective)
6  .use(remarkDirectiveRehype)
7  .use(remarkRehype)
8  .use(rehypeComponents, {
9    components: {
10      'documentation-page': DocumentationPage,
11      'inline-code': InfoBox,
12      'copyright-notice': CopyrightNotice,
13    },
14  })
15  .use(rehypeStringify)
16  .process(await read('example.md'))
17
18console.log(String(file))

See rehype-components for more information on how to implement the components.

Contributing

Contributions are always welcome!

See ./docs/CONTRIBUTING.md for ways to get started.