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

Syntax highlighting for rehype.

Installation

npm:

npm install rehype-highlight

Usage

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

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

options.subset

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

License

MIT © Titus Wormer