rehype-highlight

The plugin does exactly what it promises with minimal fuss. Drop it into your rehype pipeline, and code blocks in your HTML get syntax highlighted automatically. The integration with lowlight (highlight.js) means you get language detection out of the box, and it handles common languages without additional setup. Configuration is intuitive—pass options like `subset` to limit languages or `prefix` to customize CSS class names.

Error handling is reasonable but not exceptional. When language detection fails, it silently skips highlighting rather than throwing errors, which is usually what you want. The main gotcha is understanding that you need to bring your own CSS theme—the plugin only adds classes, not styles. This isn't documented as prominently as it should be, leading to confusion when code blocks look unstyled initially.

Debugging is straightforward since the plugin's output is just HTML with classes. When something goes wrong, inspecting the generated HTML usually reveals the issue quickly. The lack of verbose logging options means you're somewhat in the dark during processing, but the simplicity of the plugin makes this less of an issue.

rehype-highlight wraps lowlight/highlight.js in a unified/rehype pipeline, making syntax highlighting straightforward for Markdown processing. The API is minimal—just add it to your rehype chain and it handles code block detection automatically. I appreciate that it processes HTML at the AST level rather than string manipulation, which reduces XSS surface area compared to client-side highlighting.

From a security perspective, it's relatively safe since it operates server-side on your own content pipeline before output. The plugin doesn't execute arbitrary code from highlighted snippets and escapes HTML properly through hast. However, you're still trusting highlight.js's language parsers, which have had past issues with ReDoS vulnerabilities. The dependency chain includes lowlight which bundles a significant number of language grammars—monitor CVEs carefully.

Error handling is mostly silent; invalid language names just skip highlighting rather than throwing. This is pragmatic but can mask configuration issues. The plugin respects existing language classes on code blocks and integrates cleanly with remark-rehype workflows. Performance is acceptable for static site generation but can be noticeable with large codebases.

rehype-highlight integrates seamlessly into unified/rehype pipelines with a simple `.use(rehypeHighlight)` call. The plugin automatically detects language from code fence info strings and applies appropriate highlight.js classes. TypeScript support is excellent with proper types for all options, including `detect`, `subset`, `prefix`, and `aliases` configuration.

The main friction point is CSS setup—the plugin only adds classes, so you must separately import a highlight.js theme stylesheet. This isn't immediately obvious from basic examples, and newcomers often wonder why their code blocks aren't styled. Once you understand the separation of concerns (plugin handles class application, you handle styling), it's actually quite flexible.

Error handling is graceful: unrecognized languages fall back to plain text without throwing. The `subset` option for restricting languages and `aliases` for custom language names work reliably. Integration with lowlight means you get the full highlight.js language support without bundling the entire library, which is great for bundle size.