unified and rehype
Use rehype-code-group in a unified pipeline, from Markdown or from existing HTML, alongside a syntax highlighter.
rehype-code-group is a regular unified plugin. Anything built on unified, and any tool that accepts a list of rehype plugins, can use it.
From Markdown
This is the complete pipeline, with every optional companion:
import rehypeCodeGroup from "rehype-code-group";
import remarkPackageManagers from "rehype-code-group/package-managers";
import remarkCodeGroup from "rehype-code-group/remark";
import rehypeStringify from "rehype-stringify";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import { unified } from "unified";
const processor = unified()
.use(remarkParse)
// Optional: `npm2yarn` fences become package-manager groups.
.use(remarkPackageManagers)
// Optional: `[label]` on fences instead of `labels=[…]`.
.use(remarkCodeGroup)
.use(remarkRehype)
.use(rehypeCodeGroup)
.use(rehypeStringify);
const file = await processor.process(markdown);
const html = String(file);The order matters:
remarkPackageManagerswrites fences with[label]metadata.remarkCodeGroupturns those labels into alabels=[…]line.remarkRehypeconverts Markdown to HTML.rehypeCodeGroupbuilds the tabs.
Leave out whichever companions you don't use.
From HTML
The plugin works on HTML too, because it reads paragraphs, not Markdown. Mark a group with paragraphs around the blocks:
<!doctype html>
<html>
<head>
<title>Install</title>
</head>
<body>
<p>::: code-group labels=[npm, pnpm]</p>
<pre><code>npm install rehype-code-group</code></pre>
<pre><code>pnpm add rehype-code-group</code></pre>
<p>:::</p>
</body>
</html>import { readFile, writeFile } from "node:fs/promises";
import { rehype } from "rehype";
import rehypeCodeGroup from "rehype-code-group";
const file = await rehype()
.use(rehypeCodeGroup)
.process(await readFile("page.html", "utf8"));
await writeFile("page.out.html", String(file));Because the input is a full document, the inline style and script go into its <head>.
With a syntax highlighter
rehype-code-group doesn't highlight code. It groups whatever blocks it finds, so it works with any highlighter that outputs ordinary HTML elements. Here it is with Shiki's rehype plugin:
import rehypeShiki from "@shikijs/rehype";
unified()
.use(remarkParse)
.use(remarkRehype)
.use(rehypeShiki, { theme: "github-dark" })
.use(rehypeCodeGroup)
.use(rehypeStringify);If your highlighter turns code blocks into something other than HTML elements, such as MDX components, put rehype-code-group first. See Next.js and Fumadocs for a real example.
Reading diagnostics
Malformed compact groups are reported as vfile messages, with the source rehype-code-group and the rule panel-count:
const file = await processor.process(markdown);
for (const message of file.messages) {
console.warn(String(message));
}Pass diagnostics: "error" to fail instead. process then rejects with the same message. The package-manager plugin uses the rule package-manager.
Several fragments on one page
Each call to process numbers its groups from rcg-0. If you render fragments separately and then put them on one page, give each a distinct idPrefix:
unified().use(rehypeCodeGroup, { idPrefix: `rcg-${slug}` });