rehype plugin to highlight code blocks with lowlight (highlight.js)
npm install rehype-highlight[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]
[rehype][] plugin to apply syntax highlighting to code with
[lowlight][lowlight].
* What is this?
* When should I use this?
* Install
* Use
* API
* [unified().use(rehypeHighlight[, options])](#unifieduserehypehighlight-options)
* Options
* Example
* Example: ignoring
* Example: registering
* Example: aliases
* Example: sanitation
* Example: line numbering and highlighting
* Types
* HTML
* CSS
* Compatibility
* Security
* Related
* Contribute
* License
This package is a [unified][] ([rehype][]) plugin to perform syntax
highlighting.
It uses highlight.js through lowlight, which is pretty fast, relatively
small, and quite good.
This package bundles 37 [common languages][lowlight-common] by default and you
can register more (190 with [all][lowlight-all]).
It looks for elements (when directly in elements) and changes
them.
You can specify the code language (such as Python) with a language-* orlang- class, where the can be for example js (so language-js), md,css, etc.
By default, code without such a language class is not highlighted.
Pass detect: true to detect their programming language and highlight the code
anyway.
You can prevent specific blocks from being highlighted with a no-highlight ornohighlight class on the .
unified is a project that transforms content with abstract syntax trees
(ASTs).
rehype adds support for HTML to unified.
hast is the HTML AST that rehype uses.
This is a rehype plugin that applies syntax highlighting to the AST.
This project is useful when you want to perform syntax highlighting in rehype.
One reason to do that is that it typically means the highlighting happens once
at build time instead of every time at run time.
When you want a high quality highlighter that can support tons of grammars and
approaches how GitHub renders code,
you can use [rehype-starry-night][rehype-starry-night].
This plugin is built on [lowlight][lowlight], which is a virtual version of
highlight.js.
You can make a plugin based on this one with lowlight when you want to do things
differently.
This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:
``sh`
npm install rehype-highlight
In Deno with [esm.sh][esmsh]:
`js`
import rehypeHighlight from 'https://esm.sh/rehype-highlight@6'
In browsers with [esm.sh][esmsh]:
`html`
Say we have the following file example.html:
`htmlHello World!
var name = "World";
console.warn("Hello, " + name + "!")…and our module
example.js contains:`js
import rehypeHighlight from 'rehype-highlight'
import rehypeParse from 'rehype-parse'
import rehypeStringify from 'rehype-stringify'
import {read} from 'to-vfile'
import {unified} from 'unified'const file = await read('example.html')
await unified()
.use(rehypeParse, {fragment: true})
.use(rehypeHighlight)
.use(rehypeStringify)
.process(file)
console.log(String(file))
`…then running
node example.js yields:`html
Hello World!
var name = "World";
console.warn("Hello, " + name + "!")
`API
This package exports no identifiers.
The default export is [
rehypeHighlight][api-rehype-highlight].$3
Apply syntax highlighting.
###### Parameters
*
options ([Options][api-options], optional)
— configuration###### Returns
Transform ([
Transformer][unified-transformer]).$3
Configuration (TypeScript type).
###### Fields
*
aliases (Record, optional)
— register more aliases;
passed to [lowlight.registerAlias][lowlight-register-alias]
* detect (boolean, default: false)
— highlight code without language classes by guessing its programming
language
* languages (Record, default:
[common][lowlight-common])
— register languages; passed to [lowlight.register][lowlight-register]
* plainText (Array, optional)
— list of language names to not highlight;
note you can also add no-highlight classes
* prefix (string, default: 'hljs-')
— class prefix
* subset (Array, default: default: [all][lowlight-all] registered
languages)
— names of languages to check when detectingExample
$3
There are three ways to not apply syntax highlighting to code blocks.
They can be ignored with an explicit class of
no-highlight (or nohighlight),
an explicit language name that’s listed in options.plainText, or by setting
options.detect to false (default), which prevents without a class
from being automatically detected.For example, with
example.html:`html
this won’t be highlighted due to detect: false (default)
this won’t be highlighted due to its class
this won’t be highlighted due to plainText: ['txt']
`…and
example.js:`js
import {rehype} from 'rehype'
import rehypeHighlight from 'rehype-highlight'
import {read} from 'to-vfile'const file = await rehype()
.data('settings', {fragment: true})
.use(rehypeHighlight, {plainText: ['txt', 'text']})
.process(await read('example.html'))
console.log(String(file))
`…then running that yields the same as
example.html: none of them are
highlighted.$3
rehype-highlight supports 37 commonly used languages by default.
This makes it small to load in browsers and Node.js, while supporting enough
default cases.
You can add more languages.For example, with
example.html:`html
a ::= 'a' | 'A'
`…and
example.js:`js
import bnf from 'highlight.js/lib/languages/bnf'
import {common} from 'lowlight'
import {rehype} from 'rehype'
import rehypeHighlight from 'rehype-highlight'
import {read} from 'to-vfile'const file = await rehype()
.data('settings', {fragment: true})
.use(rehypeHighlight, {languages: {...common, bnf}})
.process(await read('example.html'))
console.log(String(file))
`…then running that yields:
`html
a ::= 'a' | 'A'
`$3
You can map your own language flags to
highlight.js languages.For example, with
example.html:`html
console.log(1)
`…and
example.js:`js
import {rehype} from 'rehype'
import rehypeHighlight from 'rehype-highlight'
import {read} from 'to-vfile'const file = await rehype()
.data('settings', {fragment: true})
// 👉 Note: the keys are language names, values are the aliases that you
// want to also allow as
x in language-x classes.
.use(rehypeHighlight, {aliases: {'javascript': 'custom-script'}})
.process(await read('example.html'))console.log(String(file))
`…then running that yields:
`html
console.log(1)
`$3
Applying syntax highlighting in rehype operates on
elements with
certain classes and it injects many elements with classes.
Allowing arbitrary classes is an opening for security vulnerabilities.To make HTML safe in rehype, use [
rehype-sanitize][rehype-sanitize].
It specifically allows /^language-./ class names on elements.
Which we also use.
So you can use rehype-highlight after rehype-sanitize:`js
import {unified} from 'unified'
import rehypeHighlight from './index.js'
import rehypeParse from 'rehype-parse'
import rehypeSanitize, {defaultSchema} from 'rehype-sanitize'
import rehypeStringify from 'rehype-stringify'const file = await unified()
.use(rehypeParse, {fragment: true})
.use(rehypeSanitize)
.use(rehypeHighlight)
.use(rehypeStringify)
.process('
console.log(1)
')console.log(String(file))
`…yields:
`html
console.log(1)
`Using plugins after
rehype-sanitize, like we just did, is safe assuming
you trust those plugins.
If you do not trust rehype-highlight, you can use it before.
But then you need to configure rehype-sanitize to keep the classes you allow:`js
import {unified} from 'unified'
import rehypeHighlight from './index.js'
import rehypeParse from 'rehype-parse'
import rehypeSanitize, {defaultSchema} from 'rehype-sanitize'
import rehypeStringify from 'rehype-stringify'const file = await unified()
.use(rehypeParse, {fragment: true})
.use(rehypeHighlight)
.use(rehypeSanitize, {
...defaultSchema,
attributes: {
...defaultSchema.attributes,
span: [
...(defaultSchema.attributes?.span || []),
// Allow all class names starting with
hljs-.
['className', /^hljs-./]
// Alternatively, to allow only certain class names:
// ['className', 'hljs-number', 'hljs-title', 'hljs-variable']
]
},
tagNames: [...(defaultSchema.tagNames || []), 'span']
})
.use(rehypeStringify)
.process('console.log(1)
')console.log(String(file))
`$3
You can add support for line numbers and line highlighting with a separate
plugin, [
rehype-highlight-code-lines][rehype-highlight-code-lines].For example, with
example.html:`html
console.log("Hi!")
`…and
example.js:`js
import {rehype} from 'rehype'
import rehypeHighlight from 'rehype-highlight'
import rehypeHighlightCodeLines from 'rehype-highlight-code-lines'
import {read} from 'to-vfile'const file = await rehype()
.data('settings', {fragment: true})
.use(rehypeHighlight)
.use(rehypeHighlightCodeLines, {
showLineNumbers: true,
lineContainerTagName: 'div'
})
.process(await read('example.html'))
console.log(String(file))
`…then running that yields:
`html
console.log("Hi!")
`Types
This package is fully typed with [TypeScript][].
It exports the additional type [
Options][api-options].HTML
On the input side,
this plugin looks for code blocks with a
language-* class.On the output side,
this plugin generates
span elements with classes that can be enhanced with
CSS.CSS
See [“CSS” in
lowlight][github-lowlight-css] for more info.Compatibility
Projects maintained by the unified collective are compatible with maintained
versions of Node.js.
When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
rehype-highlight@^7,
compatible with Node.js 16.This plugin works with
rehype-parse version 1+, rehype-stringify version 1+,
rehype version 1+, and unified version 4+.Security
Use of
rehype-highlight should be safe to use as highlight.js and
lowlight should be safe to use.
When in doubt, use [rehype-sanitize][rehype-sanitize].Related
* [
rehype-starry-night][rehype-starry-night]
— apply syntax highlighting with starry-night
* rehype-meta
— add metadata to the head of a document
* rehype-document
— wrap a fragment in a document
* [rehype-highlight-code-lines][rehype-highlight-code-lines]
— add line numbers and highlight linesContribute
See [
contributing.md][contributing] in [rehypejs/.github][health] for ways
to get started.
See [support.md`][support] for ways to get help.This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.
License
[MIT][license] © [Titus Wormer][author]
[api-options]: #options
[api-rehype-highlight]: #unifieduserehypehighlight-options
[author]: https://wooorm.com
[backers-badge]: https://opencollective.com/unified/backers/badge.svg
[build]: https://github.com/rehypejs/rehype-highlight/actions
[build-badge]: https://github.com/rehypejs/rehype-highlight/workflows/main/badge.svg
[chat]: https://github.com/rehypejs/rehype/discussions
[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg
[coc]: https://github.com/rehypejs/.github/blob/HEAD/code-of-conduct.md
[collective]: https://opencollective.com/unified
[contributing]: https://github.com/rehypejs/.github/blob/HEAD/contributing.md
[coverage]: https://codecov.io/github/rehypejs/rehype-highlight
[coverage-badge]: https://img.shields.io/codecov/c/github/rehypejs/rehype-highlight.svg
[downloads]: https://www.npmjs.com/package/rehype-highlight
[downloads-badge]: https://img.shields.io/npm/dm/rehype-highlight.svg
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
[esmsh]: https://esm.sh
[github-lowlight-css]: https://github.com/wooorm/lowlight#css
[health]: https://github.com/rehypejs/.github
[license]: license
[lowlight]: https://github.com/wooorm/lowlight
[lowlight-all]: https://github.com/wooorm/lowlight#all
[lowlight-common]: https://github.com/wooorm/lowlight#common
[lowlight-register]: https://github.com/wooorm/lowlight#lowlightregistergrammars
[lowlight-register-alias]: https://github.com/wooorm/lowlight#lowlightregisteraliasaliases
[npm]: https://docs.npmjs.com/cli/install
[rehype]: https://github.com/rehypejs/rehype
[rehype-highlight-code-lines]: https://github.com/ipikuka/rehype-highlight-code-lines
[rehype-sanitize]: https://github.com/rehypejs/rehype-sanitize
[rehype-starry-night]: https://github.com/rehypejs/rehype-starry-night
[size]: https://bundlejs.com/?q=rehype-highlight
[size-badge]: https://img.shields.io/bundlejs/size/rehype-highlight
[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
[support]: https://github.com/rehypejs/.github/blob/HEAD/support.md
[typescript]: https://www.typescriptlang.org
[unified]: https://github.com/unifiedjs/unified
[unified-transformer]: https://github.com/unifiedjs/unified#transformer