rehype-prism-plus

rehype plugin to highlight code blocks in HTML with Prism (via refractor) with additional line highlighting and line numbers functionalities.

Inspired by and uses a compatible API as @mapbox/rehype-prism with additional support for line-highlighting, line numbers and diff code blocks.

Tested to work with xdm and mdx v2 libraries such as mdx-bundler. If you are using mdx v1 libraries such as next-mdx-remote, you will need to patch it with the fixMetaPlugin discussed in this issue, before rehype-prism-plus.

An appropriate stylesheet should be loaded to style the language tokens, format line numbers and highlight lines. You can specify language for diff code blocks by using diff-[language] to enable syntax highlighting in diffs.

Installation

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm install rehype-prism-plus

Usage

The following import paths are supported:

• rehype-prism-plus/generator, generator function. Can be used to generate a rehype prism plugin that works on your desired languages.
• rehype-prism-plus/common, rehype plugin. Supports the languages in refractor/lib/common.js.
• rehype-prism-plus/all, rehype plugin. Works with all language supported by refractor.
• rehype-prism-plus, re-exports the above 3 packages with rehype-prism-plus/all as the default export.

Some examples of how you might use the rehype plugin:

1import rehype from 'rehype'
2import rehypePrism from 'rehype-prism-plus'
3
4rehype().use(rehypePrism).process(/* some html */)

Here's an example of syntax highlighting in Markdown, with xdm

1import { compile } from 'xdm'
2import rehypePrism from 'rehype-prism-plus'
3
4async function main(code) {
5  console.log(String(await compile(code, { rehypePlugins: [rehypePrism] })))
6}
7
8main(`~~~js
9console.log(1)
10~~~`)

Sample markdown to HTML output

Input:

1```js {1,3-4} showLineNumbers
2function fancyAlert(arg) {
3  if (arg) {
4    $.facebox({ div: '#foo' })
5  }
6}
7```

HTML Output:

1<code class="language-js">
2  <div class="code-line line-number highlight-line" line="1">
3    <span class="keyword">function</span>
4    <span class="function">fancyAlert</span><span class="punctuation">(</span
5    ><span class="">arg</span><span class="punctuation">)</span>
6    <span class="punctuation">{</span>
7  </div>
8  <div class="code-line line-number highlight-line" line="2">
9    <span class="keyword">if</span>
10    <span class="punctuation">(</span>arg<span class="punctuation">)</span>
11    <span class="punctuation">{</span>
12  </div>
13  <div class="code-line line-number" line="3">
14    $<span class="punctuation">.</span><span class="function">facebox</span
15    ><span class="punctuation">(</span><span class="punctuation">{</span> div<span class="">:</span>
16    <span class="string">'#foo'</span>
17    <span class="punctuation">}</span><span class="punctuation">)</span>
18  </div>
19  <div class="code-line line-number" line="4">
20    <span class="punctuation">}</span>
21  </div>
22  <div class="code-line line-number" line="5">
23    <span class="punctuation">}</span>
24  </div></code
25>

Generating

To customise the languages for your own prism plugin:

1import { refractor } from 'refractor/lib/core.js'
2import markdown from 'refractor/lang/markdown.js'
3import rehypePrismGenerator from 'rehype-prism-plus/generator'
4
5refractor.register(markdown)
6const myPrismPlugin = rehypePrismGenerator(refractor)

Styling

To style the language tokens, you can just copy them from any prismjs compatible ones. Here's a list of themes.

In addition, the following styles should be added for line highlighting and line numbers to work correctly:

1pre {
2  overflow-x: auto;
3}
4
5/**
6 * Inspired by gatsby remark prism - https://www.gatsbyjs.com/plugins/gatsby-remark-prismjs/
7 * 1. Make the element just wide enough to fit its content.
8 * 2. Always fill the visible space in .code-highlight.
9 */
10.code-highlight {
11  float: left; /* 1 */
12  min-width: 100%; /* 2 */
13}
14
15.code-line {
16  display: block;
17  padding-left: 16px;
18  padding-right: 16px;
19  margin-left: -16px;
20  margin-right: -16px;
21  border-left: 4px solid rgba(0, 0, 0, 0); /* Set placeholder for highlight accent border color to transparent */
22}
23
24.code-line.inserted {
25  background-color: rgba(16, 185, 129, 0.2); /* Set inserted line (+) color */
26}
27
28.code-line.deleted {
29  background-color: rgba(239, 68, 68, 0.2); /* Set deleted line (-) color */
30}
31
32.highlight-line {
33  margin-left: -16px;
34  margin-right: -16px;
35  background-color: rgba(55, 65, 81, 0.5); /* Set highlight bg color */
36  border-left: 4px solid rgb(59, 130, 246); /* Set highlight accent border color */
37}
38
39.line-number::before {
40  display: inline-block;
41  width: 1rem;
42  text-align: right;
43  margin-right: 16px;
44  margin-left: -8px;
45  color: rgb(156, 163, 175); /* Line number color */
46  content: attr(line);
47}

Here's the styled output using the prism-night-owl theme:

For more information on styling of language tokens, consult refractor and 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 or support line numbers and line highlighting for code blocks without a specified language, set this option to true.

options.defaultLanguage

Type: string. Default: ``.

Uses the specified language as the default if none is specified. Takes precedence over ignoreMissing.

Note: The language must be first registered with refractor.

options.showLineNumbers

Type: boolean. Default: false.

By default, line numbers will only be displayed for code block cells with a meta property that includes 'showLineNumbers'. To control the starting line number use showLineNumbers=X, where X is the starting line number as a meta property for the code block.

If you would like to show line numbers for all code blocks, without specifying the meta property, set this to true.

Note: This will wrongly assign a language class and the class might appear as language-{1,3} or language-showLineNumbers, but allow the language highlighting and line number function to work. An possible approach would be to add a placeholder like unknown so the div will have class="language-unknown"