rehype-highlight

rehype-highlight is a rehype plugin that walks the HTML syntax tree (hast) a unified pipeline has already parsed, finds <pre><code> blocks, and applies syntax highlighting to them with lowlight, a virtual/AST-based wrapper around highlight.js. It looks for language-* or lang-* classes to decide which grammar to apply, and can optionally guess a language automatically with detect: true.

Because the highlighting happens once on the AST at build time rather than in the browser, pages ship with no client-side highlighter and no highlighting-related layout shift or flash of unstyled code. It bundles 37 common highlight.js languages out of the box, supports registering the full ~190-language set or custom grammars, and composes safely with rehype-sanitize for untrusted HTML.

What You Get

• A default-exported unified/rehype plugin usable as unified().use(rehypeHighlight, options)
• 37 bundled highlight.js languages via lowlight’s common set, with opt-in access to the full ~190-language all set or custom grammars
• A fully typed Options object (aliases, detect, languages, plainText, prefix, subset) generated from JSDoc via TypeScript’s checkJs/declaration emit
• Zero client-side runtime cost — highlighting is computed once at build time and baked into the output HTML

Common Use Cases

• Highlighting fenced code blocks in statically generated documentation and blog sites
• Adding syntax highlighting to Markdown-to-HTML pipelines built on remark/rehype
• Composing with rehype-sanitize for safe highlighting of untrusted or CMS-authored HTML

Under The Hood

Architecture — The plugin is a single factory function (lib/index.js, ~182 lines) that returns a unified transformer. The transformer uses unist-util-visit to walk the hast tree looking for <code> elements directly inside <pre>, reads the code’s text with hast-util-to-text, and delegates the actual tokenization to a lowlight instance created via createLowlight(languages). Highlighted output replaces the node’s children in place and a hljs/language-* class is added — the whole transform is synchronous and side-effect-free outside the tree it’s given.

Tech Stack — The package is ESM-only ("type": "module"), depends on @types/hast, hast-util-to-text, lowlight (^3), unist-util-visit, and vfile, and targets Node.js 16+. Types are authored as JSDoc comments and compiled to .d.ts/.d.ts.map via tsc --build with checkJs and exactOptionalPropertyTypes enabled, so there’s no separate TypeScript source tree to maintain — the JS is the source of truth for both runtime and types.

Code Quality — test.js (508 lines) uses Node’s built-in node:test/node:assert runner against real unified/rehype pipelines (parse → highlight → stringify) rather than mocking internals, and c8 --100 enforces full statement/branch coverage on every test run. type-coverage is configured with atLeast: 100 in strict mode, so the JSDoc-derived types must fully cover the code — a notably rigorous bar for a project this size.

API Design — The public surface is a single default export with an optional Options object whose defaults (detect: false, prefix: 'hljs-') are safe no-ops, so .use(rehypeHighlight) with zero configuration is a valid starting point. Escape hatches (aliases, languages, plainText, subset) are additive rather than required, keeping the common case boilerplate-free while still supporting advanced registration and sanitization scenarios documented with runnable examples in the README.