Attention: This package is no longer maintained

⚠️ This is Fork from mdx-prism which automate the release process. There are a few fixes that does not have a published version there.

Maybe in the future I can delete this repository in favor of having a single but for now I need things a bit more professional.

mdx-prism-2

This is a fork of @mapbox/rehype-prism that adds line highlighting capabilities, e.g.:

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 mdx-prism-2

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

| Parameter | Type | Default | Description | | :------------------------ | :----------------------------------------------------------------------------------: | :----------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ignoreMissing | boolean | 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. | | lineHighlight.component | string (HTML element) | div | The HTML tag used to wrap the highlight line. | | lineHighlight.className | string | mdx-marker | CSS class applied to highlight line. |

Usage

Use this package as a rehype plugin.

Some examples of how you might do that:

const rehype = require('rehype');
const mdxPrism = require('mdx-prism-2');

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

const rehype = require('rehype');
const mdxPrism = require('mdx-prism-2');

rehype()
  .use(mdxPrism, {
    lineHighlight: {
      component: 'span',
      className: 'my-line-highlight-class',
    },
  })
  .process(/* some html */);

const unified = require('unified');
const rehypeParse = require('rehype-parse');
const mdxPrism = require('mdx-prism-2');

unified().use(rehypeParse).use(mdxPrism).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 mdxPrism = require('mdx-prism-2');

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

FAQ

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 mdx-prism-2 to get the most out of these themes, we decided to do the same.