lowlight

Virtual syntax highlighting for virtual DOMs and non-HTML things

Usage no npm install needed!

<script type="module">
  import lowlight from 'https://cdn.skypack.dev/lowlight';
</script>

README

lowlight

Build Coverage Downloads Size

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

Contents

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 — 191 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.

  • 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
  • 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 — 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) — Microtik RouterOS script
  • rsl — RenderMan RSL
  • ruby (rb, gemspec, podspec, thor, irb) — Ruby
  • ruleslanguage — Oracle Rules Language
  • rust (rs) — Rust
  • sas — SAS
  • scala — Scala
  • scheme — 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) — 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 12.20+, 14.14+, and 16.0+. It also works in Deno and modern browsers.

Security

This package is safe.

Related

Projects

Contribute

Yes please! See How to Contribute to Open Source.

License

MIT © Titus Wormer