lowlight

Virtual syntax highlighting for virtual DOMs and non-HTML things.

What is this?

This package wraps highlight.js to output objects (ASTs) instead of a string of HTML.

highlight.js, through lowlight, supports 190+ programming languages. Supporting all of them requires a lot of code. That’s why there are three entry points for lowlight:

lib/core.js — 0 languages
lib/common.js (default) — 35 languages
lib/all.js — 192 languages

Bundled, minified, and gzipped, those are roughly 9.7 kB, 47 kB, and 290 kB.

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).

A different package, refractor, does the same as lowlight but uses Prism instead.

Install

This package is ESM only. In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:

npm install lowlight

In Deno with Skypack:

import {lowlight} from 'https://cdn.skypack.dev/lowlight@2?dts'

In browsers with Skypack:

<script type="module">
  import {lowlight} from 'https://cdn.skypack.dev/lowlight@2?min'
</script>

Use

import {lowlight} from 'lowlight'

const tree = lowlight.highlight('js', '"use strict";')

console.dir(tree, {depth: null})

Yields:

{
  type: 'root',
  data: {language: 'js', relevance: 10},
  children: [
    {
      type: 'element',
      tagName: 'span',
      properties: {className: ['hljs-meta']},
      children: [{type: 'text', value: '"use strict"'}]
    },
    {type: 'text', value: ';'}
  ]
}

API

This package exports the following identifier: lowlight. There is no default export.

`lowlight.highlight(language, value[, options])`

Highlight value (code) as language (name).

Parameters

language (string) — programming language name
value (string) — code to highlight
options.prefix (string?, default: 'hljs-') — class prefix

Returns

A hast Root node with the following data fields:

relevance (number) — how sure lowlight is that the given code is in the language
language (string) — detected programming language name

Example

import {lowlight} from 'lowlight'

console.log(lowlight.highlight('css', 'em { color: red }'))

Yields:

{type: 'root', data: {language: 'css', relevance: 3}, children: [Array]}

`lowlight.highlightAuto(value[, options])`

Highlight value (code) and guess its programming language.

Parameters

value (string) — code to highlight
options.prefix (string?, default: 'hljs-') — class prefix
options.subset (Array<string>, default: all registered language names) — list of allowed languages

Returns

The same result as lowlight.highlight is returned.

Example

import {lowlight} from 'lowlight'

console.log(lowlight.highlightAuto('"hello, " + name + "!"'))

Yields:

{type: 'root', data: {language: 'applescript', relevance: 3}, children: [Array]}

`lowlight.registerLanguage(language, syntax)`

Register a language.

Parameters

language (string) — programming language name
syntax (HighlightSyntax) — highlight.js syntax

Note

highlight.js operates as a singleton: once you register a language in one place, it’ll be available everywhere.

Example

import {lowlight} from 'lowlight/lib/core.js'
import xml from 'highlight.js/lib/languages/xml.js'

lowlight.registerLanguage('xml', xml)

console.log(lowlight.highlight('html', '<em>Emphasis</em>'))

Yields:

{type: 'root', data: {language: 'html', relevance: 2}, children: [Array]}

`lowlight.registerAlias(language, alias)`

Register aliases for already registered languages.

Signatures

registerAlias(language, alias|list)
registerAlias(aliases)

Parameters

language (string) — programming language name
alias (string) — new aliases for the programming language
list (Array<string>) — list of aliases
aliases (Record<language, alias|list>) — map of languages to aliases or lists

Example

import {lowlight} from 'lowlight/lib/core.js'
import md from 'highlight.js/lib/languages/markdown.js'

lowlight.registerLanguage('markdown', md)

// 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 language is registered.

Parameters

aliasOrlanguage (string) — name of a registered language or alias

Returns

Whether aliasOrlanguage is registered (boolean).

Example

import {lowlight} from 'lowlight/lib/core.js'
import javascript from 'highlight.js/lib/languages/javascript.js'

lowlight.registerLanguage('javascript', javascript)

lowlight.registered('js') // return false

lowlight.registerAlias('javascript', 'js')
lowlight.registered('js') // return true

`lowlight.listLanguages()`

List registered languages.

Returns

