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, with language auto-detection. Perfect for React, VDOM, and others.

Lowlight is built to work with all syntaxes supported by highlight.js, that’s 185 languages (and all 89 themes).

Want to use Prism instead? Try refractor!

Contents

• Install
• Use
• API
  • low.highlight(language, value[, options])
  • low.highlightAuto(value[, options])
  • Result
  • low.registerLanguage(name, syntax)
  • low.registerAlias(name[, alias])
  • low.listLanguages()
• Browser
• Related
• Projects
• License

Install

npm:

npm install lowlight

Usage in the browser »

Use

Highlight:

var low = require('lowlight')
var tree = low.highlight('js', '"use strict";').value

console.log(tree)

Yields:

[ { type: 'element',
    tagName: 'span',
    properties: { className: [ 'hljs-meta' ] },
    children: [ { type: 'text', value: '"use strict"' } ] },
  { type: 'text', value: ';' } ]

Or, serialized with rehype:

var rehype = require('rehype')
var html = rehype()
  .stringify({type: 'root', children: tree})
  .toString()

console.log(html)

Yields:

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

Tip: Use hast-to-hyperscript to transform to other virtual DOMs, or DIY.

API

low.highlight(language, value[, options])

Parse value (string) according to the language grammar.

options

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

Returns

Result.

Example

var low = require('lowlight')

console.log(low.highlight('css', 'em { color: red }'))

Yields:

{ relevance: 4, language: 'css', value: [Array] }

low.highlightAuto(value[, options])

Parse value by guessing its grammar.

options

• prefix (string?, default: 'hljs-') — Class prefix
• subset (Array.<string>? default: all registered languages) — List of allowed languages

Returns

Result, with a secondBest if found.

Example

var low = require('lowlight')

console.log(low.highlightAuto('"hello, " + name + "!"'))

Yields:

{
  relevance: 3,
  language: 'applescript',
  value: [Array],
  secondBest: {relevance: 3, language: 'basic', value: [Array]}
}

Result

Result is a highlighting result object.

Properties

• relevance (number) — How sure low is that the given code is in the found language
• language (string) — The detected language
• value (Array.<Node>) — Virtual nodes representing the highlighted given code
• secondBest (Result?) — Result of the second-best (based on relevance) match. Only set by highlightAuto, but can still be null.

low.registerLanguage(name, syntax)

Register a syntax as name (string). Useful in the browser or with custom grammars.

Example

var low = require('lowlight/lib/core')
var xml = require('highlight.js/lib/languages/xml')

low.registerLanguage('xml', xml)

console.log(low.highlight('html', '<em>Emphasis</em>'))

Yields:

{relevance: 2, language: 'html', value: [Array]}

low.registerAlias(name[, alias])

Register a new alias for the name language.

Signatures

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

Parameters

• name (string) — Name of a registered language
• alias (string) — New alias for the registered language
• list (Array.<alias>) — List of aliases
• aliases (Object.<alias|list>) — Map where each key is a name and each value an alias or a list

Example

var low = require('lowlight/lib/core')
var md = require('highlight.js/lib/languages/markdown')

low.registerLanguage('markdown', md)

// low.highlight('mdown', '<em>Emphasis</em>')
// ^ would throw: Error: Unknown language: `mdown` is not registered

low.registerAlias({markdown: ['mdown', 'mkdn', 'mdwn', 'ron']})
low.highlight('mdown', '<em>Emphasis</em>')
// ^ Works!

low.listLanguages()

List all registered languages.

Returns

Array.<string>.

Example

var low = require('lowlight/lib/core')
var md = require('highlight.js/lib/languages/markdown')

console.log(low.listLanguages()) // => []

low.registerLanguage('markdown', md)

console.log(low.listLanguages()) // => ['markdown']

Browser

It is not suggested to use the pre-built files or requiring lowlight in the browser as that would include 838kB (241kB GZipped) of code.

Instead, require lowlight/lib/core, and include only the used highlighters. For example:

var low = require('lowlight/lib/core')
var js = require('highlight.js/lib/languages/javascript')

low.registerLanguage('javascript', js)

low.highlight('js', '"use strict";')
// See `Usage` for the results.

…when using browserify and minifying with tinyify this results in just 18kB of code (7kB with GZip).

Related

• refractor — Same, but based on 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 — Syntax highlighting in rehype
• remark-highlight.js — Syntax highlighting in remark
• jstransformer-lowlight — Syntax highlighting for JSTransformers and Pug

License

MIT © Titus Wormer