Note: This repository is no longer maintained

As of April 2024, this repo is no longer being used by the Mapbox docs team.

@mapbox/rehype-prism

rehype plugin to highlight code blocks in HTML with Prism (via refractor).

(If you would like to highlight code blocks with highlight.js, instead, check out rehype-highlight.)

Best suited for usage in Node. If you would like to perform syntax highlighting in the browser, you should look into less heavy ways to use refractor.

Installation

npm install @mapbox/rehype-prism

API

rehype().use(rehypePrism, [options])

Syntax highlights pre > code. Under the hood, it uses refractor, which is a virtual version of Prism.

The code language is configured by setting a language-{name} class on the <code> element. You can use any language supported by refractor.

If no language-{name} class is found on a <code> element, it will be skipped.

options

options.ignoreMissing

Type: boolean. Default: false.

By default, if {name} does not correspond to a language supported by refractor an error will be thrown.

If you would like to silently skip <code> elements with invalid languages, set this option to true.

options.alias

Type: Record<string, string | string[]>. Default: undefined.

Provide aliases to refractor to register as alternative names for a language.

Usage

Use this package as a rehype plugin.

Some examples of how you might do that:

1const rehype = require('rehype');
2const rehypePrism = require('@mapbox/rehype-prism');
3
4rehype()
5  .use(rehypePrism)
6  .process(/* some html */);

1const unified = require('unified');
2const rehypeParse = require('rehype-parse');
3const rehypePrism = require('@mapbox/rehype-prism');
4
5unified()
6  .use(rehypeParse)
7  .use(rehypePrism)
8  .processSync(/* some html */);

If you'd like to get syntax highlighting in Markdown, parse the Markdown (with remark-parse), convert it to rehype, then use this plugin.

1const unified = require('unified');
2const remarkParse = require('remark-parse');
3const remarkRehype = require('remark-rehype');
4const rehypePrism = require('@mapbox/rehype-prism');
5
6unified()
7  .use(remarkParse)
8  .use(remarkRehype)
9  .use(rehypePrism)
10  .process(/* some markdown */);

FAQ

1<pre><code class="language-css">p { color: red }</code></pre>

1<pre class="language-css"><code class="language-css"><span class="token selector">p</span> <span class="token punctuation">{</span> <span class="token property">color</span><span class="token punctuation">:</span> red <span class="token punctuation">}</span></code></pre>