# @mapbox/rehype-prism

> rehype plugin to highlight code blocks in HTML with Prism

Latest version **0.9.0** (published 2023-11-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install @mapbox/rehype-prism
pnpm add @mapbox/rehype-prism
yarn add @mapbox/rehype-prism
bun add @mapbox/rehype-prism
```

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.9.0 |
| Published | 2023-11-01 |
| First published | 2018-03-31 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/mapbox__rehype-prism) |
| Module format | CommonJS |
| Node | >=10 |
| Dependencies | 3 |
| Unpacked size | 12.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 173 |
| Author | Mapbox |
| Maintainers | mbx-npm-ci-production, mbx-npm-ci-staging, mbx-npm-advanced-actions-production, mbx-npm-advanced-actions-staging, mbx-npm-09-production, mbx-npm-08-production, mbx-npm-07-production, mbx-npm-06-production, mbx-npm-05-production, mbx-npm-04-production, mbx-npm-03-production, mbx-npm-02-production, mbx-npm-01-production, mbx-npm-02-staging, mapbox-npm-01, mapbox-npm-02, mapbox-npm-07, mapbox-npm-03, mapbox-npm-04, mapbox-npm-09, mapbox-npm-05, mapbox-npm-06, mapbox-npm-08, mapbox-npm-advanced-actions, mapbox-npm-ci, mapbox-npm, mapbox-admin, mapbox-machine-user |
| Keywords | rehype, rehype-plugin, syntax-highlighting, prism, html |

## Links

- npm: https://www.npmjs.com/package/@mapbox/rehype-prism
- Repository: https://github.com/mapbox/rehype-prism
- Homepage: https://github.com/mapbox/rehype-prism#readme
- Issues: https://github.com/mapbox/rehype-prism/issues
- npm.io page: https://npm.io/package/@mapbox/rehype-prism

## Dependencies (3)

- [refractor](https://npm.io/package/refractor.md) ^3.4.0
- [unist-util-visit](https://npm.io/package/unist-util-visit.md) ^2.0.3
- [hast-util-to-string](https://npm.io/package/hast-util-to-string.md) ^1.0.4

## Alternatives

- [@oh-my-pi/pi-natives](https://npm.io/package/@oh-my-pi/pi-natives.md) — 51.8K weekly downloads
- [@capgo/capacitor-light-sensor](https://npm.io/package/@capgo/capacitor-light-sensor.md) — 3.0K weekly downloads
- [@heyhuynhgiabuu/pi-diff](https://npm.io/package/@heyhuynhgiabuu/pi-diff.md) — 492 weekly downloads
- [@lotsa/verdant-lang-asm](https://npm.io/package/@lotsa/verdant-lang-asm.md) — 38 weekly downloads
- [new-era-syntax](https://npm.io/package/new-era-syntax.md) — 20 weekly downloads

## Recent versions

- 0.9.0 (latest) — 2023-11-01
- 0.8.0 — 2021-09-21
- 0.7.0 — 2021-06-30
- 0.6.0 — 2021-03-01
- 0.5.0 — 2020-06-16
- 0.4.0 — 2020-01-02
- 0.3.1 — 2019-01-23
- 0.3.0 — 2018-09-17
- 0.2.0 — 2018-03-31

## README

# @mapbox/rehype-prism

[![Build Status](https://travis-ci.com/mapbox/rehype-prism.svg?branch=main)](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 `<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](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

<details>
  <summary>Why does rehype-prism copy the <code>language-</code> class to the <code>&lt;pre&gt;</code> tag?</summary>
  
  [Prism recommends](https://prismjs.com/#basic-usage) adding the `language-` class to the `<code>` tag like this:

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

  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
  <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>
  ```

  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.
</details>

[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

---
_Source: https://npm.io/package/@mapbox/rehype-prism · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._