The rehype-raw plugin is a powerful tool within the unified.js ecosystem designed for parsing HTML documents and managing raw nodes within an abstract syntax tree (AST) framework. If you’re looking to regain control over raw HTML embedded in markdown, this article has got you covered!

What is rehype-raw?

This plugin allows you to parse documents containing HTML, ensuring that the original data and positional information remain intact. It processes each node through the parse5 parser, similar to how a web browser interprets HTML.

When Should You Use rehype-raw?

rehype-raw is especially useful in two scenarios:

• When you’re converting markdown that includes embedded HTML elements, and you want those elements treated as actual nodes, not just strings.
• When you’re working with output formats like React or MDX that require structured nodes instead of plain HTML strings.

Installation

This plugin is ESM only. To install rehype-raw in Node.js (version 16+), simply run:

npm install rehype-raw

For environments like Deno, the import line would look like this:

import rehypeRaw from "https://esm.sh/rehype-raw@7"

And for browser environments, you can include it in your HTML like this:

<script type="module"> import rehypeRaw from "https://esm.sh/rehype-raw@7"?bundle </script>

Usage

Here’s how you can use rehype-raw effectively:

import rehypeDocument from "rehype-document";
import rehypeFormat from "rehype-format";
import rehypeRaw from "rehype-raw";
import rehypeStringify from "rehype-stringify";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import read from "to-vfile";
import unified from "unified";

const file = await unified()
    .use(remarkParse)
    .use(remarkRehype, { allowDangerousHtml: true })
    .use(rehypeRaw)
    .use(rehypeDocument, { title: "Your Title" })
    .use(rehypeFormat)
    .use(rehypeStringify)
    .process(await read("example.md"));
    
console.log(String(file));

Explaining the Code: An Analogy

Imagine you are a chef in a restaurant. Your recipe book (markdown) contains ingredients (markdown elements like lists and bold text) alongside special sauces (raw HTML). The rehype-raw plugin acts as a skilled sous-chef. It takes your recipe, ensures the ingredients are accurately represented, and properly blends in the special sauces, maintaining the original flavors and arrangements. After it’s all mixed properly, the final dish is ready to serve (HTML output)!

API Overview

The plugin provides a straightforward API:

• unified().use(rehypeRaw[, options]) – This function re-parses the tree, allowing for raw HTML nodes to be integrated while keeping their positional info.

Parameters include optional options for custom configurations.

Troubleshooting

If you run into any issues while using rehype-raw, consider these tips:

• Ensure that your Node.js version is compatible (v16 or higher).
• Double-check that the markdown syntax is correct, especially if using embedded HTML.
• If you encounter security warnings, consult the remark-rehype documentation for safe handling of HTML.
• For more insights, updates, or to collaborate on AI development projects, stay connected with fxis.ai.

Conclusion

With the rehype-raw plugin, you can elegantly handle the integration of raw HTML within markdown, ensuring a well-structured final product. At fxis.ai, we believe that such advancements are crucial for the future of AI, as they enable more comprehensive and effective solutions. Our team is continually exploring new methodologies to push the envelope in artificial intelligence, ensuring that our clients benefit from the latest technological innovations.