rehype-highlight

rehype plugin to highlight the syntax of code with lowlight (highlight.js).

Install

npm:

npm install rehype-highlight

Use

Say example.html looks as follows:

<h1>Hello World!</h1>

<pre><code class="language-js">var name = "World";
console.warn("Hello, " + name + "!")</code></pre>

…and example.js like this:

var vfile = require('to-vfile')
var report = require('vfile-reporter')
var rehype = require('rehype')
var highlight = require('rehype-highlight')

rehype()
  .data('settings', {fragment: true})
  .use(highlight)
  .process(vfile.readSync('example.html'), function(err, file) {
    console.error(report(err || file))
    console.log(String(file))
  })

Now, running node example yields:

example.html: no issues found
<h1>Hello World!</h1>

<pre><code class="hljs language-js"><span class="hljs-keyword">var</span> name = <span class="hljs-string">"World"</span>;
<span class="hljs-built_in">console</span>.warn(<span class="hljs-string">"Hello, "</span> + name + <span class="hljs-string">"!"</span>)</code></pre>

API

rehype().use(highlight[, options])

Syntax highlight pre > code. Uses lowlight under the hood, which is a virtual version of highlight.js.

Configure the language by using a lang-js or language-js class. Ignore code with a no-highlight or nohighlight class. Will auto-detect the syntax language otherwise.

options

options.prefix

Prefix to use before classes (string, default: 'hljs-').

options.subset

Scope of languages to check when auto-detecting (boolean or Array.<string>, default: all languages). Pass false to not highlight code without language classes.

options.ignoreMissing

Swallow errors for missing languages (boolean, default: false). By default, unregistered syntaxes throw an error when they are used. Pass true to swallow those errors and thus ignore code with unknown code languages.

options.plainText

List of plain-text languages (Array.<string>, default: []). Pass any languages you would like to be kept as plain-text instead of getting highlighted.

options.aliases

Register more aliases (Object<string | Array.<string>>, default: {}). Passed to lowlight.registerAlias.

options.languages

Register more languages (Object<string | function>, default: {}). Each key/value pair passed as arguments to lowlight.registerLanguage.

Browser

It is not suggested to require rehype-highlight in the browser as it will include all the highlighters.

⚠️ Please configure languages, as otherwise nothing gets highlighted.

In the example below, only the JavaScript and TypeScript highlighters are included:

var vfile = require('to-vfile')
var report = require('vfile-reporter')
var rehype = require('rehype')
var highlight = require('rehype-highlight/light')

rehype()
  .data('settings', {fragment: true})
  .use(highlight, {
    // Don’t forget to define the languages you need
    languages: {
      javascript: require('highlight.js/lib/languages/javascript'),
      typescript: require('highlight.js/lib/languages/typescript')
    }
  })
  .process(vfile.readSync('example.html'), function (error, file) {
    console.error(report(error || file))
    console.log(String(file))
  })

Security

Use of rehype-highlight should be safe to use as lowlight should be safe to use. When in doubt, use rehype-sanitize.

Contribute

See contributing.md in rehypejs/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer