Skip to content
main
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

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