unified

Project: rehypejs/rehype-raw

Package: rehype-raw@6.1.0

  1. Dependents: 111
  2. rehype plugin to reparse the tree (and raw nodes)
  1. unified 174
  2. plugin 137
  3. html 121
  4. rehype 85
  5. rehype-plugin 60
  6. raw 3

rehype-raw

Build Coverage Downloads Size Sponsors Backers Chat

rehype plugin to parse the tree again (and raw nodes). Keeping positional info OK. 🙌

Tiny wrapper around hast-util-raw

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install rehype-raw

Use

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

<div class="note">

A mix of *Markdown* and <em>HTML</em>.

</div>

And our script, example.js, looks as follows:

import {readSync} from 'to-vfile'
import {reporter} from 'vfile-reporter'
import {unified} from 'unified'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import rehypeRaw from 'rehype-raw'
import rehypeDocument from 'rehype-document'
import rehypeFormat from 'rehype-format'
import rehypeStringify from 'rehype-stringify'

const file = readSync('example.md')

unified()
  .use(remarkParse)
  .use(remarkRehype, {allowDangerousHtml: true})
  .use(rehypeRaw)
  .use(rehypeDocument, {title: '🙌'})
  .use(rehypeFormat)
  .use(rehypeStringify)
  .process(file)
  .then((file) => {
    console.error(reporter(file))
    console.log(String(file))
  })

Now, running node example yields:

example.md: no issues found
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>🙌</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <div class="note">
      <p>A mix of <em>Markdown</em> and <em>HTML</em>.</p>
    </div>
  </body>
</html>

API

This package exports no identifiers. The default export is rehypeRaw.

unified().use(rehypeRaw[, options])

Parse the tree again, also parsing “raw” nodes (as exposed by remark-rehype). options are passed to hast-util-raw.

Note

This project parses a hast tree with embedded raw HTML. This typically occurs because we’re coming from Markdown, often parsed by remark-parse. Inside Markdown, HTML is a black box: Markdown doesn’t know what’s inside that HTML. So, when rehype-raw maps Markdown to HTML, it cannot understand raw embedded HTML.

That’s where this project comes in.

But, Markdown is much terser than HTML, so it’s often preferred to use Markdown, in HTML, inside Markdown. As can be seen in the above example.

However, Markdown can only be mixed with HTML in some cases. Take the following examples:

Security

Improper use of rehype-raw can open you up to a cross-site scripting (XSS) attack.

Either do not combine this plugin with user content or use rehype-sanitize.

Contribute

See contributing.md in rehypejs/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer