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.