Nutritious Potato Munchies

    @mapbox/rehype-prism
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/mapbox__rehype-prism package

    0.8.0 • Public • Published

    @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:

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

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

    Install

    npm i @mapbox/rehype-prism

    DownloadsWeekly Downloads

    35,597

    Version

    0.8.0

    License

    MIT

    Unpacked Size

    13.4 kB

    Total Files

    10

    Last publish

    Collaborators

    • 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