https://github.com/mapbox/rehype-prism
rehype plugin to highlight code blocks in HTML with Prism (via refractor)
https://github.com/mapbox/rehype-prism
docs-infrastructure
Last synced: 26 days ago
JSON representation
rehype plugin to highlight code blocks in HTML with Prism (via refractor)
- Host: GitHub
- URL: https://github.com/mapbox/rehype-prism
- Owner: mapbox
- License: mit
- Archived: true
- Created: 2017-06-21T23:04:19.000Z (almost 8 years ago)
- Default Branch: main
- Last Pushed: 2024-04-16T15:39:51.000Z (about 1 year ago)
- Last Synced: 2025-04-23T23:39:02.808Z (about 1 month ago)
- Topics: docs-infrastructure
- Language: JavaScript
- Homepage:
- Size: 325 KB
- Stars: 176
- Watchers: 104
- Forks: 24
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-rehype - rehype-prism - Highlight code blocks with [refractor](https://github.com/wooorm/refractor) (Prism). (Plugins)
README
## 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
[](https://travis-ci.com/mapbox/rehype-prism)
[rehype](https://github.com/wooorm/rehype) plugin to highlight code blocks in HTML with [Prism] (via [refractor]).
(If you would like to highlight code blocks with [highlight.js](https://github.com/isagalaev/highlight.js), instead, check out [rehype-highlight](https://github.com/wooorm/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](https://github.com/wooorm/refractor#browser).
## 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 `` element.
You can use any [language supported by refractor].
If no `language-{name}` class is found on a `` 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 `` elements with invalid languages, set this option to `true`.
#### options.alias
Type: `Record`.
Default: `undefined`.
Provide [aliases] to refractor to register as alternative names for a language.
## Usage
Use this package [as a rehype plugin](https://github.com/rehypejs/rehype/blob/master/doc/plugins.md#using-plugins).
Some examples of how you might do that:
```js
const rehype = require('rehype');
const rehypePrism = require('@mapbox/rehype-prism');
rehype()
.use(rehypePrism)
.process(/* some html */);
```
```js
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.
```js
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](https://prismjs.com/#basic-usage) adding the `language-` class to the `` 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 `
` tag:
```html
p { color: red }
```
This resulted in many [Prism themes](https://github.com/PrismJS/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.
[Prism]: http://prismjs.com/
[refractor]: https://github.com/wooorm/refractor
[language supported by refractor]: https://github.com/wooorm/refractor#syntaxes
[aliases]: https://github.com/wooorm/refractor#refractoraliasname-alias