@mapbox/rehype-prism

rehype plugin to highlight code blocks in HTML with Prism

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
@mapbox/rehype-prism
14190.8.0a year ago5 years agoMinified + gzip package size for @mapbox/rehype-prism in KB

Readme

@mapbox/rehype-prism
Build Status
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:
const rehype = require('rehype');
const rehypePrism = require('@mapbox/rehype-prism');

rehype()
  .use(rehypePrism)
  .process(/* some html */);

const unified = require('unified');
const rehypeParse = require('rehype-parse');
const rehypePrism = require('@mapbox/rehype-prism');

unified()
  .use(rehypeParse)
  .use(rehypePrism)
  .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.
const unified = require('unified');
const remarkParse = require('remark-parse');
const remarkRehype = require('remark-rehype');
const rehypePrism = require('@mapbox/rehype-prism');

unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypePrism)
  .process(/* some markdown */);

FAQ

Why does rehype-prism copy the language- class to the <pre> tag?
Prism recommends adding the language- class to the <code> tag like this:
```html
p { color: red }
```
It bases this recommendation on the HTML5 spec. However, an undocumented behavior of their JavaScript is that, in the process of highlighting the code, they also copy the language- class to the <pre> tag:
```html
p { color: red }
```
This resulted in many Prism themes relying on this behavior by using CSS selectors like pre[class*="language-"]. So in order for people using rehype-prism to get the most out of these themes, we decided to do the same.