rehype-highlight

rehype plugin to apply syntax highlighting to code with lowlight.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • unified().use(rehypeHighlight[, options])
  • Options
• Example
  • Example: ignoring
  • Example: registering
  • Example: aliases
  • Example: sanitation
  • Example: line numbering and highlighting
• Types
• HTML
• CSS
• Compatibility
• Security
• Related
• Contribute
• License

What is this?

This package is a unified (rehype) plugin to perform syntax highlighting. It uses highlight.js through lowlight, which is pretty fast, relatively small, and quite good. This package bundles 37 common languages by default and you can register more (190 with all).

It looks for <code> elements (when directly in <pre> elements) and changes them. You can specify the code language (such as Python) with a language-* or lang-* class, where the * can be for example js (so language-js), md, css, etc. By default, code without such a language class is not highlighted. Pass detect: true to detect their programming language and highlight the code anyway. You can prevent specific blocks from being highlighted with a no-highlight or nohighlight class on the <code>.

unified is a project that transforms content with abstract syntax trees (ASTs). rehype adds support for HTML to unified. hast is the HTML AST that rehype uses. This is a rehype plugin that applies syntax highlighting to the AST.

When should I use this?

This project is useful when you want to perform syntax highlighting in rehype. One reason to do that is that it typically means the highlighting happens once at build time instead of every time at run time.

When you want a high quality highlighter that can support tons of grammars and approaches how GitHub renders code, you can use rehype-starry-night.

This plugin is built on lowlight, which is a virtual version of highlight.js. You can make a plugin based on this one with lowlight when you want to do things differently.

Install

This package is ESM only. In Node.js (version 16+), install with npm:

npm install rehype-highlight

In Deno with esm.sh:

import rehypeHighlight from 'https://esm.sh/rehype-highlight@6'

In browsers with esm.sh:

<script type="module">
  import rehypeHighlight from 'https://esm.sh/rehype-highlight@6?bundle'
</script>

Use

Say we have the following file example.html:

<h1>Hello World!</h1>

<pre><code class="language-js">var name = "World";
console.warn("Hello, " + name + "!")</code></pre>

…and our module example.js contains:

import {rehype} from 'rehype'
import rehypeHighlight from 'rehype-highlight'
import {read} from 'to-vfile'

const file = await rehype()
  .data('settings', {fragment: true})
  .use(rehypeHighlight)
  .process(await read('example.html'))

console.log(String(file))

…then running node example.js yields:

<h1>Hello World!</h1>

<pre><code class="hljs language-js"><span class="hljs-keyword">var</span> name = <span class="hljs-string">"World"</span>;
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">warn</span>(<span class="hljs-string">"Hello, "</span> + name + <span class="hljs-string">"!"</span>)</code></pre>

API

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

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

Apply syntax highlighting.

Parameters

• options (Options, optional) — configuration

Returns

Transform (Transformer).

Options

Configuration (TypeScript type).

Fields

• aliases (Record<string, Array<string> | string>, optional) — register more aliases; passed to lowlight.registerAlias
• detect (boolean, default: false) — highlight code without language classes by guessing its programming language
• languages (Record<string, LanguageFn>, default: common) — register languages; passed to lowlight.register
• plainText (Array<string>, optional) — list of language names to not highlight; note you can also add no-highlight classes
• prefix (string, default: 'hljs-') — class prefix
• subset (Array<string>, default: default: all registered languages) — names of languages to check when detecting

Example

Example: ignoring

There are three ways to not apply syntax highlighting to code blocks. They can be ignored with an explicit class of no-highlight (or nohighlight), an explicit language name that’s listed in options.plainText, or by setting options.detect to false (default), which prevents <code> without a class from being automatically detected.

For example, with example.html:

<pre><code>this won’t be highlighted due to `detect: false` (default)</code></pre>

<pre><code class="no-highlight">this won’t be highlighted due to its class</code></pre>

<pre><code class="language-txt">this won’t be highlighted due to `plainText: ['txt']`</code></pre>

…and example.js:

import {rehype} from 'rehype'
import rehypeHighlight from 'rehype-highlight'
import {read} from 'to-vfile'

const file = await rehype()
  .data('settings', {fragment: true})
  .use(rehypeHighlight, {plainText: ['txt', 'text']})
  .process(await read('example.html'))

console.log(String(file))

…then running that yields the same as example.html: none of them are highlighted.

Example: registering

rehype-highlight supports 37 commonly used languages by default. This makes it small to load in browsers and Node.js, while supporting enough default cases. You can add more languages.

For example, with example.html:

<pre><code class="language-bnf">a ::= 'a' | 'A'</code></pre>

…and example.js:

import bnf from 'highlight.js/lib/languages/bnf'
import {common} from 'lowlight'
import {rehype} from 'rehype'
import rehypeHighlight from 'rehype-highlight'
import {read} from 'to-vfile'

