emphasize

ANSI syntax highlighting for the terminal.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • all
  • common
  • createEmphasize(grammars?)
  • emphasize.highlight(language, value[, options])
  • emphasize.highlightAuto(value[, options])
  • emphasize.listLanguages()
  • emphasize.register(grammars)
  • emphasize.registerAlias(aliases)
  • emphasize.registered(aliasOrLanguage)
  • AutoOptions
  • LanguageFn
  • Result
  • Sheet
  • Style
• 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:

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)

Register languages.

See lowlight.register.

emphasize.registerAlias(aliases)

Register 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

MIT © Titus Wormer