readme.md

rehype-starry-night

rehype plugin to apply syntax highlighting to code with starry-night.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • Options
  • rehypeStarryNight(options) (default)
• HTML
• CSS
• Compatibility
• Security
• Related
• Contribute
• License

What is this?

This package is a unified (rehype) plugin to perform syntax highlighting. It uses starry-night, which is a high quality highlighter that can support tons of grammars and approaches how GitHub renders code.

When should I use this?

This plugin is useful when you want to perform syntax highlighting in rehype. If you are not using rehype, you can instead use starry-night directly.

You can combine this package with rehype-twoslash. That processes JavaScript and TypeScript code with twoslash and also uses starry-night just for that code.

starry-night has a WASM dependency, and rather big grammars, which means that this plugin might be too heavy particularly in browsers, in which case rehype-highlight might be more suitable.

Install

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

npm install rehype-starry-night

In Deno with esm.sh:

import rehypeStarryNight from 'https://esm.sh/rehype-starry-night@2'

In browsers with esm.sh:

<script type="module">
  import rehypeStarryNight from 'https://esm.sh/rehype-starry-night@2?bundle'
</script>

Use

Say we have the following file example.md:

# Neptune

```rs
fn main() {
    println!("Hello, Neptune!");
}
```

…and our module example.js contains:

import rehypeStarryNight from 'rehype-starry-night'
import rehypeStringify from 'rehype-stringify'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {read} from 'to-vfile'
import {unified} from 'unified'

const file = await read('example.md')

await unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeStarryNight)
  .use(rehypeStringify)
  .process(file)

console.log(String(file))

…then running node example.js yields:

<h1>Neptune</h1>
<pre><code class="language-rs"><span class="pl-k">fn</span> <span class="pl-en">main</span>() {
    <span class="pl-en">println!</span>(<span class="pl-s"><span class="pl-pds">"</span>Hello, Neptune!<span class="pl-pds">"</span></span>);
}
</code></pre>

API

Options

Configuration for rehype-starry-night.

Extends

• StarryNightOptions

Fields

• allowMissingScopes? (boolean | null | undefined) — do not warn for missing scopes (default: false)
• grammars? (ReadonlyArray<Grammar> | null | undefined) — grammars to support (default: common)
• plainText? (ReadonlyArray<string> | null | undefined) — list of language names to not highlight (default: [])

rehypeStarryNight(options) (default)

Plugin to highlight code with starry-night.

Parameters

• options? (Readonly<Options> | null | undefined) — configuration (optional)

Returns

Transform ((tree: Root, file: VFile) => Promise<Root>).

HTML

On the input side, this plugin looks for code blocks with a language-* class.

On the output side, this plugin generates span elements with classes that can be enhanced with CSS.

CSS

See “CSS” in starry-night for more info.

Compatibility

Projects maintained by the unified collective are 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, rehype-starry-night@2, compatible with Node.js 16.

Security

This package is safe.

Related

• rehype-highlight — highlight code blocks with lowlight
• rehype-twoslash — process JavaScript/TypeScript code with twoslash and starry-night too

Contribute

See contributing.md in rehypejs/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Julien Barbay