const file = await rehype()
  .data('settings', {fragment: true})
  .use(rehypeHighlight, {languages: {...common, bnf}})
  .process(await read('example.html'))

console.log(String(file))

…then running that yields:

<pre><code class="hljs language-bnf">a ::= <span class="hljs-string">'a'</span> | <span class="hljs-string">'A'</span></code></pre>

Example: aliases

You can map your own language flags to highlight.js languages.

For example, with example.html:

<pre><code class="language-custom-script">console.log(1)</code></pre>

…and example.js:

import {rehype} from 'rehype'
import rehypeHighlight from 'rehype-highlight'
import {read} from 'to-vfile'

const file = await rehype()
  .data('settings', {fragment: true})
  // 👉 **Note**: the keys are language names, values are the aliases that you
  // want to also allow as `x` in `language-x` classes.
  .use(rehypeHighlight, {aliases: {'javascript': 'custom-script'}})
  .process(await read('example.html'))

console.log(String(file))

…then running that yields:

<pre><code class="hljs language-custom-script"><span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-number">1</span>)</code></pre>

Example: sanitation

Applying syntax highlighting in rehype operates on <code> elements with certain classes and it injects many <span> elements with classes. Allowing arbitrary classes is an opening for security vulnerabilities.

To make HTML safe in rehype, use rehype-sanitize. It specifically allows /^language-./ class names on <code> elements. Which we also use. So you can use rehype-highlight after rehype-sanitize:

import {unified} from 'unified'
import rehypeHighlight from './index.js'
import rehypeParse from 'rehype-parse'
import rehypeSanitize, {defaultSchema} from 'rehype-sanitize'
import rehypeStringify from 'rehype-stringify'

const file = await unified()
  .use(rehypeParse, {fragment: true})
  .use(rehypeSanitize)
  .use(rehypeHighlight)
  .use(rehypeStringify)
  .process('<pre><code className="language-js">console.log(1)</code></pre>')

console.log(String(file))

…yields:

<pre><code class="hljs language-js"><span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-number">1</span>)</code></pre>

Using plugins after rehype-sanitize, like we just did, is safe assuming you trust those plugins. If you do not trust rehype-highlight, you can use it before. But then you need to configure rehype-sanitize to keep the classes you allow:

import {unified} from 'unified'
import rehypeHighlight from './index.js'
import rehypeParse from 'rehype-parse'
import rehypeSanitize, {defaultSchema} from 'rehype-sanitize'
import rehypeStringify from 'rehype-stringify'

const file = await unified()
  .use(rehypeParse, {fragment: true})
  .use(rehypeHighlight)
  .use(rehypeSanitize, {
    ...defaultSchema,
    attributes: {
      ...defaultSchema.attributes,
      span: [
        ...(defaultSchema.attributes?.span || []),
        // Allow all class names starting with `hljs-`.
        ['className', /^hljs-./]
        // Alternatively, to allow only certain class names:
        // ['className', 'hljs-number', 'hljs-title', 'hljs-variable']
      ]
    },
    tagNames: [...(defaultSchema.tagNames || []), 'span']
  })
  .use(rehypeStringify)
  .process('<pre><code className="language-js">console.log(1)</code></pre>')

console.log(String(file))

Example: line numbering and highlighting

You can add support for line numbers and line highlighting with a separate plugin, rehype-highlight-code-lines.

For example, with example.html:

<pre><code class="language-js">console.log("Hi!")</code></pre>

…and example.js:

import {rehype} from 'rehype'
import rehypeHighlight from 'rehype-highlight'
import rehypeHighlightCodeLines from 'rehype-highlight-code-lines'
import {read} from 'to-vfile'

const file = await rehype()
  .data('settings', {fragment: true})
  .use(rehypeHighlight)
  .use(rehypeHighlightCodeLines, {
    showLineNumbers: true,
    lineContainerTagName: 'div'
  })
  .process(await read('example.html'))

console.log(String(file))

…then running that yields:

<pre><code class="hljs language-js"><div class="code-line numbered-code-line" data-line-number="1"><span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">"Hi!"</span>)</div></code></pre>

Types

This package is fully typed with TypeScript. It exports the additional type Options.

HTML

On the input side, this plugin looks for code blocks with a language-* class.

On the output side, this plugin generates span elements with classes that can be enhanced with CSS.

CSS

See “CSS” in lowlight for more info.

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, rehype-highlight@^7, compatible with Node.js 16.

This plugin works with rehype-parse version 1+, rehype-stringify version 1+, rehype version 1+, and unified version 4+.

Security

Use of rehype-highlight should be safe to use as highlight.js and lowlight should be safe to use. When in doubt, use rehype-sanitize.

Related

• rehype-starry-night — apply syntax highlighting with starry-night
• rehype-meta — add metadata to the head of a document
• rehype-document — wrap a fragment in a document
• rehype-highlight-code-lines — add line numbers and highlight lines

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