ANSI syntax highlighting for the terminal
npm install emphasize[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
[![Size][badge-size-image]][badge-size-url]
ANSI syntax highlighting for the terminal.
* What is this?
* When should I use this?
* Install
* Use
* API
* all
* common
* createEmphasize(grammars?)
* [emphasize.highlight(language, value[, options])](#emphasizehighlightlanguage-value-options)
* [emphasize.highlightAuto(value[, options])](#emphasizehighlightautovalue-options)
* emphasize.listLanguages()
* emphasize.register(grammars)
* emphasize.registerAlias(aliases)
* emphasize.registered(aliasOrLanguage)
* AutoOptions
* LanguageFn
* Result
* Sheet
* Style
* Compatibility
* Security
* Contribute
* License
This package wraps [lowlight][github-lowlight] to output ANSI syntax
highlighting instead of HTML.
It can support 190+ programming languages.
This package is useful when you want to display code on a terminal.
This package is [ESM only][github-gist-esm].
In Node.js (version 16+),
install with [npm][npm-install]:
``sh`
npm install emphasize
In Deno with [esm.sh][esm-sh]:
`js`
import {all, common, createEmphasize} from 'https://esm.sh/emphasize@7'
In browsers with [esm.sh][esm-sh]:
`html`
Say example.css looks as follows:
`css
@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:
`js
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:
`txt
\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]\x1B39m\x1B[35m::after\x1B[39m {
\x1B[33mcontent\x1B[39m: \x1B[31mattr\x1B[39m(href)
}
}
`
…which looks as follows:
![Screenshot showing the code in terminal
This package exports the identifiers
[all][api-all],common
[][api-common],createEmphasize
and [][api-create-emphasize].
There is no default export.
It exports the [TypeScript][] types
[AutoOptions][api-auto-options],LanguageFn
[][api-language-fn],Result
[][api-result],Sheet
[][api-sheet],Style
and [][api-style].
Map of all (±190) grammars ([Record][api-language-fn]).
See [all from lowlight][github-lowlight-all].
Map of common (37) grammars ([Record][api-language-fn]).
See [common from lowlight][github-lowlight-common].
Create a emphasize instance.
###### Parameters
* grammars ([Record][api-language-fn], optional)
— grammars to add
###### Returns
Emphasize (emphasize).
Highlight value (code) as language (name).
###### Parameters
* language (string)value
— programming language [name][github-highlight-names]
* (string)sheet
— code to highlight
* ([Sheet][api-sheet], optional)
— style sheet
###### Returns
[Result][api-result].
Highlight value (code) and guess its programming language.
###### Parameters
* value (string)options
— code to highlight
* ([AutoOptions][api-auto-options] or [Sheet][api-sheet],
optional)
— configuration or style sheet
###### Returns
[Result][api-result].
List registered languages.
See [lowlight.listLanguages][github-lowlight-list-languages].
Register languages.
See [lowlight.register][github-lowlight-register].
Register aliases.
See [lowlight.registerAlias][github-lowlight-register-alias].
Check whether an alias or name is registered.
See [lowlight.registered][github-lowlight-registered].
Configuration for highlightAuto (TypeScript type).
###### Fields
* sheet ([Sheet][api-sheet], optional)subset
— sheet
* (Array, default: all registered languages)
— list of allowed languages
Highlight.js grammar (TypeScript type).
See [LanguageFn from lowlight][github-lowlight-langauge-fn].
Result (TypeScript type).
###### Fields
* language (string or undefined)relevance
— detected programming language.
* (number or undefined)lowlight
— how sure is that the given code is in the languagevalue
* (string)
— highlighted code
Map [highlight.js classes][github-highlight-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][github-chalk-styles] is suggested.
An abbreviated example is as follows:
`js`
{
'comment': chalk.gray,
'meta meta-string': chalk.cyan,
'meta keyword': chalk.magenta,
'emphasis': chalk.italic,
'strong': chalk.bold,
'formula': chalk.inverse
}
###### Type
`ts`
type Sheet = Record
Color something (TypeScript type).
###### Parameters
* value (string)
— input
###### Returns
Output (string).
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.
This package is safe.
Yes please!
See [How to Contribute to Open Source][open-source-guide-contribute].
[MIT][file-license] © [Titus Wormer][wooorm]
[api-all]: #all
[api-auto-options]: #autooptions
[api-common]: #common
[api-create-emphasize]: #createemphasizegrammars
[api-language-fn]: #languagefn
[api-result]: #result
[api-sheet]: #sheet
[api-style]: #style
[badge-build-image]: https://github.com/wooorm/emphasize/workflows/main/badge.svg
[badge-build-url]: https://github.com/wooorm/emphasize/actions
[badge-coverage-image]: https://img.shields.io/codecov/c/github/wooorm/emphasize.svg
[badge-coverage-url]: https://codecov.io/github/wooorm/emphasize
[badge-downloads-image]: https://img.shields.io/npm/dm/emphasize.svg
[badge-downloads-url]: https://www.npmjs.com/package/emphasize
[badge-size-image]: https://img.shields.io/bundlejs/size/emphasize
[badge-size-url]: https://bundlejs.com/?q=emphasize
[npm-install]: https://docs.npmjs.com/cli/install
[esm-sh]: https://esm.sh
[file-license]: license
[github-chalk-styles]: https://github.com/chalk/chalk#styles
[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
[github-highlight-classes]: https://highlightjs.readthedocs.io/en/latest/css-classes-reference.html
[github-highlight-names]: https://github.com/highlightjs/highlight.js/blob/main/SUPPORTED_LANGUAGES.md
[github-lowlight]: https://github.com/wooorm/lowlight
[github-lowlight-all]: https://github.com/wooorm/lowlight#all
[github-lowlight-common]: https://github.com/wooorm/lowlight#common
[github-lowlight-langauge-fn]: https://github.com/wooorm/lowlight#languagefn
[github-lowlight-list-languages]: https://github.com/wooorm/lowlight#lowlightlistlanguages
[github-lowlight-register]: https://github.com/wooorm/lowlight#lowlightregistergrammars
[github-lowlight-register-alias]: https://github.com/wooorm/lowlight#lowlightregisteraliasaliases
[github-lowlight-registered]: https://github.com/wooorm/lowlight#lowlightregisteredaliasorlanguage
[open-source-guide-contribute]: https://opensource.guide/how-to-contribute/
[typescript]: https://www.typescriptlang.org
[wooorm]: https://wooorm.com