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 :

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

In Deno with Skypack:

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

In browsers with Skypack:

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

Usage

Say we have the following file, example.md:

:::documentation-page{title="Welcome"}

Please install :inline-code[unified]!

::copyright-notice{year="2020"}

:::

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 remarkDirectiveRehype from 'remark-directive-rehype'
import remarkRehype from 'remark-rehype'
import rehypeStringify from 'rehype-stringify'

main()

async function main() {
  const file = await unified()
    .use(remarkParse)
    .use(remarkDirective)
    .use(remarkDirectiveRehype)
    .use(remarkRehype)
    .use(rehypeStringify)
    .process(await read('example.md'))

  console.log(String(file))
}

Now running node example yields:

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

Examples

Example: react-markdown

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

import React from 'react'
import ReactDom from 'react-dom'
import ReactMarkdown from 'react-markdown'
import remarkDirective from 'remark-directive'
import remarkDirectiveRehype from 'remark-directive-rehype'

const markdown = `
# Cat videos

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

const YouTubeVideo = ({id, children}) => (
  <iframe
    src={'https://www.youtube.com/embed/' + id}
    width="200"
    height="200"
  >
    {children}
  </iframe>
)

ReactDom.render(
  <ReactMarkdown
    children={markdown}
    remarkPlugins={[remarkDirective, remarkDirectiveRehype]}
    components={{
      'youtube-video': YouTubeVideo
    }}
  />,
  document.body
)

Yields:

<h1>Cat videos</h1>
<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.

// …

const file = await unified()
  .use(remarkParse)
  .use(remarkDirective)
  .use(remarkDirectiveRehype)
  .use(remarkRehype)
  .use(rehypeComponents, {
    components: {
      'documentation-page': DocumentationPage,
      'inline-code': InfoBox,
      'copyright-notice': CopyrightNotice,
    },
  })
  .use(rehypeStringify)
  .process(await read('example.md'))

console.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.