emphasize

ANSI syntax highlighting for the terminal.

What is this?
When should I use this?
Install
Use
API
Compatibility
Security
Contribute
License

What is this?

This package wraps lowlight to output ANSI syntax highlighting instead of HTML. It can support 190+ programming languages.

When should I use this?

This package is useful when you want to display code on a terminal.

Install

This package is ESM only. In Node.js (version 16+), install with npm:

npm install emphasize

In Deno with esm.sh:

import {all, common, createEmphasize} from 'https://esm.sh/emphasize@7'

In browsers with esm.sh:

<script type="module">
  import {all, common, createEmphasize} from 'https://esm.sh/emphasize@7?bundle'
</script>

Use

Say example.css looks as follows:

@font-face {
  font-family: Alpha;
  src: url('Bravo.otf');
}

body, .charlie, #delta {
  color: #bada55;
  background-color: rgba(33, 33, 33, 0.33);
  font-family: "Alpha", sans-serif;
}

@import url(echo.css);

@media print {
  a[href^=http]::after {
    content: attr(href)
  }
}

…and example.js contains the following:

import fs from 'node:fs/promises'
import {emphasize} from 'emphasize'

const doc = String(await fs.readFile('example.css'))

const output = emphasize.highlightAuto(doc).value

console.log(output)

…now running node example.js yields:

\x1B[32m@font-face\x1B[39m {
  \x1B[33mfont-family\x1B[39m: Alpha;
  \x1B[33msrc\x1B[39m: \x1B[31murl\x1B[39m(\x1B[36m'Bravo.otf'\x1B[39m);
}

\x1B[32mbody\x1B[39m, \x1B[34m.charlie\x1B[39m, \x1B[34m#delta\x1B[39m {
  \x1B[33mcolor\x1B[39m: \x1B[36m#bada55\x1B[39m;
  \x1B[33mbackground-color\x1B[39m: \x1B[31mrgba\x1B[39m(\x1B[36m33\x1B[39m, \x1B[36m33\x1B[39m, \x1B[36m33\x1B[39m, \x1B[36m0.33\x1B[39m);
  \x1B[33mfont-family\x1B[39m: \x1B[36m"Alpha"\x1B[39m, sans-serif;
}

\x1B[32m@import\x1B[39m url(echo.css);

\x1B[32m@media\x1B[39m print {
  \x1B[32ma\x1B[39m\x1B[35m[href^=http]\x1B[39m\x1B[35m::after\x1B[39m {
    \x1B[33mcontent\x1B[39m: \x1B[31mattr\x1B[39m(href)
  }
}

…which looks as follows:

Screenshot showing the code in terminal

API

This package exports the identifiers all, common, and createEmphasize. There is no default export.

It exports the TypeScript types AutoOptions, LanguageFn, Result, Sheet, and Style.

`all`

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

See all from lowlight.

`common`

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

See common from lowlight.

`createEmphasize(grammars?)`

Create a emphasize instance.

Parameters

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

Returns

Emphasize (emphasize).

`emphasize.highlight(language, value[, options])`

Highlight value (code) as language (name).

Parameters

language (string) — programming language name
value (string) — code to highlight
sheet (Sheet, optional) — style sheet

Returns

Result.

`emphasize.highlightAuto(value[, options])`

Highlight value (code) and guess its programming language.

Parameters

value (string) — code to highlight
options (AutoOptions or Sheet, optional) — configuration or style sheet

Returns

Result.

`emphasize.listLanguages()`

List registered languages.

See lowlight.listLanguages.

`emphasize.register(grammars)`

See lowlight.register.

`emphasize.registerAlias(aliases)`

See lowlight.registerAlias.

`emphasize.registered(aliasOrLanguage)`

Check whether an alias or name is registered.

See lowlight.registered.

`AutoOptions`

Configuration for highlightAuto (TypeScript type).

Fields

sheet (Sheet, optional) — sheet
subset (Array<string>, default: all registered languages) — list of allowed languages

`LanguageFn`

Highlight.js grammar (TypeScript type).

See LanguageFn from lowlight.

`Result`

Result (TypeScript type).

Fields

language (string or undefined) — detected programming language.
relevance (number or undefined) — how sure lowlight is that the given code is in the language
value (string) — highlighted code

`Sheet`

Map highlight.js classes to styles functions (TypeScript type).

The hljs- prefix must not be used in those classes. The “descendant selector” (a space) is supported.

For convenience chalk’s chaining of styles is suggested. An abbreviated example is as follows:

{
  'comment': chalk.gray,
  'meta meta-string': chalk.cyan,
  'meta keyword': chalk.magenta,
  'emphasis': chalk.italic,
  'strong': chalk.bold,
  'formula': chalk.inverse
}

Type

type Sheet = Record<string, Style>

`Style`

Color something (TypeScript type).

Parameters

value (string) — input

Returns

Output (string).

Compatibility

This projects 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, emphasize@7, compatible with Node.js 16.

Security

This package is safe.

Contribute

Yes please! See How to Contribute to Open Source.

License

Current Tags

7.0.0 ... latest (a year ago)

emphasize

Contents

What is this?

When should I use this?

Install

Use

API

`all`

`common`

`createEmphasize(grammars?)`

Parameters

Returns

`emphasize.highlight(language, value[, options])`

Parameters

Returns

`emphasize.highlightAuto(value[, options])`

Parameters

Returns

`emphasize.listLanguages()`

`emphasize.register(grammars)`

`emphasize.registerAlias(aliases)`

`emphasize.registered(aliasOrLanguage)`

`AutoOptions`

Fields

`LanguageFn`

`Result`

Fields

`Sheet`

Type

`Style`

Parameters

Returns

Compatibility

Security

Contribute

License

Current Tags

15 Versions