Close up of The Starry Night by Vincent van Gogh (1889)
with examples of starry-night over it

starry-night

[![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]

Syntax highlighting,
like what GitHub uses to highlight code,
but free and open source and JavaScript!

Contents

* What is this?
* When should I use this?
* What is PrettyLights?
* Install
* Use
* API
* all
* common
* [createStarryNight(grammars[, options])](#createstarrynightgrammars-options)
* starryNight.flagToScope(flag)
* starryNight.highlight(value, scope)
* starryNight.missingScopes()
* starryNight.register(grammars)
* starryNight.scopes()
* GetOnigurumaUrl
* Grammar
* Options
* Examples
* Example: serializing hast as html
* Example: using starry-night on the client
* Example: turning hast into react nodes
* Example: adding line numbers
* Example: integrate with unified, remark, and rehype
* Example: integrating with markdown-it
* Syntax tree
* CSS
* Languages
* Compatibility
* Security
* Related
* Contribute
* License

What is this?

This package is an open source version of GitHub’s closed-source PrettyLights
project (more on that later).
It supports 600+ grammars and its extremely high quality.
It uses TextMate grammars which are also used in popular editors
(SublimeText, Atom, VS Code, \&c).
They’re heavy but high quality.

When should I use this?

starry-night is a high quality highlighter
(when your readers or authors are programmers,
you want this!)
that can support tons of grammars
(from new things like MDX to much more!)
which approaches how GitHub renders code.

It has a WASM dependency,
and rather big grammars,
which means that starry-night might be too heavy particularly in browsers,
in which case [lowlight][github-lowlight] or [refractor][github-refractor]
might be more suitable.

This project is similar to the excellent [shiki][github-shiki],
and it uses the same underlying dependencies,
but starry-night is meant to match GitHub in that it produces classes and
works with the CSS it ships,
making it easier to add dark mode and other themes with CSS compared to inline
styles.

Finally,
this package produces objects (an AST),
which makes it useful when you want to perform syntax highlighting in a place
where serialized HTML wouldn’t work or wouldn’t work well.
For example,
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 [hast][github-hast] or [rehype][github-rehype].

Bundled,
minified,
and gzipped,
starry-night and the WASM binary are 185 kB.
There are two lists of grammars you can use:
[common][api-common]
(±35 languages, good for your own site)
adds 250 kB and [all][api-all]
(\~600 languages, useful if you are making a site like GitHub)
is 1.6 MB.
You can also manually choose which grammars to include
(or add to common):
a language is typically between 3 and 5 kB.
To illustrate,
Astro costs 2.1 kB and TSX costs 25.4 kB.

What is PrettyLights?

PrettyLights is the syntax highlighter that GitHub uses to turn this:

```markdown
`markdown


Hello, world!

`html
# Hello, world!
`

…which is what starry-night does too
(some small differences in markup,
but essentially the same)!

PrettyLights is responsible for taking the flag markdown,
looking it up in
[languages.yml from github-linguist][github-linguist-languages-yml]
to figure out that that means markdown,
taking a corresponding grammar
(in this case
[wooorm/markdown-tm-language][github-markdown-tm-language]),
doing some GPL magic in C,
and turning it into spans with classes.

GitHub is using PrettyLights since December 2014,
when it [replaced Pygments][github-pages-pygments].
They wanted to open source it,
but [were unable][github-pages-license] due to licensing issues.
Recently ([Feb 2019][github-tree-sitter-tree-lights]?),
GitHub has slowly started to move towards TreeLights,
which is based on TreeSitter,
and also closed source.
If TreeLights includes a language
(currently: C, C#, CSS, CodeQL, EJS, Elixir, ERB, Gleam, Go, HTML, Java, JS,
Nix, PHP, Python, RegEx, Ruby, Rust, TLA, TS),
that’ll be used,
for everything else PrettyLights is used.

starry-night does what PrettyLights does,
not what TreeLights does.
I’m hopeful that that will be open sourced in the future and we can mimic both.

![][artsandculture-google-starry-night]

Install

This package is [ESM only][github-gist-esm].
In Node.js (version 16+),
install with [npm][npmjs-install]:

`sh
npm install @wooorm/starry-night
`

In Deno with [esm.sh][esmsh]:

`js
import {common, createStarryNight} from 'https://esm.sh/@wooorm/starry-night@3'
`

In browsers with [esm.sh][esmsh]:

`html

`

To get the CSS in browsers,
do
(see [CSS][section-css] for more info):

`html


`

Use

`js
import {common, createStarryNight} from '@wooorm/starry-night'

const starryNight = await createStarryNight(common)

const scope = starryNight.flagToScope('markdown')
const tree = starryNight.highlight('# hi', scope)

console.log(tree)
`

Yields:

`js
{
type: 'root',
children: [
{
type: 'element',
tagName: 'span',
properties: {className: ['pl-mh']},
children: [
{type: 'text', value: '# '},
{
type: 'element',
tagName: 'span',
properties: {className: ['pl-en']},
children: [{type: 'text', value: 'hi'}]
}
]
}
]
}
`

API

This package exports the identifiers
[all][api-all],
[common][api-common],
and
[createStarryNight][api-create-starry-night]
from the main module.
It exports the additional [TypeScript][] types
[GetOnigurumaUrl][api-get-oniguruma-url],
[Grammar][api-grammar],
and [Options][api-options].
There is no default export.

It also includes grammars directly in its export map,
which each expose a [Grammar][api-grammar] as the default export.
Do not use the lang/ folder or the .js extension.

For CSS files,
do use style/ and don’t use .css:

`js
import sourceMdx from '@wooorm/starry-night/source.mdx' // Grammar.
import styleTritanopiaDark from '@wooorm/starry-night/style/tritanopia-dark' // CSS.
`

$3

List of all grammars ([Array][api-grammar])

$3

List of ±35 common grammars ([Array][api-grammar])

$3

Create a StarryNight that can highlight things with the given grammars.
This is async to allow async loading and registering,
which is currently only used for WASM.

###### Parameters

* grammars
([Array][api-grammar])
— grammars to support
* options
([Options][api-options], optional)
— configuration

###### Returns

Promise that resolves to an instance which highlights with the bound
grammars (Promise).

$3

Get the grammar scope (such as text.md) associated with a grammar name
(such as markdown) or grammar extension (such as .mdwn).

This function uses the first word (when splitting on spaces and tabs) that is
used after the opening of a fenced code block:

``markdown
`js
console.log(1)
`
``

To match GitHub,
this also accepts entire paths:

``markdown
`path/to/example.js
console.log(1)
`
``

> 👉 Note:
> languages can use the same extensions.
> For example,
> .h is reused by many languages.
> In those cases,
> you will get one scope back,
> but it might not be the most popular language associated with an extension.

###### Parameters

* flag
(string)
— grammar name
(such as 'markdown'),
grammar extension
(such as '.mdwn'),
or entire file path ending in extension

###### Returns

Grammar scope,
such as 'text.md'
(string or undefined).

###### Example

`js
import {common, createStarryNight} from '@wooorm/starry-night'

const starryNight = await createStarryNight(common)

console.log(starryNight.flagToScope('pandoc')) // 'text.md'
console.log(starryNight.flagToScope('workbook')) // 'text.md'
console.log(starryNight.flagToScope('.workbook')) // 'text.md'
console.log(starryNight.flagToScope('path/to/example.js')) // 'source.js'
console.log(starryNight.flagToScope('whatever')) // undefined
`

$3

Highlight programming code.

###### Parameters

* value (string)
— code to highlight
* scope (string)
— registered grammar scope to highlight as (such as 'text.md')

###### Returns

Node representing highlighted code ([Root][github-hast-root]).

###### Example

`js
import sourceCss from '@wooorm/starry-night/source.css'
import {createStarryNight} from '@wooorm/starry-night'

const starryNight = await createStarryNight([sourceCss])

console.log(starryNight.highlight('em { color: red }', 'source.css'))
`

Yields:

`js
{
type: 'root',
children: [
{type: 'element', tagName: 'span', properties: [Object], children: [Array]},
{type: 'text', value: ' { '},
{type: 'element', tagName: 'span', properties: [Object], children: [Array]},
{type: 'text', value: ': '},
{type: 'element', tagName: 'span', properties: [Object], children: [Array]},
{type: 'text', value: ' }'}
]
}
`

$3

List scopes that are needed by the registered grammars but that are
missing.

To illustrate,
the text.xml.svg grammar needs the text.xml grammar.
When you register text.xml.svg without text.xml,
it will be listed here.

###### Returns

List of grammar scopes,
such as 'text.md'
(Array).

###### Example

`js
import textXmlSvg from '@wooorm/starry-night/text.xml.svg'
import textXml from '@wooorm/starry-night/text.xml'
import {createStarryNight} from '@wooorm/starry-night'

const svg = await createStarryNight([textXmlSvg])
console.log(svg.missingScopes()) //=> ['text.xml']

const svgAndXml = await createStarryNight([textXmlSvg, textXml])
console.log(svgAndXml.missingScopes()) //=> []
`

$3

Add more grammars.

###### Parameters

* grammars ([Array][api-grammar])
— grammars to support

###### Returns

Promise resolving to nothing (Promise).

###### Example

``js
import sourceCss from '@wooorm/starry-night/source.css'
import textMd from '@wooorm/starry-night/text.md'
import {createStarryNight} from '@wooorm/starry-night'
import {toHtml} from 'hast-util-to-html'

const markdown = '`css\nem { color: red }\n`'

const starryNight = await createStarryNight([textMd])

console.log(toHtml(starryNight.highlight(markdown, 'text.md')))

await starryNight.register([sourceCss])

console.log(toHtml(starryNight.highlight(markdown, 'text.md')))
``

Yields:

``html
`css
em { color: red }
`
``

``html
`css
em { color: red }
`
``

$3

List all registered scopes.

###### Returns

List of grammar scopes,
such as 'text.md'
(Array).

###### Example

`js
import {common, createStarryNight} from '@wooorm/starry-night'

const starryNight = await createStarryNight(common)

console.log(starryNight.scopes())
`

Yields:

`js
[
'source.c',
'source.c++',
// …
'text.xml',
'text.xml.svg'
]
`

$3

Function to get a URL to the oniguruma WASM (TypeScript type).

> 👉 Note:
> this must currently result in a version 2 URL of onig.wasm from
> [vscode-oniguruma][github-vscode-oniguruma].

> ⚠️ Danger:
> when you use this functionality,
> your project might break at any time
> (when reinstalling dependencies),
> except when you make sure that the WASM binary you load manually is what our
> internally used vscode-oniguruma dependency expects.
> To solve this, you could for example use an npm script called
> [dependencies][npmjs-using-npm-script-dependencies]
> (which runs everytime node_modules is changed)
> which copies vscode-oniguruma/release/onig.wasm to the place you want to
> host it.

###### Returns

URL object to a WASM binary (Promise or URL).

###### Example

`js
import {common, createStarryNight} from '@wooorm/starry-night'

const starryNight = await createStarryNight(common, {
getOnigurumaUrlFetch() {
return new URL('/onig.wasm', window.location.href);
}
})
`

$3

TextMate grammar with some extra info (TypeScript type).

###### Fields

* dependencies
(Array, optional, example: ['source.tsx'])
— list of scopes that are needed for this grammar to work
* extensions
(Array, example: ['.mdx'])
— list of extensions
* extensionsWithDot
(Array, optional, example: ['.php'])
— list of extensions that only match if used w/ a dot
* injections
(Record, optional)
— TextMate injections
* names
(Array, example: ['mdx'])
— list of names
* patterns
(Array)
— TextMate patterns
* repository
(Record, optional)
— TextMate repository
* scopeName
(string, example: 'source.mdx')
— scope

$3

Configuration (TypeScript type).

###### Fields

* getOnigurumaUrlFetch
([GetOnigurumaUrl][api-get-oniguruma-url], optional)
— get a URL to the oniguruma WASM,
typically used in browsers
* getOnigurumaUrlFs
([GetOnigurumaUrl][api-get-oniguruma-url], optional)
— get a URL to the oniguruma WASM,
typically used in Node.js

Examples

$3

[hast][github-hast] trees as returned by starry-night can be serialized with
[hast-util-to-html][github-hast-util-to-html]:

`js
import {common, createStarryNight} from '@wooorm/starry-night'
import {toHtml} from 'hast-util-to-html'

const starryNight = await createStarryNight(common)

const tree = starryNight.highlight('"use strict";', 'source.js')

console.log(toHtml(tree))
`

Yields:

`html
"use strict";
`

$3

You don’t have to do preprocess things on a server.
Particularly,
when you are not using Node.js or so.
Or,
when you have a lot of often changing content
(likely markdown),
such as on a page of comments.

In those cases,
you can run starry-night in the browser.
Here is an example.
It also uses [hast-util-to-dom][github-hast-util-to-dom],
which is a light way to turn the AST into DOM nodes.

Say we have this example.js on our browser (no bundling needed!):

`js
import {
common,
createStarryNight
} from 'https://esm.sh/@wooorm/starry-night@3?bundle'
import {toDom} from 'https://esm.sh/hast-util-to-dom@4?bundle'

const starryNight = await createStarryNight(common)
const prefix = 'language-'

const nodes = Array.from(document.body.querySelectorAll('code'))

for (const node of nodes) {
const className = Array.from(node.classList).find(function (d) {
return d.startsWith(prefix)
})
if (!className) continue
const scope = starryNight.flagToScope(className.slice(prefix.length))
if (!scope) continue
const tree = starryNight.highlight(node.textContent, scope)
node.replaceChildren(toDom(tree, {fragment: true}))
}
`

…and then,
if we would have an index.html for our document:

`html







Hello

console.log('it works!')

Opening that page in a browser,
we’d see the being swapped with:

`html
console.log('it works!')

`

$3

hast trees as returned by starry-night can be turned into
preact, react, solid, svelte, vue, etc.,
with
[hast-util-to-jsx-runtime][github-hast-util-to-jsx-runtime]:

`js
import {common, createStarryNight} from '@wooorm/starry-night'
import {toJsxRuntime} from 'hast-util-to-jsx-runtime'
import {Fragment, jsx, jsxs} from 'react/jsx-runtime'

const starryNight = await createStarryNight(common)

const tree = starryNight.highlight('"use strict";', 'source.js')
const reactNode = toJsxRuntime(tree, {Fragment, jsx, jsxs})

console.log(reactNode)
`

Yields:

`js
{
'$$typeof': Symbol(react.element),
type: Symbol(react.fragment),
key: null,
ref: null,
props: { children: [ [Object], ';' ] },
_owner: null,
_store: {}
}
`

$3

GitHub itself does not add line numbers to the code they highlight.
You can do that,
by transforming the AST.
Here’s an example of a utility that wraps each line into a span with a class and
a data attribute with its line number.
That way,
you can style the lines as you please.
Or you can generate different elements for each line,
of course.

Say we have our utility as hast-util-starry-night-gutter.js:

`js
/**
* @import {ElementContent, Element, RootContent, Root} from 'hast'
*/

/**
* @param {Root} tree
* Tree.
* @returns {undefined}
* Nothing.
*/
export function starryNightGutter(tree) {
/* @type {Array} /
const replacement = []
const search = /\r?\n|\r/g
let index = -1
let start = 0
let startTextRemainder = ''
let lineNumber = 0

while (++index < tree.children.length) {
const child = tree.children[index]

if (child.type === 'text') {
let textStart = 0
let match = search.exec(child.value)

while (match) {
// Nodes in this line.
const line = /* @type {Array} / (
tree.children.slice(start, index)
)

// Prepend text from a partial matched earlier text.
if (startTextRemainder) {
line.unshift({type: 'text', value: startTextRemainder})
startTextRemainder = ''
}

// Append text from this text.
if (match.index > textStart) {
line.push({
type: 'text',
value: child.value.slice(textStart, match.index)
})
}

// Add a line, and the eol.
lineNumber += 1
replacement.push(createLine(line, lineNumber), {
type: 'text',
value: match[0]
})

start = index + 1
textStart = match.index + match[0].length
match = search.exec(child.value)
}

// If we matched, make sure to not drop the text after the last line ending.
if (start === index + 1) {
startTextRemainder = child.value.slice(textStart)
}
}
}

const line = /* @type {Array} / (tree.children.slice(start))
// Prepend text from a partial matched earlier text.
if (startTextRemainder) {
line.unshift({type: 'text', value: startTextRemainder})
startTextRemainder = ''
}

if (line.length > 0) {
lineNumber += 1
replacement.push(createLine(line, lineNumber))
}

// Replace children with new array.
tree.children = replacement
}

/**
* @param {Array} children
* @param {number} line
* @returns {Element}
*/
function createLine(children, line) {
return {
type: 'element',
tagName: 'span',
properties: {className: 'line', dataLineNumber: line},
children
}
}
`

…and a module example.js:

``js
import {common, createStarryNight} from '@wooorm/starry-night'
import {toHtml} from 'hast-util-to-html'
import {starryNightGutter} from './hast-util-starry-night-gutter.js'

const starryNight = await createStarryNight(common)

const tree = starryNight.highlight(
'# Some heading\n\n`js\nalert(1)\n`\n*',
'text.md'
)

starryNightGutter(tree)

console.log(toHtml(tree))
``

Now running node example.js yields:

``html
# Some heading

`js
alert(1)
`
*
``

$3

This example shows how to use
[rehype-starry-night][github-rehype-starry-night] with
[unified][github-unified].
If we have a markdown file example.md:

``markdown


Hello

…world!

`js
console.log('it works!')
`
``

…and a module example.js:

`js
import fs from 'node:fs/promises'
import rehypeStarryNight from 'rehype-starry-night'
import rehypeStringify from 'rehype-stringify'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {unified} from 'unified'

const file = await unified()
.use(remarkParse)
.use(remarkRehype)
.use(rehypeStarryNight)
.use(rehypeStringify)
.process(await fs.readFile('example.md'))

console.log(String(file))
`

…then running node example.js yields:

`html


Hello

console.log('it works!')

console.log('it works!')