rehype-starry-night
rehype plugin to highlight code with Starry Night
What’s this?
This package is a unified (rehype) plugin to highlight code with Starry Night in a markdown document. The syntax highlighting mimics what GitHub's syntax highlighting color schemes.
When should I use this?
This project is useful if you want to use the syntax highlighting powered by VS Code syntax highlighter engine, and themes similar to GitHub. It is also useful if you want to build your own syntax highlighting themes based on CSS custom properties.
The following additonal features are also available:
- line numbers
- line highlights
- support for prompt
- captions and language information
- highlighting inline
code
elements
Install
This package is ESM only.
In Node.js (version 16.0+), install with npm:
npm install @microflash/rehype-starry-night
In Deno, with esm.sh:
import rehypeStarryNight from "https://esm.sh/@microflash/rehype-starry-night";
In browsers, with esm.sh:
<script type="module">
import rehypeStarryNight from "https://esm.sh/@microflash/rehype-starry-night?bundle";
</script>
Use
Say we have the following file example.md
:
```css
html {
box-sizing: border-box;
text-size-adjust: 100%;
/* allow percentage based heights for the children */
height: 100%;
}
```
And our module example.js
looks as follows:
import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import rehypeStringify from "rehype-stringify";
import rehypeStarryNight from "@microflash/rehype-starry-night";
main();
async function main() {
const file = await unified()
.use(remarkParse)
.use(remarkRehype, { allowDangerousHtml: true })
.use(rehypeStarryNight)
.use(rehypeStringify, { allowDangerousHtml: true })
.process(markdown);
console.log(String(file));
}
Running that with node example.js
yields:
<div class="hl hl-css">
<div class="hl-header">
<div class="hl-language">css</div>
</div>
<pre id="MC45OTExNTEw"><code tabindex="0"><span class="line"><span class="line-number" aria-hidden="true">1</span><span class="pl-ent">html</span> {</span>
<span class="line"><span class="line-number" aria-hidden="true">2</span> <span class="pl-c1">box-sizing</span>: <span class="pl-c1">border-box</span>;</span>
<span class="line"><span class="line-number" aria-hidden="true">3</span> <span class="pl-c1">text-size-adjust</span>: <span class="pl-c1">100</span><span class="pl-k">%</span>;</span>
<span class="line"><span class="line-number" aria-hidden="true">4</span> <span class="pl-c">/* allow percentage based heights for the children */</span></span>
<span class="line"><span class="line-number" aria-hidden="true">5</span> <span class="pl-c1">height</span>: <span class="pl-c1">100</span><span class="pl-k">%</span>;</span>
<span class="line"><span class="line-number" aria-hidden="true">6</span>}</span>
</code></pre>
</div>
Support for inline code
elements
To highlight inline code
elements, import rehype-starry-night-inline
plugin. This plugin relies on the language information injected by the remark-inline-code-lang
plugin.
Say we have the following file example.md
:
To print a greeting, use `js> console.log("Hello, world!");`. When executed, it prints `Hello, world!`.
And our module example.js
looks as follows:
import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkInlineCodeLang from "@microflash/rehype-starry-night/remark-inline-code-lang";
import remarkRehype from "remark-rehype";
import rehypeStringify from "rehype-stringify";
import rehypeStarryNightInline from "@microflash/rehype-starry-night/rehype-starry-night-inline";
main();
async function main() {
const file = await unified()
.use(remarkParse)
.use(remarkInlineCodeLang)
.use(remarkRehype, { allowDangerousHtml: true })
.use(rehypeStarryNightInline)
.use(rehypeStringify, { allowDangerousHtml: true })
.process(markdown);
console.log(String(file));
}
Running that with node example.js
yields:
<p>To print a greeting, use <code class="hl-inline hl-js"><span class="pl-en">console</span>.<span class="pl-c1">log</span>(<span class="pl-s"><span class="pl-pds">"</span>Hello, world!<span class="pl-pds">"</span></span>);</code>. When executed, it prints <code>Hello, world!</code>.</p>
API
The default export is rehypeStarryNight
. The following options are available. All of them are optional.
aliases
: an object to alias languages to force syntax highlighting. By default, unknown languages are highlighted as plain text. Applicable to both rehype-starry-night
and rehype-starry-night-inline
.grammars
: a list of Starry Night compatible grammar definitions. By default, all grammars provided by Starry Night are used. Applicable to both rehype-starry-night
and rehype-starry-night-inline
.classNamePrefix
(default: hl
): a prefix for the classNames for different elements of HTML generated by rehype-starry-night
and rehype-starry-night-inline
.headerExtensions
: a list of functions to customize the header. Applicable to only rehype-starry-night
. By default, language-extension and caption-extension are used. A header extension has access to the following arguments.
headerOptions
: an object with a randomly generated id
attached to the pre
element, metadata
containing the caption, list of highlighted lines, etc., the language
tag specified on the code, and the classNamePrefix
children
: an array of nodes contained in the header
marker
(default: >
): the marker for inline code
element before which the language information is specified. Applicable to remark-inline-code-lang
.
Themes
Check out the available themes on Starry Night repository.
Import index.css or use it as a base for your own custom styles to style codeblock headers (containing language and captions) and gutters (providing line number, highlighting and prompt).
Supporting Light and Dark themes
There are multiple ways to support light and dark themes. Here's one way to do this; the appropriate theme will get activated based on system preferences.
:root {
--hl-background-color: hsl(0, 0%, 100%);
--hl-border-color: hsl(208, 21%, 86%);
--hl-code-highlight: hsl(208, 19%, 82%);
}
@media (prefers-color-scheme: dark) {
:root {
--hl-background-color: hsl(240, 20%, 2%);
--hl-border-color: hsl(208, 21%, 12%);
--hl-code-highlight: hsl(208, 19%, 13%);
}
}
@import "https://raw.githubusercontent.com/wooorm/starry-night/main/style/both.css";
@import "https://raw.githubusercontent.com/Microflash/rehype-starry-night/main/src/index.css";
[!WARNING]
URL imports for external styles is not recommended. You should either self-host them, bundle them, or copy-paste the entire CSS in one single file.
Examples
Example: single line codeblock
```sh
docker ps -a
```
The above codeblock will yield:
<div class="hl hl-sh">
<div class="hl-header">
<div class="hl-language">sh</div>
</div>
<pre id="MC4zNzExNzQw"><code tabindex="0"><span class="line">docker ps -a</span>
</code></pre>
</div>
Example: line numbers for multiline codeblock
```css
* {
display: revert;
}
```
The above codeblock will yield:
<div class="hl hl-css">
<div class="hl-header">
<div class="hl-language">css</div>
</div>
<pre id="MC4wMTQ1Nzg4"><code tabindex="0"><span class="line"><span class="line-number" aria-hidden="true">1</span><span class="pl-ent">*</span> {</span>
<span class="line"><span class="line-number" aria-hidden="true">2</span> <span class="pl-c1">display</span>: <span class="pl-c1">revert</span>;</span>
<span class="line"><span class="line-number" aria-hidden="true">3</span>}</span>
</code></pre>
</div>
Line numbers are automatically padded to ensure that they are aligned properly.
Example: show prompts
Sometimes you may want to show a prompt while displaying a command-line instruction. Prompts on multiple lines can be specified as follows.
```sh prompt{1,3}
curl localhost:8080/actuator/health
{"status":"UP"}
curl localhost:8080/greeter?name=Anya
Hello, Anya!
```
The above codeblock will yield:
<div class="hl hl-sh">
<div class="hl-header">
<div class="hl-language">sh</div>
</div>
<pre id="MC44MTg4MTA0"><code tabindex="0"><span class="line"><span class="line-number" aria-hidden="true">1</span><span class="line-prompt" aria-hidden="true"></span>curl localhost:8080/actuator/health</span>
<span class="line"><span class="line-number" aria-hidden="true">2</span>{<span class="pl-s"><span class="pl-pds">"</span>status<span class="pl-pds">"</span></span>:<span class="pl-s"><span class="pl-pds">"</span>UP<span class="pl-pds">"</span></span>}</span>
<span class="line"><span class="line-number" aria-hidden="true">3</span><span class="line-prompt" aria-hidden="true"></span>curl localhost:8080/greeter<span class="pl-k">?</span>name=Anya</span>
<span class="line"><span class="line-number" aria-hidden="true">4</span>Hello, Anya<span class="pl-k">!</span></span>
</code></pre>
</div>
index.css disables user-selection of prompts to make sure that when a user copies the content of a codeblock, the prompt is not copied.
Example: highlight lines
You can highlight multiple lines by specifying the line numbers (or even, range of line numbers) between curly braces in the codeblock metadata.
```sh {4..7} prompt{1}
aws --endpoint-url http://localhost:4566 s3api list-buckets
{
"Buckets": [
{
"Name": "my-bucket",
"CreationDate": "2022-07-12T13:44:44+00:00"
}
],
"Owner": {
"DisplayName": "webfile",
"ID": "bcaf1ffd86f41161ca5fb16fd081034f"
}
}
```
The above codeblock will yield:
<div class="hl hl-sh">
<div class="hl-header">
<div class="hl-language">sh</div>
</div>
<pre id="MC44MTc0NjQ5"><code tabindex="0"><span class="line"><span class="line-number" aria-hidden="true"> 1</span><span class="line-prompt" aria-hidden="true"></span>aws --endpoint-url http://localhost:4566 s3api list-buckets</span>
<span class="line"><span class="line-number" aria-hidden="true"> 2</span>{</span>
<span class="line"><span class="line-number" aria-hidden="true"> 3</span> <span class="pl-s"><span class="pl-pds">"</span>Buckets<span class="pl-pds">"</span></span>: [</span>
<span class="line" data-highlighted><span class="line-number" aria-hidden="true"> 4</span> {</span>
<span class="line" data-highlighted><span class="line-number" aria-hidden="true"> 5</span> <span class="pl-s"><span class="pl-pds">"</span>Name<span class="pl-pds">"</span></span>: <span class="pl-s"><span class="pl-pds">"</span>my-bucket<span class="pl-pds">"</span></span>,</span>
<span class="line" data-highlighted><span class="line-number" aria-hidden="true"> 6</span> <span class="pl-s"><span class="pl-pds">"</span>CreationDate<span class="pl-pds">"</span></span>: <span class="pl-s"><span class="pl-pds">"</span>2022-07-12T13:44:44+00:00<span class="pl-pds">"</span></span></span>
<span class="line" data-highlighted><span class="line-number" aria-hidden="true"> 7</span> }</span>
<span class="line"><span class="line-number" aria-hidden="true"> 8</span> ],</span>
<span class="line"><span class="line-number" aria-hidden="true"> 9</span> <span class="pl-s"><span class="pl-pds">"</span>Owner<span class="pl-pds">"</span></span>: {</span>
<span class="line"><span class="line-number" aria-hidden="true">10</span> <span class="pl-s"><span class="pl-pds">"</span>DisplayName<span class="pl-pds">"</span></span>: <span class="pl-s"><span class="pl-pds">"</span>webfile<span class="pl-pds">"</span></span>,</span>
<span class="line"><span class="line-number" aria-hidden="true">11</span> <span class="pl-s"><span class="pl-pds">"</span>ID<span class="pl-pds">"</span></span>: <span class="pl-s"><span class="pl-pds">"</span>bcaf1ffd86f41161ca5fb16fd081034f<span class="pl-pds">"</span></span></span>
<span class="line"><span class="line-number" aria-hidden="true">12</span> }</span>
<span class="line"><span class="line-number" aria-hidden="true">13</span>}</span>
</code></pre>
</div>
Refer to the documentation of fenceparser to learn about the additional ways in which you can specify the information about highlighted lines.
Example: codeblock with a caption
Captions are useful to describe the context of a piece of code.
```sh caption='Configuring the AWS account' prompt{1}
aws configure
AWS Access Key ID [None]: gwen
AWS Secret Access Key [None]: stacy
Default region name [None]: us-east-1
Default output format [None]: json
```
The above codeblock will yield:
<div class="hl hl-sh">
<div class="hl-header">
<div class="hl-language">sh</div>
<div class="hl-caption">Configuring the AWS account</div>
</div>
<pre id="MC45ODEyODAy"><code tabindex="0"><span class="line"><span class="line-number" aria-hidden="true">1</span><span class="line-prompt" aria-hidden="true"></span>aws configure</span>
<span class="line"><span class="line-number" aria-hidden="true">2</span>AWS Access Key ID [None]: gwen</span>
<span class="line"><span class="line-number" aria-hidden="true">3</span>AWS Secret Access Key [None]: stacy</span>
<span class="line"><span class="line-number" aria-hidden="true">4</span>Default region name [None]: us-east-1</span>
<span class="line"><span class="line-number" aria-hidden="true">5</span>Default output format [None]: json</span>
</code></pre>
</div>
Example: aliases
Although Starry Night supports a large number of languages, it is not all encompassing. In such cases, you can configure aliases to force the syntax highlighting on a codeblock containing code in a language not yet supported by Starry Night.
Say we have the following file example.md
:
```xjm
language = "en"
customization = false
features = [ "io", "graphics", "compute" ]
```
You can alias xjm
to toml
as follows with example.js
:
import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import rehypeStringify from "rehype-stringify";
import rehypeStarryNight from "https://esm.sh/@microflash/rehype-starry-night";
main()
async function main() {
const file = await unified()
.use(remarkParse)
.use(remarkRehype, { allowDangerousHtml: true })
.use(rehypeStarryNight, { aliases: { xjm: "toml" } })
.use(rehypeStringify, { allowDangerousHtml: true })
.process(markdown);
console.log(String(file));
}
Running that with node example.js
yields:
<div class="hl hl-toml">
<div class="hl-header">
<div class="hl-language">xjm</div>
</div>
<pre id="MC40OTE3NjA4"><code tabindex="0"><span class="line"><span class="line-number" aria-hidden="true">1</span><span class="pl-smi">language</span> = <span class="pl-s"><span class="pl-pds">"</span>en<span class="pl-pds">"</span></span></span>
<span class="line"><span class="line-number" aria-hidden="true">2</span><span class="pl-smi">customization</span> = <span class="pl-c1">false</span></span>
<span class="line"><span class="line-number" aria-hidden="true">3</span><span class="pl-smi">features</span> = [ <span class="pl-s"><span class="pl-pds">"</span>io<span class="pl-pds">"</span></span>, <span class="pl-s"><span class="pl-pds">"</span>graphics<span class="pl-pds">"</span></span>, <span class="pl-s"><span class="pl-pds">"</span>compute<span class="pl-pds">"</span></span> ]</span>
</code></pre>
</div>
Suppose you want to add a copy to clipboard button in the header. You can do so by adding a custom header extension.
Say we have the following file example.md
:
```html
<mark>highlighted</mark>
```
You can pass a custom header extension as follows with example.js
:
import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import rehypeStringify from "rehype-stringify";
import rehypeStarryNight from "@microflash/rehype-starry-night";
import rehypeStarryNightHeaderCaptionExtension from "@microflash/rehype-starry-night/header-caption-extension";
import rehypeStarryNightHeaderLanguageExtension from "@microflash/rehype-starry-night/header-language-extension";
main()
async function main() {
const file = await unified()
.use(remarkParse)
.use(remarkRehype, { allowDangerousHtml: true })
.use(rehypeStarryNight, {
headerExtensions: [
rehypeStarryNightHeaderLanguageExtension,
rehypeStarryNightHeaderCaptionExtension,
(headerOptions, children) => {
children.push({
type: "element",
tagName: "button",
properties: { className: [`${headerOptions.classNamePrefix}-copy`], for: headerOptions.id },
children: [
{
type: "text",
value: "Copy"
}
]
})
}
]
})
.use(rehypeStringify, { allowDangerousHtml: true })
.process(markdown);
console.log(String(file));
}
Running that with node example.js
yields:
<div class="hl hl-html">
<div class="hl-header">
<div class="hl-language">html</div>
<button class="hl-copy" for="MC40MTUyMDQ4">Copy</button>
</div>
<pre id="MC40MTUyMDQ4"><code tabindex="0"><span class="line"><<span class="pl-ent">mark</span>>highlighted</<span class="pl-ent">mark</span>></span>
</code></pre>
</div>
Example: custom classname prefix
You can attach your own prefix on the classNames of HTML elements generated by the rehype-starry-night
and rehype-starry-night-inline
plugins.
Say we have the following file example.md
:
```java
System.out.println("Hello, world!");
```
You can customize the className prefix as follows with example.js
:
import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import rehypeStringify from "rehype-stringify";
import rehypeStarryNight from "@microflash/rehype-starry-night";
main()
async function main() {
const file = await unified()
.use(remarkParse)
.use(remarkRehype, { allowDangerousHtml: true })
.use(rehypeStarryNight, { classNamePrefix: "syntax" })
.use(rehypeStringify, { allowDangerousHtml: true })
.process(markdown);
console.log(String(file));
}
Running that with node example.js
yields:
<div class="syntax syntax-java">
<div class="syntax-header">
<div class="syntax-language">java</div>
</div>
<pre id="MC42NjM4OTE0"><code tabindex="0"><span class="line"><span class="pl-smi">System</span><span class="pl-k">.</span>out<span class="pl-k">.</span>println(<span class="pl-s"><span class="pl-pds">"</span>Hello, world!<span class="pl-pds">"</span></span>);</span>
</code></pre>
</div>
Similarly for inline code
element, say we have the following file example.md
:
To remove the whitespace around a string, try `java> str.strip()`.
You can customize the className prefix as follows with example.js
:
import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkInlineCodeLang from "@microflash/rehype-starry-night/remark-inline-code-lang";
import remarkRehype from "remark-rehype";
import rehypeStringify from "rehype-stringify";
import rehypeStarryNightInline from "@microflash/rehype-starry-night/rehype-starry-night-inline";
main();
async function main() {
const file = await unified()
.use(remarkParse)
.use(remarkInlineCodeLang)
.use(remarkRehype, { allowDangerousHtml: true })
.use(rehypeStarryNightInline, { classNamePrefix: "syntax" })
.use(rehypeStringify, { allowDangerousHtml: true })
.process(markdown);
console.log(String(file));
}
Running that with node example.js
yields:
<p>To remove the whitespace around a string, try <code class="syntax-inline syntax-java">str<span class="pl-k">.</span>strip()</code>.</p>
Example: custom marker
You can configure a custom marker for inline code
element to inject the language information. For example, say you want to annotate your inline code
element with :
instead of the default >
marker, as shown in the following file example.md
:
To specify the language direction, use `html: <span dir="rtl">مرحبا</span>`.
You can customize the marker as follows with example.js
:
import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkInlineCodeLang from "@microflash/rehype-starry-night/remark-inline-code-lang";
import remarkRehype from "remark-rehype";
import rehypeStringify from "rehype-stringify";
import rehypeStarryNightInline from "@microflash/rehype-starry-night/rehype-starry-night-inline";
main();
async function main() {
const file = await unified()
.use(remarkParse)
.use(remarkInlineCodeLang, { marker: ": " })
.use(remarkRehype, { allowDangerousHtml: true })
.use(rehypeStarryNightInline)
.use(rehypeStringify, { allowDangerousHtml: true })
.process(markdown);
console.log(String(file));
}
Running that with node example.js
yields:
<p>To specify the language direction, use <code class="hl-inline hl-html"><<span class="pl-ent">span</span> <span class="pl-e">dir</span>=<span class="pl-s"><span class="pl-pds">"</span>rtl<span class="pl-pds">"</span></span>>مرحبا</<span class="pl-ent">span</span>></code>.</p>
Related
License
MIT