Names of registered language (Array<string>).

Example

import {lowlight} from 'lowlight/lib/core.js'
import md from 'highlight.js/lib/languages/markdown.js'

console.log(lowlight.listLanguages()) // => []

lowlight.registerLanguage('markdown', md)

console.log(lowlight.listLanguages()) // => ['markdown']

Examples

Example: serializing hast as html

hast trees as returned by lowlight can be serialized with hast-util-to-html:

import {lowlight} from 'lowlight'
import {toHtml} from 'hast-util-to-html'

const tree = lowlight.highlight('js', '"use strict";')

console.log(toHtml(tree))

Yields:

<span class="hljs-meta">"use strict"</span>;

Example: turning hast into react nodes

hast trees as returned by lowlight can be turned into React (or Preact) with hast-to-hyperscript:

import {lowlight} from 'lowlight'
import {toH} from 'hast-to-hyperscript'
import React from 'react'

const tree = lowlight.highlight('js', '"use strict";')
const react = toH(React.createElement, tree)

console.log(react)

Yields:

{
  '$$typeof': Symbol(react.element),
  type: 'div',
  key: 'h-1',
  ref: null,
  props: { children: [ [Object], ';' ] },
  _owner: null,
  _store: {}
}

Types

This package is fully typed with TypeScript. It exports additional Root, Options, and AutoOptions types that models their respective interfaces.

Data

If you’re using lowlight/lib/core.js, no syntaxes are included. Checked syntaxes are included if you import lowlight (or explicitly lowlight/lib/common.js). Unchecked syntaxes are available through lowlight/lib/all.js. You can import core or common and manually add more languages as you please.

highlight.js operates as a singleton: once you register a language in one place, it’ll be available everywhere.

CSS

lowlight does not inject CSS for the syntax highlighted code (because well, lowlight doesn’t have to be turned into HTML and might not run in a browser!). If you are in a browser, you can use any highlight.js theme. For example, to get GitHub Dark from cdnjs:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.2.0/styles/github-dark.min.css">

Compatibility

This package is at least compatible with all maintained versions of Node.js. As of now, that is Node.js 12.20+, 14.14+, and 16.0+. It also works in Deno and modern browsers.

Security

This package is safe.

Projects

emphasize — syntax highlighting in ANSI (for the terminal)
react-lowlight — syntax highlighter for React
react-syntax-highlighter — React component for syntax highlighting
rehype-highlight — rehype plugin to highlight code blocks
jstransformer-lowlight — syntax highlighting for JSTransformers and Pug

Contribute

Yes please! See How to Contribute to Open Source.

Name		Name	Last commit message	Last commit date
Latest commit History 188 Commits
.github/workflows		.github/workflows
lib		lib
script		script
test		test
.editorconfig		.editorconfig
.gitignore		.gitignore
.npmrc		.npmrc
.prettierignore		.prettierignore
changelog.md		changelog.md
funding.yml		funding.yml
index.js		index.js
license		license
package.json		package.json
readme.md		readme.md
tsconfig.json		tsconfig.json

Uh oh!

License

wooorm/lowlight

Folders and files

Latest commit

History

Repository files navigation

lowlight

Contents

What is this?

When should I use this?

Install

Use

API

lowlight.highlight(language, value[, options])

Parameters

Returns

Example

lowlight.highlightAuto(value[, options])

Parameters

Returns

Example

lowlight.registerLanguage(language, syntax)

Parameters

Note

Example

lowlight.registerAlias(language, alias)

Signatures

Parameters

Example

lowlight.registered(aliasOrlanguage)

Parameters

Returns

Example

lowlight.listLanguages()

Returns

Example

Examples

Example: serializing hast as html

Example: turning hast into react nodes

Types

Data

CSS

Compatibility

Security

Related

Projects

Contribute

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 44

Sponsor this project

Uh oh!

Used by 311k

Contributors 12

Uh oh!

Languages

`lowlight.highlight(language, value[, options])`

`lowlight.highlightAuto(value[, options])`

`lowlight.registerLanguage(language, syntax)`

`lowlight.registerAlias(language, alias)`

`lowlight.registered(aliasOrlanguage)`

`lowlight.listLanguages()`