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 14.14+, 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 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 the additional types Root, Options, and AutoOptions.

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
• 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++
• bash (sh) — Bash
• basic — BASIC
• bnf — Backus–Naur Form
• brainfuck (bf) — Brainfuck
• 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
• cpp (cc, c++, h++, hpp, hh, hxx, cxx) — C++
• crmsh (crm, pcmk) — crmsh
• crystal (cr) — Crystal
• csharp (cs, c#) — C#
• csp — CSP
• css — CSS
• d — D
• dart — Dart
• delphi (dpr, dfm, pas, pascal) — Delphi
• 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
• go (golang) — Go
• golo — Golo
• gradle — Gradle
• 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
• ini (toml) — TOML, also INI
• irpf90 — IRPF90
• isbl — ISBL
• java (jsp) — Java
• javascript (js, jsx, mjs, cjs) — JavaScript
• jboss-cli (wildfly-cli) — JBoss CLI
• json — JSON
• julia — Julia
• julia-repl (jldoctest) — Julia REPL
• kotlin (kt, kts) — Kotlin
• lasso (ls, lassoscript) — Lasso
• latex (tex) — LaTeX
• ldif — LDIF
• leaf — Leaf
• less — Less
• lisp — Lisp
• livecodeserver — LiveCode
• livescript (ls) — LiveScript
• llvm — LLVM IR
• lsl — LSL (Linden Scripting Language)
• lua — Lua
• makefile (mk, mak, make) — Makefile
• 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
• objectivec (mm, objc, obj-c, obj-c++, objective-c++) — Objective-C
• ocaml (ml) — OCaml
• openscad (scad) — OpenSCAD
• oxygene — Oxygene
• parser3 — Parser3
• perl (pl, pm) — Perl
• pf (pf.conf) — Packet Filter config
• pgsql (postgres, postgresql) — PostgreSQL
• php — undefined
• php-template — PHP template
• plaintext (text, txt) — Plain text
• pony — Pony
• powershell (pwsh, ps, ps1) — PowerShell
• processing (pde) — Processing
• profile — Python profiler
• prolog — Prolog
• properties — .properties
• protobuf (proto) — Protocol Buffers
• puppet (pp) — Puppet
• purebasic (pb, pbi) — PureBASIC
• python (py, gyp, ipython) — Python
• python-repl (pycon) — undefined
• q (k, kdb) — Q
• qml (qt) — QML
• r — R
• reasonml (re) — ReasonML
• rib — RenderMan RIB
• roboconf (graph, instances) — Roboconf
• routeros (mikrotik) — MikroTik RouterOS script
• rsl — RenderMan RSL
• ruby (rb, gemspec, podspec, thor, irb) — Ruby
• ruleslanguage — Oracle Rules Language
• rust (rs) — Rust
• sas — SAS
• scala — Scala
• scheme (scm) — Scheme
• scilab (sci) — Scilab
• scss — SCSS
• shell (console, shellsession) — Shell Session
• smali — Smali
• smalltalk (st) — Smalltalk
• sml (ml) — SML (Standard ML)
• sqf — SQF
• sql — SQL
• stan (stanfuncs) — Stan
• stata (do, ado) — Stata
• step21 (p21, step, stp) — STEP Part 21
• stylus (styl) — Stylus
• subunit — SubUnit
• swift — Swift
• taggerscript — Tagger Script
• tap — Test Anything Protocol
• tcl (tk) — Tcl
• thrift — Thrift
• tp — TP
• twig (craftcms) — Twig
• typescript (ts, tsx, mts, cts) — TypeScript
• vala — Vala
• vbnet (vb) — Visual Basic .NET
• vbscript (vbs) — VBScript
• vbscript-html — VBScript in HTML
• verilog (v, sv, svh) — Verilog
• vhdl — VHDL
• vim — Vim Script
• wasm — WebAssembly
• wren — Wren
• x86asm — Intel x86 Assembly
• xl (tao) — XL
• xml (html, xhtml, rss, atom, xjb, xsd, xsl, plist, wsf, svg) — HTML, XML
• xquery (xpath, xq) — XQuery
• 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 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