lowlight

What is lowlight?

The lowlight npm package is a library for syntax highlighting of code using languages supported by highlight.js. It is primarily used to parse and transform code into a syntax-highlighted format without a browser, making it suitable for server-side applications or pre-processing of static pages.

What are lowlight's main functionalities?

Syntax Highlighting

This feature allows you to highlight syntax of various programming languages. The code sample demonstrates highlighting a simple JavaScript code snippet.

const lowlight = require('lowlight');
const highlightedCode = lowlight.highlight('javascript', 'const x = 123;').value;
console.log(highlightedCode);

Registering Languages

This feature enables the addition of new languages to lowlight's highlighting capabilities by registering them through highlight.js. The code sample shows how to register and highlight Python code.

const lowlight = require('lowlight');
lowlight.registerLanguage('python', require('highlight.js/lib/languages/python'));
const highlightedPython = lowlight.highlight('python', 'def foo(): return 123').value;
console.log(highlightedPython);

Auto-Detection of Language

This feature automatically detects the programming language of a given code snippet and applies appropriate syntax highlighting. The code sample demonstrates auto-detection for a JavaScript snippet.

const lowlight = require('lowlight');
const result = lowlight.highlightAuto('const x = 123;');
console.log(result.language); // 'javascript'
console.log(result.value);

Other packages similar to lowlight

highlight.js

highlight.js is a widely used library for syntax highlighting. It supports numerous languages and is often used directly in web browsers. Compared to lowlight, highlight.js is more versatile for client-side applications but both can be used server-side.

prismjs

Prism is another popular syntax highlighting library that works both in the browser and on the server. It is known for its lightweight core and extensible plugins. Unlike lowlight, PrismJS focuses more on client-side performance and extensibility.

shiki

Shiki is a syntax highlighter powered by the same language grammars as Visual Studio Code. It provides accurate and visually appealing highlights. Shiki is similar to lowlight in that it can be used server-side, but it offers a richer set of themes and a different integration approach.

README

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

• 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 — 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

• wooorm/refractor — the same as lowlight but with Prism

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