Repository files navigation

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

• What is this?
• When should I use this?
• Install
• Use
• API
  • all
  • common
  • createLowlight([grammars])
  • lowlight.highlight(language, value[, options])
  • lowlight.highlightAuto(value[, options])
  • lowlight.listLanguages()
  • lowlight.register(grammars)
  • lowlight.registerAlias(aliases)
  • lowlight.registered(aliasOrlanguage)
  • AutoOptions
  • LanguageFn
  • Options
• Examples
  • Example: serializing hast as html
  • Example: turning hast into preact, react, etc
• Types
• Data
• CSS
• Compatibility
• Security
• Related
• Projects
• Contribute
• License

This package useshighlight.js for syntax highlighting andoutputs objects (ASTs) instead of a string of HTML.It can support 190+ programming languages.

This package is useful when you want to perform syntax highlighting in a placewhere 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 byrendering to ANSI sequences, when you’re using virtual DOM frameworks (such asReact or Preact) so that diffing can be performant, or when you’re working withASTs (rehype).

You can use the similarrefractor if you want to usePrismgrammars instead.If you’re looking for areally good (but rather heavy) alternative, usestarry-night.

This package isESM only.In Node.js (version 16+), install withnpm:

npm install lowlight

In Deno withesm.sh:

import{all,common,createLowlight}from'https://esm.sh/lowlight@3'

In browsers withesm.sh:

<scripttype="module">import{all,common,createLowlight}from'https://esm.sh/lowlight@3?bundle'</script>

import{common,createLowlight}from'lowlight'constlowlight=createLowlight(common)consttree=lowlight.highlight('js','"use strict";')console.dir(tree,{depth:undefined})

Yields:

{type:'root',children:[{type:'element',tagName:'span',properties:{className:['hljs-meta']},children:[{type:'text',value:'"use strict"'}]},{type:'text',value:';'}],data:{language:'js',relevance:10}}

This package exports the identifiersall,common, andcreateLowlight.There is no default export.

Map of all (±190) grammars (Record<string, LanguageFn>).

Map of common (37) grammars (Record<string, LanguageFn>).

Create alowlight instance.

• grammars (Record<string, LanguageFn>, optional)— grammars to add

Lowlight (Lowlight).

Highlightvalue (code) aslanguage (name).

• language (string)— programming languagename
• value (string)— code to highlight
• options (Options, optional)— configuration

Tree (Root); with the followingdata fields:language(string), detected programming language name;relevance (number), howsure lowlight is that the given code is in the language.

import{common,createLowlight}from'lowlight'constlowlight=createLowlight(common)console.log(lowlight.highlight('css','em { color: red }'))

Yields:

{type:'root',children:[Array],data:{language:'css',relevance:3}}

Highlightvalue (code) and guess its programming language.

• value (string)— code to highlight
• options (AutoOptions, optional)— configuration

Tree (Root); with the followingdata fields:language(string), detected programming language name;relevance (number), howsure lowlight is that the given code is in the language.

import{common,createLowlight}from'lowlight'constlowlight=createLowlight(common)console.log(lowlight.highlightAuto('"hello, " + name + "!"'))

Yields:

{type:'root',children:[Array],data:{language:'arduino',relevance:2}}

List registered languages.

Names of registered language (Array<string>).

import{createLowlight}from'lowlight'importmarkdownfrom'highlight.js/lib/languages/markdown'constlowlight=createLowlight()console.log(lowlight.listLanguages())// => []lowlight.register({markdown})console.log(lowlight.listLanguages())// => ['markdown']

Register languages.

• register(name, grammar)
• register(grammars)

• name (string)— programming languagename
• grammar (LanguageFn)— grammar
• grammars (Record<string, LanguageFn>, optional)— grammars

Nothing (undefined).

import{createLowlight}from'lowlight'importxmlfrom'highlight.js/lib/languages/xml'constlowlight=createLowlight()lowlight.register({xml})// Note: `html` is an alias for `xml`.console.log(lowlight.highlight('html','<em>Emphasis</em>'))

Yields:

{type:'root',children:[Array],data:{language:'html',relevance:2}}

Register aliases.

• registerAlias(aliases)
• registerAlias(name, alias)

• aliases (Record<string, Array<string> | string>)— map of programming languagenames to one or more aliases
• name (string)— programming languagename
• alias (Array<string> | string)— one or more aliases for the programming language

