Lowlight
Virtual syntax highlighting for virtual DOMs and non-HTML things
Install / Use
/learn @wooorm/LowlightREADME
lowlight
[![Build][build-badge]][build] [![Coverage][coverage-badge]][coverage] [![Downloads][downloads-badge]][downloads] [![Size][size-badge]][size]
Virtual syntax highlighting for virtual DOMs and non-HTML things based on
[highlight.js][highlight-js].
Contents
- What is this?
- When should I use this?
- Install
- Use
- API
- Examples
- Types
- Data
- CSS
- Compatibility
- Security
- Related
- Projects
- Contribute
- License
What is this?
This package uses [highlight.js][highlight-js] for syntax highlighting and
outputs objects (ASTs) instead of a string of HTML.
It can support 190+ programming languages.
When should I use this?
This package is useful when you want to perform syntax highlighting in a place where serialized HTML wouldn’t work or wouldn’t work well. For example, you can use lowlight when you want to show code in a CLI by rendering to ANSI sequences, when you’re using virtual DOM frameworks (such as React or Preact) so that diffing can be performant, or when you’re working with ASTs (rehype).
You can use the similar [refractor][refractor] if you want to use [Prism][]
grammars instead.
If you’re looking for a really good (but rather heavy) alternative, use
[starry-night][starry-night].
Install
This package is [ESM only][esm]. In Node.js (version 16+), install with [npm][]:
npm install lowlight
In Deno with [esm.sh][esmsh]:
import {all, common, createLowlight} from 'https://esm.sh/lowlight@3'
In browsers with [esm.sh][esmsh]:
<script type="module">
import {all, common, createLowlight} from 'https://esm.sh/lowlight@3?bundle'
</script>
Use
import {common, createLowlight} from 'lowlight'
const lowlight = createLowlight(common)
const tree = lowlight.highlight('js', '"use strict";')
console.dir(tree, {depth: undefined})
Yields:
{
type: 'root',
children: [
{
type: 'element',
tagName: 'span',
properties: {className: ['hljs-meta']},
children: [{type: 'text', value: '"use strict"'}]
},
{type: 'text', value: ';'}
],
data: {language: 'js', relevance: 10}
}
API
This package exports the identifiers [all][api-all],
[common][api-common], and
[createLowlight][api-create-lowlight].
There is no default export.
all
Map of all (±190) grammars ([Record<string, LanguageFn>][api-language-fn]).
common
Map of common (37) grammars ([Record<string, LanguageFn>][api-language-fn]).
createLowlight([grammars])
Create a lowlight instance.
Parameters
grammars([Record<string, LanguageFn>][api-language-fn], optional) — grammars to add
Returns
Lowlight (Lowlight).
lowlight.highlight(language, value[, options])
Highlight value (code) as language (name).
Parameters
language(string) — programming language [name][names]value(string) — code to highlightoptions([Options][api-options], optional) — configuration
Returns
Tree ([Root][hast-root]); with the following data fields: language
(string), detected programming language name; relevance (number), how
sure lowlight is that the given code is in the language.
Example
import {common, createLowlight} from 'lowlight'
const lowlight = createLowlight(common)
console.log(lowlight.highlight('css', 'em { color: red }'))
Yields:
{type: 'root', children: [Array], data: {language: 'css', relevance: 3}}
lowlight.highlightAuto(value[, options])
Highlight value (code) and guess its programming language.
Parameters
value(string) — code to highlightoptions([AutoOptions][api-auto-options], optional) — configuration
Returns
Tree ([Root][hast-root]); with the following data fields: language
(string), detected programming language name; relevance (number), how
sure lowlight is that the given code is in the language.
Example
import {common, createLowlight} from 'lowlight'
const lowlight = createLowlight(common)
console.log(lowlight.highlightAuto('"hello, " + name + "!"'))
Yields:
{type: 'root', children: [Array], data: {language: 'arduino', relevance: 2}}
lowlight.listLanguages()
List registered languages.
Returns
[Names][] of registered language (Array<string>).
Example
import {createLowlight} from 'lowlight'
import markdown from 'highlight.js/lib/languages/markdown'
const lowlight = createLowlight()
console.log(lowlight.listLanguages()) // => []
lowlight.register({markdown})
console.log(lowlight.listLanguages()) // => ['markdown']
lowlight.register(grammars)
Register languages.
Signatures
register(name, grammar)register(grammars)
Parameters
name(string) — programming language [name][names]grammar([LanguageFn][api-language-fn]) — grammargrammars([Record<string, LanguageFn>][api-language-fn], optional) — grammars
Returns
Nothing (undefined).
Example
import {createLowlight} from 'lowlight'
import xml from 'highlight.js/lib/languages/xml'
const lowlight = createLowlight()
lowlight.register({xml})
// Note: `html` is an alias for `xml`.
console.log(lowlight.highlight('html', '<em>Emphasis</em>'))
Yields:
{type: 'root', children: [Array], data: {language: 'html', relevance: 2}}
lowlight.registerAlias(aliases)
Register aliases.
Signatures
registerAlias(aliases)registerAlias(name, alias)
Parameters
aliases(Record<string, Array<string> | string>) — map of programming language [names][] to one or more aliasesname(string) — programming language [name][names]alias(Array<string> | string) — one or more aliases for the programming language
Returns
Nothing (undefined).
Example
import {createLowlight} from 'lowlight'
import markdown from 'highlight.js/lib/languages/markdown'
const lowlight = createLowlight()
lowlight.register({markdown})
// lowlight.highlight('mdown', '<em>Emphasis</em>')
// ^ would throw: Error: Unknown language: `mdown` is not registered
lowlight.registerAlias({markdown: ['mdown', 'mkdn', 'mdwn', 'ron']})
lowlight.highlight('mdown', '<em>Emphasis</em>')
// ^ Works!
lowlight.registered(aliasOrlanguage)
Check whether an alias or name is registered.
Parameters
aliasOrlanguage(string) — [name][names] of a language or alias for one
Returns
Whether aliasOrName is registered (boolean).
Example
import {createLowlight} from 'lowlight'
import javascript from 'highlight.js/lib/languages/javascript'
const lowlight = createLowlight({javascript})
console.log(lowlight.registered('funkyscript')) // => `false`
lowlight.registerAlias({javascript: 'funkyscript'})
console.log(lowlight.registered('funkyscript')) // => `true`
AutoOptions
Configuration for highlightAuto (TypeScript type).
Fields
prefix(string, default:'hljs-') — class prefixsubset(Array<string>, default: all registered languages) — list of allowed languages
LanguageFn
Highlight.js grammar (TypeScript type).
Type
type {LanguageFn} from 'highlight.js'
Options
Configuration for highlight (TypeScript type).
Fields
prefix(string, default:'hljs-') — class prefix
Examples
Example: serializing hast as html
hast trees as returned by lowlight can be serialized with
[hast-util-to-html][hast-util-to-html]:
import {common, createLowlight} from 'lowlight'
import {toHtml} from 'hast-util-to-html'
const lowlight = createLowlight(common)
const tree = lowlight.highlight('js', '"use strict";')
console.log(toHtml(tree))
Yields:
<span class="hljs-meta">"use strict"</span>;
Example: turning hast into preact, react, etc
hast trees as returned by lowlight can be turned into nodes of any framework
that supports JSX, such as preact, react, solid, svelte, vue, and more, with
[hast-util-to-jsx-runtime][hast-util-to-jsx-runtime]:
import {toJsxRuntime} from 'hast-util-to-jsx-runtime'
// @ts-expect-error: react types don’t type these.
import {Fragment, jsx, jsxs} from 'react/jsx-runtime'
import {common, createLowlight} from 'lowlight'
const lowlight = createLowlight(common)
const tree = lowlight.highlight('js', '"use strict";')
console.log(toJsxRuntime(tree, {Fragment, jsx, jsxs}))
Yields:
{
$$typeof: Symbol(react.element),
type: Symbol(react.fragment),
key: null,
ref: null,
props: {children: [[Object], ';']},
_owner: null,
_store: {}
}
Types
This package is fully typed with [TypeScript][].
It exports the additional types
[AutoOptions][api-auto-options],
[LanguageFn][api-language-fn], and
[Options][api-options].
It also registers root.data with `@types/ha
