lowlight
Virtual syntax highlighting for virtual DOMs and non-HTML things
Last updated 4 years ago by wooorm .
MIT · Repository · Bugs · Original npm 
$ cnpm install lowlight
SYNC missed versions from official npm registry.

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

Projects

Contribute

Yes please! See How to Contribute to Open Source.

License

MIT © Titus Wormer

Current Tags

  • 2.6.1                                ...           latest (3 years ago)

9 Versions

  • 2.0.1                                ...           4 years ago
  • 2.6.1                                ...           3 years ago
  • 2.5.0                                ...           4 years ago
  • 1.9.2                                ...           7 years ago
  • 1.20.0                                ...           4 years ago
  • 1.17.0                                ...           5 years ago
  • 1.14.0                                ...           5 years ago
  • 1.12.1                                ...           6 years ago
  • 1.11.0                                ...           7 years ago
Maintainers (1)
wooorm
Downloads
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 0
Dependencies (3)
Dev Dependencies (18)
Dependents (0)
None

Copyright 2013 - present © cnpmjs.org