Nothing (undefined).

import{createLowlight}from'lowlight'importmarkdownfrom'highlight.js/lib/languages/markdown'constlowlight=createLowlight()lowlight.register({markdown})// lowlight.highlight('mdown', '<em>Emphasis</em>')// ^ would throw: Error: Unknown language: `mdown` is not registeredlowlight.registerAlias({markdown:['mdown','mkdn','mdwn','ron']})lowlight.highlight('mdown','<em>Emphasis</em>')// ^ Works!

Check whether an alias or name is registered.

• aliasOrlanguage (string)—name of a language or alias for one

WhetheraliasOrName is registered (boolean).

import{createLowlight}from'lowlight'importjavascriptfrom'highlight.js/lib/languages/javascript'constlowlight=createLowlight({javascript})console.log(lowlight.registered('funkyscript'))// => `false`lowlight.registerAlias({javascript:'funkyscript'})console.log(lowlight.registered('funkyscript'))// => `true`

Configuration forhighlightAuto (TypeScript type).

• prefix (string, default:'hljs-')— class prefix
• subset (Array<string>, default: all registered languages)— list of allowed languages

Highlight.js grammar (TypeScript type).

type{LanguageFn}from'highlight.js'

Configuration forhighlight (TypeScript type).

• prefix (string, default:'hljs-')— class prefix

hast trees as returned by lowlight can be serialized withhast-util-to-html:

import{common,createLowlight}from'lowlight'import{toHtml}from'hast-util-to-html'constlowlight=createLowlight(common)consttree=lowlight.highlight('js','"use strict";')console.log(toHtml(tree))

Yields:

<spanclass="hljs-meta">"use strict"</span>;

hast trees as returned by lowlight can be turned into nodes of any frameworkthat supports JSX, such as preact, react, solid, svelte, vue, and more, withhast-util-to-jsx-runtime:

import{toJsxRuntime}from'hast-util-to-jsx-runtime'//@ts-expect-error: react types don’t type these.import{Fragment,jsx,jsxs}from'react/jsx-runtime'import{common,createLowlight}from'lowlight'constlowlight=createLowlight(common)consttree=lowlight.highlight('js','"use strict";')console.log(toJsxRuntime(tree,{Fragment, jsx, jsxs}))

Yields:

{$$typeof:Symbol(react.element),type:Symbol(react.fragment),key:null,ref:null,props:{children:[[Object],';']},_owner:null,_store:{}}

This package is fully typed withTypeScript.It exports the additional typesAutoOptions,LanguageFn, andOptions.

It also registersroot.data with@types/hast.If you’re working with the data fields, make sure to import this packagesomewhere in your types, as that registers the new fields on the file.

/** *@import {Root} from 'hast' *@import {} from 'lowlight' */import{VFile}from'vfile'/**@type {Root} */constroot={type:'root',children:[]}console.log(root.data?.language)//=> TS now knows that this is a `string?`.

If you’re usingcreateLowlight(), no syntaxes are included yet.You can importall orcommon and pass them, such as withcreateLowlight(all).Checked syntaxes are included incommon.All syntaxes are included inall.

You can also manually import syntaxes fromhighlight.js/lib/languages/xxx,wherexxx is the name, such as'highlight.js/lib/languages/wasm'.

• 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,zsh) — 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 (jsonc) — 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 (pluto) — 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,xqm) — XQuery
• yaml (yml) — YAML
• zephir (zep) — Zephir

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 anyhighlight.js theme.For example, to get GitHub Dark from cdnjs:

<linkrel="stylesheet"href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.0/styles/github-dark.min.css">

This package is compatible with maintained versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions ofNode.This means we try to keep the current release line,lowlight@^3, compatible with Node.js 16.

This package is safe.

• refractor— the same as lowlight but withPrism
• starry-night— similar but like GitHub and really good

• emphasize— syntax highlighting in ANSI (for the terminal)
• react-lowlight— syntax highlighter forReact
• react-syntax-highlighter—React component for syntax highlighting
• rehype-highlight—rehype plugin to highlight codeblocks
• jstransformer-lowlight— syntax highlighting forJSTransformersandPug

Yes please!SeeHow to Contribute to Open Source.

MIT ©Titus Wormer