lowlight v3.1.0
lowlight
Virtual syntax highlighting for virtual DOMs and non-HTML things based on
highlight.js
.
Contents
- What is this?
- When should I use this?
- Install
- Use
- API
- Examples
- Types
- Data
- CSS
- Compatibility
- Security
- Related
- Projects
- Contribute
- License
What is this?
This package uses highlight.js
for syntax highlighting and
outputs objects (ASTs) instead of a string of HTML.
It can support 190+ programming languages.
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).
You can use the similar refractor
if you want to use Prism
grammars instead.
If you’re looking for a really good (but rather heavy) alternative, use
starry-night
.
Install
This package is ESM only. In Node.js (version 16+), install with npm:
npm install lowlight
In Deno with esm.sh
:
import {all, common, createLowlight} from 'https://esm.sh/lowlight@3'
In browsers with esm.sh
:
<script type="module">
import {all, common, createLowlight} from 'https://esm.sh/lowlight@3?bundle'
</script>
Use
import {common, createLowlight} from 'lowlight'
const lowlight = createLowlight(common)
const tree = 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}
}
API
This package exports the identifiers all
,
common
, and
createLowlight
.
There is no default export.
all
Map of all (±190) grammars (Record<string, LanguageFn>
).
common
Map of common (37) grammars (Record<string, LanguageFn>
).
createLowlight([grammars])
Create a lowlight
instance.
Parameters
grammars
(Record<string, LanguageFn>
, optional) — grammars to add
Returns
Lowlight (Lowlight
).
lowlight.highlight(language, value[, options])
Highlight value
(code) as language
(name).
Parameters
language
(string
) — programming language namevalue
(string
) — code to highlightoptions
(Options
, optional) — configuration
Returns
Tree (Root
); with the following data
fields: language
(string
), detected programming language name; relevance
(number
), how
sure lowlight is that the given code is in the language.
Example
import {common, createLowlight} from 'lowlight'
const lowlight = createLowlight(common)
console.log(lowlight.highlight('css', 'em { color: red }'))
Yields:
{type: 'root', children: [Array], data: {language: 'css', relevance: 3}}
lowlight.highlightAuto(value[, options])
Highlight value
(code) and guess its programming language.
Parameters
value
(string
) — code to highlightoptions
(AutoOptions
, optional) — configuration
Returns
Tree (Root
); with the following data
fields: language
(string
), detected programming language name; relevance
(number
), how
sure lowlight is that the given code is in the language.
Example
import {common, createLowlight} from 'lowlight'
const lowlight = createLowlight(common)
console.log(lowlight.highlightAuto('"hello, " + name + "!"'))
Yields:
{type: 'root', children: [Array], data: {language: 'arduino', relevance: 2}}
lowlight.listLanguages()
List registered languages.
Returns
Names of registered language (Array<string>
).
Example
import {createLowlight} from 'lowlight'
import markdown from 'highlight.js/lib/languages/markdown'
const lowlight = createLowlight()
console.log(lowlight.listLanguages()) // => []
lowlight.register({markdown})
console.log(lowlight.listLanguages()) // => ['markdown']
lowlight.register(grammars)
Register languages.
Signatures
register(name, grammar)
register(grammars)
Parameters
name
(string
) — programming language namegrammar
(LanguageFn
) — grammargrammars
(Record<string, LanguageFn>
, optional) — grammars
Returns
Nothing (undefined
).
Example
import {createLowlight} from 'lowlight'
import xml from 'highlight.js/lib/languages/xml'
const lowlight = 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}}
lowlight.registerAlias(aliases)
Register aliases.
Signatures
registerAlias(aliases)
registerAlias(name, alias)
Parameters
aliases
(Record<string, Array<string> | string>
) — map of programming language names to one or more aliasesname
(string
) — programming language namealias
(Array<string> | string
) — one or more aliases for the programming language
Returns
Nothing (undefined
).
Example
import {createLowlight} from 'lowlight'
import markdown from 'highlight.js/lib/languages/markdown'
const lowlight = createLowlight()
lowlight.register({markdown})
// 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 name is registered.
Parameters
aliasOrlanguage
(string
) — name of a language or alias for one
Returns
Whether aliasOrName
is registered (boolean
).
Example
import {createLowlight} from 'lowlight'
import javascript from 'highlight.js/lib/languages/javascript'
const lowlight = createLowlight({javascript})
console.log(lowlight.registered('funkyscript')) // => `false`
lowlight.registerAlias({javascript: 'funkyscript'})
console.log(lowlight.registered('funkyscript')) // => `true`
AutoOptions
Configuration for highlightAuto
(TypeScript type).
Fields
prefix
(string
, default:'hljs-'
) — class prefixsubset
(Array<string>
, default: all registered languages) — list of allowed languages
LanguageFn
Highlight.js grammar (TypeScript type).
Type
type {LanguageFn} from 'highlight.js'
Options
Configuration for highlight
(TypeScript type).
Fields
prefix
(string
, default:'hljs-'
) — class prefix
Examples
Example: serializing hast as html
hast trees as returned by lowlight can be serialized with
hast-util-to-html
:
import {common, createLowlight} from 'lowlight'
import {toHtml} from 'hast-util-to-html'
const lowlight = createLowlight(common)
const tree = lowlight.highlight('js', '"use strict";')
console.log(toHtml(tree))
Yields:
<span class="hljs-meta">"use strict"</span>;
Example: turning hast into preact, react, etc
hast trees as returned by lowlight can be turned into nodes of any framework
that supports JSX, such as preact, react, solid, svelte, vue, and more, with
hast-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'
const lowlight = createLowlight(common)
const tree = 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: {}
}
Types
This package is fully typed with TypeScript.
It exports the additional types
AutoOptions
,
LanguageFn
, and
Options
.
It also registers root.data
with @types/hast
.
If you’re working with the data fields, make sure to import this package
somewhere in your types, as that registers the new fields on the file.
/**
* @typedef {import('hast').Root} Root
*
* @typedef {import('lowlight')}
*/
import {VFile} from 'vfile'
/** @type {Root} */
const root = {type: 'root', children: []}
console.log(root.data?.language) //=> TS now knows that this is a `string?`.
Data
If you’re using createLowlight()
, no syntaxes are included yet.
You can import all
or common
and pass them, such as with
createLowlight(all)
.
Checked syntaxes are included in common
.
All syntaxes are included in all
.
You can also manually import syntaxes from highlight.js/lib/languages/xxx
,
where xxx
is the name, such as 'highlight.js/lib/languages/wasm'
.
1c
— 1C:Enterpriseabnf
— Augmented Backus-Naur Formaccesslog
— Apache Access Logactionscript
(as
) — ActionScriptada
— Adaangelscript
(asc
) — AngelScriptapache
(apacheconf
) — Apache configapplescript
(osascript
) — AppleScriptarcade
— ArcGIS Arcadearduino
(ino
) — Arduinoarmasm
(arm
) — ARM Assemblyasciidoc
(adoc
) — AsciiDocaspectj
— AspectJautohotkey
(ahk
) — AutoHotkeyautoit
— AutoItavrasm
— AVR Assemblyawk
— Awkaxapta
(x++
) — X++bash
(sh
) — Bashbasic
— BASICbnf
— Backus–Naur Formbrainfuck
(bf
) — Brainfuckc
(h
) — Ccal
— C/ALcapnproto
(capnp
) — Cap’n Protoceylon
— Ceylonclean
(icl
,dcl
) — Cleanclojure
(clj
,edn
) — Clojureclojure-repl
— Clojure REPLcmake
(cmake.in
) — CMakecoffeescript
(coffee
,cson
,iced
) — CoffeeScriptcoq
— Coqcos
(cls
) — Caché Object Scriptcpp
(cc
,c++
,h++
,hpp
,hh
,hxx
,cxx
) — C++crmsh
(crm
,pcmk
) — crmshcrystal
(cr
) — Crystalcsharp
(cs
,c#
) — C#csp
— CSPcss
— CSSd
— Ddart
— Dartdelphi
(dpr
,dfm
,pas
,pascal
) — Delphidiff
(patch
) — Diffdjango
(jinja
) — Djangodns
(bind
,zone
) — DNS Zonedockerfile
(docker
) — Dockerfiledos
(bat
,cmd
) — Batch file (DOS)dsconfig
— undefineddts
— Device Treedust
(dst
) — Dustebnf
— Extended Backus-Naur Formelixir
(ex
,exs
) — Elixirelm
— Elmerb
— ERBerlang
(erl
) — Erlangerlang-repl
— Erlang REPLexcel
(xlsx
,xls
) — Excel formulaefix
— FIXflix
— Flixfortran
(f90
,f95
) — Fortranfsharp
(fs
,f#
) — F#gams
(gms
) — GAMSgauss
(gss
) — GAUSSgcode
(nc
) — G-code (ISO 6983)gherkin
(feature
) — Gherkinglsl
— GLSLgml
— GMLgo
(golang
) — Gogolo
— Gologradle
— Gradlegraphql
(gql
) — GraphQLgroovy
— Groovyhaml
— HAMLhandlebars
(hbs
,html.hbs
,html.handlebars
,htmlbars
) — Handlebarshaskell
(hs
) — Haskellhaxe
(hx
) — Haxehsp
— HSPhttp
(https
) — HTTPhy
(hylang
) — Hyinform7
(i7
) — Inform 7ini
(toml
) — TOML, also INIirpf90
— IRPF90isbl
— ISBLjava
(jsp
) — Javajavascript
(js
,jsx
,mjs
,cjs
) — JavaScriptjboss-cli
(wildfly-cli
) — JBoss CLIjson
— JSONjulia
— Juliajulia-repl
(jldoctest
) — Julia REPLkotlin
(kt
,kts
) — Kotlinlasso
(ls
,lassoscript
) — Lassolatex
(tex
) — LaTeXldif
— LDIFleaf
— Leafless
— Lesslisp
— Lisplivecodeserver
— LiveCodelivescript
(ls
) — LiveScriptllvm
— LLVM IRlsl
— LSL (Linden Scripting Language)lua
— Luamakefile
(mk
,mak
,make
) — Makefilemarkdown
(md
,mkdown
,mkd
) — Markdownmathematica
(mma
,wl
) — Mathematicamatlab
— Matlabmaxima
— Maximamel
— MELmercury
(m
,moo
) — Mercurymipsasm
(mips
) — MIPS Assemblymizar
— Mizarmojolicious
— Mojoliciousmonkey
— Monkeymoonscript
(moon
) — MoonScriptn1ql
— N1QLnestedtext
(nt
) — Nested Textnginx
(nginxconf
) — Nginx confignim
— Nimnix
(nixos
) — Nixnode-repl
— Node REPLnsis
— NSISobjectivec
(mm
,objc
,obj-c
,obj-c++
,objective-c++
) — Objective-Cocaml
(ml
) — OCamlopenscad
(scad
) — OpenSCADoxygene
— Oxygeneparser3
— Parser3perl
(pl
,pm
) — Perlpf
(pf.conf
) — Packet Filter configpgsql
(postgres
,postgresql
) — PostgreSQLphp
— undefinedphp-template
— PHP templateplaintext
(text
,txt
) — Plain textpony
— Ponypowershell
(pwsh
,ps
,ps1
) — PowerShellprocessing
(pde
) — Processingprofile
— Python profilerprolog
— Prologproperties
— .propertiesprotobuf
(proto
) — Protocol Bufferspuppet
(pp
) — Puppetpurebasic
(pb
,pbi
) — PureBASICpython
(py
,gyp
,ipython
) — Pythonpython-repl
(pycon
) — undefinedq
(k
,kdb
) — Qqml
(qt
) — QMLr
— Rreasonml
(re
) — ReasonMLrib
— RenderMan RIBroboconf
(graph
,instances
) — Roboconfrouteros
(mikrotik
) — MikroTik RouterOS scriptrsl
— RenderMan RSLruby
(rb
,gemspec
,podspec
,thor
,irb
) — Rubyruleslanguage
— Oracle Rules Languagerust
(rs
) — Rustsas
— SASscala
— Scalascheme
(scm
) — Schemescilab
(sci
) — Scilabscss
— SCSSshell
(console
,shellsession
) — Shell Sessionsmali
— Smalismalltalk
(st
) — Smalltalksml
(ml
) — SML (Standard ML)sqf
— SQFsql
— SQLstan
(stanfuncs
) — Stanstata
(do
,ado
) — Statastep21
(p21
,step
,stp
) — STEP Part 21stylus
(styl
) — Stylussubunit
— SubUnitswift
— Swifttaggerscript
— Tagger Scripttap
— Test Anything Protocoltcl
(tk
) — Tclthrift
— Thrifttp
— TPtwig
(craftcms
) — Twigtypescript
(ts
,tsx
,mts
,cts
) — TypeScriptvala
— Valavbnet
(vb
) — Visual Basic .NETvbscript
(vbs
) — VBScriptvbscript-html
— VBScript in HTMLverilog
(v
,sv
,svh
) — Verilogvhdl
— VHDLvim
— Vim Scriptwasm
— WebAssemblywren
— Wrenx86asm
— Intel x86 Assemblyxl
(tao
) — XLxml
(html
,xhtml
,rss
,atom
,xjb
,xsd
,xsl
,plist
,wsf
,svg
) — HTML, XMLxquery
(xpath
,xq
,xqm
) — XQueryyaml
(yml
) — YAMLzephir
(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.8.0/styles/github-dark.min.css">
Compatibility
This package is compatible with maintained versions of Node.js.
When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
lowlight@^3
, compatible with Node.js 16.
Security
This package is safe.
Related
refractor
— the same as lowlight but with Prismstarry-night
— similar but like GitHub and really good
Projects
emphasize
— syntax highlighting in ANSI (for the terminal)react-lowlight
— syntax highlighter for Reactreact-syntax-highlighter
— React component for syntax highlightingrehype-highlight
— rehype plugin to highlight code blocksjstransformer-lowlight
— syntax highlighting for JSTransformers and Pug
Contribute
Yes please! See How to Contribute to Open Source.
License
7 months ago
8 months ago
12 months ago
1 year ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
5 years ago
5 years ago
5 years ago
6 years ago
6 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago