rehype-highlight

What is rehype-highlight?

rehype-highlight is a plugin for the rehype ecosystem that provides syntax highlighting for code blocks in HTML. It uses the popular highlight.js library under the hood to perform the actual highlighting.

What are rehype-highlight's main functionalities?

Basic Syntax Highlighting

This feature allows you to add syntax highlighting to code blocks in your HTML. The code sample demonstrates how to use rehype-highlight to process an HTML string containing a JavaScript code block.

const rehype = require('rehype');
const rehypeHighlight = require('rehype-highlight');

rehype()
  .use(rehypeHighlight)
  .process('<pre><code class="language-js">const x = 42;</code></pre>', function (err, file) {
    if (err) throw err;
    console.log(String(file));
  });

Custom Languages

This feature allows you to add custom languages for syntax highlighting. The code sample shows how to include a custom language definition and use it with rehype-highlight.

const rehype = require('rehype');
const rehypeHighlight = require('rehype-highlight');
const customLanguage = require('highlight.js/lib/languages/yourLanguage');

rehype()
  .use(rehypeHighlight, { languages: { yourLanguage: customLanguage } })
  .process('<pre><code class="language-yourLanguage">your code here</code></pre>', function (err, file) {
    if (err) throw err;
    console.log(String(file));
  });

Custom Highlight.js Configuration

This feature allows you to configure highlight.js options, such as specifying a subset of languages to include. The code sample demonstrates how to limit the languages to JavaScript and Python.

const rehype = require('rehype');
const rehypeHighlight = require('rehype-highlight');

rehype()
  .use(rehypeHighlight, { subset: ['javascript', 'python'] })
  .process('<pre><code class="language-js">const x = 42;</code></pre>', function (err, file) {
    if (err) throw err;
    console.log(String(file));
  });

Other packages similar to rehype-highlight

prismjs

Prism is a lightweight, extensible syntax highlighter. It is a popular alternative to highlight.js and offers a wide range of plugins and themes. Unlike rehype-highlight, which is a rehype plugin, Prism can be used directly in the browser or with various build tools.

highlight.js

highlight.js is the underlying library used by rehype-highlight for syntax highlighting. It can be used directly without the rehype ecosystem, offering more control and customization options for users who do not need the additional features provided by rehype.

shiki

Shiki is a syntax highlighter that uses TextMate grammar and VS Code themes. It provides high-quality highlighting and is designed to be used in Node.js environments. Shiki offers a different approach to syntax highlighting compared to rehype-highlight, focusing on using VS Code's ecosystem.

README

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.

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