Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/igassmann/remark-directive-rehype

Remark plugin to enable Markdown directives to be parsed as HTML.
https://github.com/igassmann/remark-directive-rehype

directive hast markdown mdast plugin rehype remark remark-directive remark-plugin unified

Last synced: about 1 month ago
JSON representation

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

Awesome Lists containing this project

README 

        
# 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](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).

In Node.js (version 12.20+, 14.14+, or 16.0+), install with [yarn][] or [npm][] :



```sh

yarn add remark-directive-rehype

npm install remark-directive-rehype

```



In Deno with [Skypack][]:



```js

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

```



In browsers with [Skypack][]:



```html



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



```



## 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'



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:



```html



  
Please install unified!


  



```



## Examples



### Example: `react-markdown`



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



```js

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}) => (

  

    {children}

  

)



ReactDom.render(

  ,

  document.body

)

```



Yields:



```html

Cat videos


Video of a cat in a box

```



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



## Contributing



Contributions are always welcome!



See [`./docs/CONTRIBUTING.md`](./docs/CONTRIBUTING.md) for ways to get started.



[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



[yarn]: https://yarnpkg.com/lang/en/docs/install/



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



[skypack]: https://www.skypack.dev/



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



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



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