lowlight

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

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • lowlight.highlight(language, value[, options])
  • lowlight.highlightAuto(value[, options])
  • lowlight.registerLanguage(language, syntax)
  • lowlight.registerAlias(language, alias)
  • lowlight.registered(aliasOrlanguage)
  • lowlight.listLanguages()
• Examples
  • Example: serializing hast as html
  • Example: turning hast into react nodes
• Types
• Data
• CSS
• Compatibility
• Security
• Related
• Projects
• Contribute
• License

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) — 37 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. If you’re looking for a really good (but rather heavy) highlighter, try starry-night.

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 esm.sh:

import {lowlight} from 'https://esm.sh/lowlight@2'

In browsers with esm.sh:

<script type="module">
  import {lowlight} from 'https://esm.sh/lowlight@2?bundle'
</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.

• [ ] 1c — 1C:Enterprise
• [ ] abnf — Augmented Backus-Naur Form
• [ ] accesslog — Apache Access Log
• [ ] actionscript (as) — ActionScript
• [ ] ada — Ada
• [ ] angelscript (asc) — AngelScript
• [ ] apache (apacheconf) — Apache config
• [ ] applescript (osascript) — AppleScript
• [ ] arcade — ArcGIS Arcade
• [x] arduino (ino) — Arduino
• [ ] armasm (arm) — ARM Assembly
• [ ] asciidoc (adoc) — AsciiDoc
• [ ] aspectj — AspectJ
• [ ] autohotkey (ahk) — AutoHotkey
• [ ] autoit — AutoIt
• [ ] avrasm — AVR Assembly
• [ ] awk — Awk
• [ ] axapta (x++) — X++
• [x] bash (sh) — Bash
• [ ] basic — BASIC
• [ ] bnf — Backus–Naur Form
• [ ] brainfuck (bf) — Brainfuck
• [x] c (h) — C
• [ ] cal — C/AL
• [ ] capnproto (capnp) — Cap’n Proto
• [ ] ceylon — Ceylon
• [ ] clean (icl, dcl) — Clean
• [ ] clojure (clj, edn) — Clojure
• [ ] clojure-repl — Clojure REPL
• [ ] cmake (cmake.in) — CMake
• [ ] coffeescript (coffee, cson, iced) — CoffeeScript
• [ ] coq — Coq
• [ ] cos (cls) — Caché Object Script
• [x] cpp (cc, c++, h++, hpp, hh, hxx, cxx) — C++
• [ ] crmsh (crm, pcmk) — crmsh
• [ ] crystal (cr) — Crystal
• [x] csharp (cs, c#) — C#
• [ ] csp — CSP
• [x] css — CSS
• [ ] d — D
• [ ] dart — Dart
• [ ] delphi (dpr, dfm, pas, pascal) — Delphi
• [x] diff (patch) — Diff
• [ ] django (jinja) — Django
• [ ] dns (bind, zone) — DNS Zone
• [ ] dockerfile (docker) — Dockerfile
• [ ] dos (bat, cmd) — Batch file (DOS)
• [ ] dsconfig — undefined
• [ ] dts — Device Tree
• [ ] dust (dst) — Dust
• [ ] ebnf — Extended Backus-Naur Form
• [ ] elixir (ex, exs) — Elixir
• [ ] elm — Elm
• [ ] erb — ERB
• [ ] erlang (erl) — Erlang
• [ ] erlang-repl — Erlang REPL
• [ ] excel (xlsx, xls) — Excel formulae
• [ ] fix — FIX
• [ ] flix — Flix
• [ ] fortran (f90, f95) — Fortran
• [ ] fsharp (fs, f#) — F#
• [ ] gams (gms) — GAMS
• [ ] gauss (gss) — GAUSS
• [ ] gcode (nc) — G-code (ISO 6983)
• [ ] gherkin (feature) — Gherkin
• [ ] glsl — GLSL
• [ ] gml — GML
• [x] go (golang) — Go
• [ ] golo — Golo
• [ ] gradle — Gradle
• [x] graphql (gql) — GraphQL
• [ ] groovy — Groovy
• [ ] haml — HAML
• [ ] handlebars (hbs, html.hbs, html.handlebars, htmlbars) — Handlebars
• [ ] haskell (hs) — Haskell
• [ ] haxe (hx) — Haxe
• [ ] hsp — HSP
• [ ] http (https) — HTTP
• [ ] hy (hylang) — Hy
• [ ] inform7 (i7) — Inform 7
• [x] ini (toml) — TOML, also INI
• [ ] irpf90 — IRPF90
• [ ] isbl — ISBL
• [x] java (jsp) — Java
• [x] javascript (js, jsx, mjs, cjs) — Javascript
• [ ] jboss-cli (wildfly-cli) — JBoss CLI
• [x] json — JSON
• [ ] julia — Julia
• [ ] julia-repl (jldoctest) — Julia REPL
• [x] kotlin (kt, kts) — Kotlin
• [ ] lasso (ls, lassoscript) — Lasso
• [ ] latex (tex) — LaTeX
• [ ] ldif — LDIF
• [ ] leaf — Leaf
• [x] less — Less
• [ ] lisp — Lisp
• [ ] livecodeserver — LiveCode
• [ ] livescript (ls) — LiveScript
• [ ] llvm — LLVM IR
• [ ] lsl — LSL (Linden Scripting Language)
• [x] lua — Lua
• [x] makefile (mk, mak, make) — Makefile
• [x] markdown (md, mkdown, mkd) — Markdown
• [ ] mathematica (mma, wl) — Mathematica
• [ ] matlab — Matlab
• [ ] maxima — Maxima
• [ ] mel — MEL
• [ ] mercury (m, moo) — Mercury
• [ ] mipsasm (mips) — MIPS Assembly
• [ ] mizar — Mizar
• [ ] mojolicious — Mojolicious
• [ ] monkey — Monkey
• [ ] moonscript (moon) — MoonScript
• [ ] n1ql — N1QL
• [ ] nestedtext (nt) — Nested Text
• [ ] nginx (nginxconf) — Nginx config
• [ ] nim — Nim
• [ ] nix (nixos) — Nix
• [ ] node-repl — Node REPL
• [ ] nsis — NSIS
• [x] objectivec (mm, objc, obj-c, obj-c++, objective-c++) — Objective-C
• [ ] ocaml (ml) — OCaml
• [ ] openscad (scad) — OpenSCAD
• [ ] oxygene — Oxygene
• [ ] parser3 — Parser3
• [x] perl (pl, pm) — Perl
• [ ] pf (pf.conf) — Packet Filter config
• [ ] pgsql (postgres, postgresql) — PostgreSQL
• [x] php — undefined
• [x] php-template — PHP template
• [x] plaintext (text, txt) — Plain text
• [ ] pony — Pony
• [ ] powershell (pwsh, ps, ps1) — PowerShell
• [ ] processing (pde) — Processing
• [ ] profile — Python profiler
• [ ] prolog — Prolog
• [ ] properties — .properties
• [ ] protobuf — Protocol Buffers
• [ ] puppet (pp) — Puppet
• [ ] purebasic (pb, pbi) — PureBASIC
• [x] python (py, gyp, ipython) — Python
• [x] python-repl (pycon) — undefined
• [ ] q (k, kdb) — Q
• [ ] qml (qt) — QML
• [x] r — R
• [ ] reasonml (re) — ReasonML
• [ ] rib — RenderMan RIB
• [ ] roboconf (graph, instances) — Roboconf
• [ ] routeros (mikrotik) — Microtik RouterOS script
• [ ] rsl — RenderMan RSL
• [x] ruby (rb, gemspec, podspec, thor, irb) — Ruby
• [ ] ruleslanguage — Oracle Rules Language
• [x] rust (rs) — Rust
• [ ] sas — SAS
• [ ] scala — Scala
• [ ] scheme — Scheme
• [ ] scilab (sci) — Scilab
• [x] scss — SCSS
• [x] shell (console, shellsession) — Shell Session
• [ ] smali — Smali
• [ ] smalltalk (st) — Smalltalk
• [ ] sml (ml) — SML (Standard ML)
• [ ] sqf — SQF
• [x] sql — SQL
• [ ] stan (stanfuncs) — Stan
• [ ] stata (do, ado) — Stata
• [ ] step21 (p21, step, stp) — STEP Part 21
• [ ] stylus (styl) — Stylus
• [ ] subunit — SubUnit
• [x] swift — Swift
• [ ] taggerscript — Tagger Script
• [ ] tap — Test Anything Protocol
• [ ] tcl (tk) — Tcl
• [ ] thrift — Thrift
• [ ] tp — TP
• [ ] twig (craftcms) — Twig
• [x] typescript (ts, tsx) — TypeScript
• [ ] vala — Vala
• [x] vbnet (vb) — Visual Basic .NET
• [ ] vbscript (vbs) — VBScript
• [ ] vbscript-html — VBScript in HTML
• [ ] verilog (v, sv, svh) — Verilog
• [ ] vhdl — VHDL
• [ ] vim — Vim Script
• [x] wasm — WebAssembly
• [ ] wren — Wren
• [ ] x86asm — Intel x86 Assembly
• [ ] xl (tao) — XL
• [x] xml (html, xhtml, rss, atom, xjb, xsd, xsl, plist, wsf, svg) — HTML, XML
• [ ] xquery (xpath, xq) — XQuery
• [x] yaml (yml) — YAML
• [ ] zephir (zep) — Zephir

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.

Related

• refractor — the same as lowlight but with Prism
• starry-night — similar but like GitHub and really good

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.

License

MIT © Titus Wormer