remark-directive-rehype/README.md

Remark plugin to enable Markdown directives to be parsed as HTML.

# 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 HTML 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](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
In Node.js (version 20+), install with [npm][]:

```sh
npm install remark-directive-rehype
```

## Usage

Say we have the following file, `example.md`:

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

Please install :inline-code[unified]!

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

:::
```

And our module `example.js` looks as follows:

```js
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'

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:

```html
<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.

```js
import { createRoot } from 'react-dom/client'
import Markdown 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>
)

createRoot(document.getElementById('root')).render(
  <Markdown
    remarkPlugins={[remarkDirective, remarkDirectiveRehype]}
    components={{
      'youtube-video': YouTubeVideo
    }}
  >
    {markdown}
  </Markdown>
)
```

Yields:

```html
<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][].

```js
// …

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.


<!-- Definitions -->

[remark]: https://github.com/remarkjs/remark

[remark-directive]: https://github.com/remarkjs/remark-directive

[remark-rehype]: https://github.com/remarkjs/remark-rehype

[unified]: https://github.com/unifiedjs/unified

[hast]: https://github.com/syntax-tree/hast

[npm]: https://docs.npmjs.com/cli/install

[react-markdown]: https://github.com/remarkjs/react-markdown

[rehype-components]: https://github.com/marekweb/rehype-components

[hastscript]: https://github.com/syntax-tree/hastscript