rehype-highlight-code-lines

This package is a unified (rehype) plugin that wraps each line of code in a container, enabling code block numbering and line highlighting.

unified is a project that transforms content with abstract syntax trees (ASTs) using the new parser micromark. remark adds support for markdown to unified. mdast is the Markdown Abstract Syntax Tree (AST) which is a specification for representing markdown in a syntax tree. rehype is a tool that transforms HTML with plugins. hast stands for HTML Abstract Syntax Tree (HAST) that rehype uses.

This plugin enables line numbering for code blocks and highlights specific lines as needed.

When should I use this?

The rehype-highlight-code-lines is ideal for adding line numbers to code blocks and highlighting specific lines.

The rehype-highlight-code-lines is NOT code highlighter and does NOT provide code highlighting! You can use a code highlighter for example rehype-highlight to highlight the code, then use the rehype-highlight-code-lines after.

[!IMPORTANT] If the code highlighter already provides numbering and highlighting code lines, don't use rehype-highlight-code-lines!

You can use rehype-highlight-code-lines even without a code highlighter.

Installation

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

1npm install rehype-highlight-code-lines

or

1yarn add rehype-highlight-code-lines

Usage

In a code fence, right after the language of the code block:

• Use curly braces {} to specify a range of line numbers to highlight specific lines.
• Add showLineNumbers to enable line numbering.

```[language] {2,4-6} showLineNumbers

```[language] showLineNumbers {2}

```[language] {1-3}

```[language] showLineNumbers

You can use the specifiers without a language:

```{5} showLineNumbers

```showLineNumbers {5}

```{2,3}

```showLineNumbers

Say we have the following markdown file, example.md:

1```javascript {2} showLineNumbers
2let a1;
3let a2;
4let a3;
5```

I assume you use rehype-highlight for code highlighting. Our module, example.js, looks as follows:

1import { read } from "to-vfile";
2import remark from "remark";
3import gfm from "remark-gfm";
4import remarkRehype from "remark-rehype";
5import rehypeHighlight from "rehype-highlight";
6import rehypeHighlightLines from "rehype-highlight-code-lines";
7import rehypeStringify from "rehype-stringify";
8
9main();
10
11async function main() {
12  const file = await remark()
13    .use(gfm)
14    .use(remarkRehype)
15    .use(rehypeHighlight)
16    .use(rehypeHighlightLines)
17    .use(rehypeStringify)
18    .process(await read("example.md"));
19
20  console.log(String(file));
21}

Now, running node example.js you will see that each line of code is wrapped in a span, which has appropriate class names (code-line, numbered-code-line, highlighted-code-line) and line numbering attribute data-line-number.

1<pre>
2  <code class="hljs language-javascript">
3    <span class="code-line numbered-code-line" data-line-number="1">
4      <span class="hljs-keyword">let</span> a1;
5    </span>
6    <span
7      class="code-line numbered-code-line highlighted-code-line" data-line-number="2">
8      <span class="hljs-keyword">let</span> a2;
9    </span>
10    <span class="code-line numbered-code-line" data-line-number="3">
11      <span class="hljs-keyword">let</span> a3;
12    </span>
13  </code>
14</pre>

Without rehype-highlight-code-lines, the lines of code wouldn't be in a span.

1<pre>
2  <code class="hljs language-javascript">
3    <span class="hljs-keyword">let</span> a1;
4    <span class="hljs-keyword">let</span> a2;
5    <span class="hljs-keyword">let</span> a3;
6  </code>
7</pre>

Note: hljs prefix comes from rehype-highlight.

Usage in HTML attributes

rehype-highlight-code-lines runs on <code> elements with directives like showLineNumbers and range number in curly braces like {2-4,8}. That directives can be passed as a word in markdown (```ts showLineNumbers {2-4,8}) or as a class and attribute in HTML (<code class="language-ts show-line-numbers" data-highlight-lines="2-4,8">).

The inverse occurs when the option showLineNumbers is true. All <code> are processed and numbered. Then (```ts noLineNumbers), or as a class (<code class="language-ts no-line-numbers">) can be used to prevent processing.

The class directives can be with dash or without, or camel cased.

See some example usage as HTML class and attributes (only opening <code> tags are provided, the rest is omitted.):

1<code class="language-typescript show-line-numbers">
2<code class="language-typescript showlinenumbers">
3<code class="language-typescript showLineNumbers">
4
5<code class="language-typescript show-line-numbers" data-highlight-lines="2-4">
6<code class="language-typescript show-line-numbers" data-start-numbering="11">
7<code class="language-typescript show-line-numbers" data-start-numbering="11" data-highlight-lines="2-4">
8
9<code class="language-typescript no-line-numbers">
10<code class="language-typescript nolinenumbers">
11<code class="language-typescript noLineNumbers">
12<code class="language-typescript no-line-numbers" data-highlight-lines="2-4">
13
14<code class="no-line-numbers">
15<code class="show-line-numbers">
16<code class="show-line-numbers" data-highlight-lines="2-4">
17<code data-highlight-lines="2-4">
18<code data-start-numbering="11">

Say we have the following HTML fragment in a example.md:

1<pre><code class="language-javascript show-line-numbers" data-highlight-lines="2">
2let a1;
3let a2;
4let a3;
5</code></pre>

I assume you use rehype-highlight for code highlighting. Our module, example.js, looks as follows:

1import { read } from "to-vfile";
2import remarkParse from "remark-parse";
3import remarkRehype from "remark-rehype";
4import rehypeRaw from "rehype-raw";
5import rehypeHighlight from "rehype-highlight";
6import rehypeHighlightLines from "rehype-highlight-code-lines";
7import rehypeStringify from "rehype-stringify";
8
9main();
10
11async function main() {
12  const file = await unified()
13    .use(remarkParse)
14    .use(remarkRehype, { allowDangerousHtml: true })
15    .use(rehypeRaw)
16    .use(rehypeHighlight)
17    .use(rehypeHighlightLines)
18    .use(rehypeStringify)
19    .process(await read("example.md"));
20
21  console.log(String(file));
22}

Now, running node example.js you will see that each line of code is wrapped in a span, which has appropriate class names (code-line, numbered-code-line, highlighted-code-line) and line numbering attribute data-line-number.

1<pre>
2  <code class="hljs language-javascript">
3    <span class="code-line numbered-code-line" data-line-number="1">
4      <span class="hljs-keyword">let</span> a1;
5    </span>
6    <span
7      class="code-line numbered-code-line highlighted-code-line" data-line-number="2">
8      <span class="hljs-keyword">let</span> a2;
9    </span>
10    <span class="code-line numbered-code-line" data-line-number="3">
11      <span class="hljs-keyword">let</span> a3;
12    </span>
13  </code>
14</pre>

Options

All options are optional and have default values.

1type HighlightLinesOptions = {
2  showLineNumbers?: boolean; // default is "false"
3  lineContainerTagName?: "span" | "div"; // deprecated, always span
4};
5
6use(rehypeHighlightLines, HighlightLinesOptions);

showLineNumbers

It is a boolean option which is for all code to be numbered.

By default, it is false.

1use(rehypeHighlightLines, {
2  showLineNumbers: true,
3});

Now, all code blocks will become numbered.

If you want to exclude a specific code block not to be numbered, use noLineNumbers.

```[language] noLineNumbers {2}

```[language] noLineNumbers

```noLineNumbers

If you want to exclude a specific code block not to be numbered in HTML fragment (in <pre>) use no-line-numbers class. In that case, the directive could be with dash, or without, or camel cased.

<code class="language-ts no-line-numbers">

<code class="language-ts nolinenumbers">

<code class="language-ts noLineNumbers">

Sometimes you may want to start the line numbering from a specific number. In that cases, use showLineNumbers=[number] in code blocks. For example, below, the code block's line numbering will start from number 8.

```[language] {2} showLineNumbers=8

```[language] showLineNumbers=8

```showLineNumbers=8

If you want to start the line numbering from a specific number in HTML fragment (in <pre>) use data-start-numbering attribute.

<code class="..." data-start-numbering="8">

lineContainerTagName (Deprecated)

It is marked as @deprecated and will be removed in the next versions.

It was a union option which was "div" | "span" for providing custom HTML tag name for code lines.

By default, it is span which is inline level container. If you set it as div, the container will still be span after deprecation.

1use(rehypeHighlightLines, {
2  lineContainerTagName: "div", // @deprecated, effectless, always "span"
3});

Examples:

1// line numbering will occur as per directive "showLineNumber" and code-line containers will be <span> inline element
2use(rehypeHighlightLines);
3
4// all code blocks will be numbered by default and code-line containers will be <span> inline element
5use(rehypeHighlightLines, {
6  showLineNumbers: true,
7});

An example screen snapshot from a working app:

Here you can find some demo applications below which the rehype-highlight and rehype-highlight-code-lines are used together:

• demo blog application using next-mdx-remote-client within Next.js app router
• demo blog application using next-mdx-remote-client within Next.js pages router

Styling

The following styles can be added for line highlighting and line numbering to work correctly:

Choose the colors as you wish!

1.parent-container-of-pre {
2  display: grid; /* in order { overflow-x: auto; } works in child <pre> */
3}
4
5pre,
6pre code {
7  background-color: var(--color-code-background);
8
9  direction: ltr;
10  text-align: left;
11  white-space: pre;
12  word-spacing: normal;
13  word-break: normal;
14  line-height: 1.2;
15  tab-size: 2;
16  hyphens: none;
17}
18
19pre {
20  padding: 0.5rem 1rem;
21  border: 1px solid var(--color-text-weak);
22  border-radius: 5px;
23
24  overflow-x: auto;
25}
26
27pre > code {
28  float: left;
29  min-width: 100%;
30}
31
32.code-line {
33  min-width: 100%;
34  padding-left: 12px;
35  padding-right: 12px;
36  margin-left: -12px;
37  margin-right: -12px;
38  border-left: 4px solid transparent; /* prepare for highlighted code-lines */
39
40  display: inline-block;
41}
42
43.code-line.inserted {
44  background-color: var(--color-inserted-line); /* inserted code-line (+) */
45}
46
47.code-line.deleted {
48  background-color: var(--color-deleted-line); /* deleted code-line (-) */
49}
50
51.highlighted-code-line {
52  background-color: var(--color-highlighted-line);
53  border-left: 4px solid var(--color-highlighted-line-indicator);
54}
55
56.numbered-code-line::before {
57  content: attr(data-line-number);
58
59  margin-left: -8px;
60  margin-right: 16px;
61  width: 1rem;
62  color: var(--color-text-weak);
63  text-align: right;
64
65  display: inline-block;
66}

Syntax tree

This plugin modifies the hast (HTML abstract syntax tree).

Types

This package is fully typed with TypeScript.

The plugin exports the type HighlightLinesOptions.

Compatibility

This plugin works with rehype-parse version 1+, rehype-stringify version 1+, rehype version 1+, and unified version 4+.

Security

Use of rehype-highlight-code-lines involves rehype (hast), but doesn't lead to cross-site scripting (XSS) attacks.

My Plugins

I like to contribute the Unified / Remark / MDX ecosystem, so I recommend you to have a look my plugins.

My Remark Plugins

• remark-flexible-code-titles – Remark plugin to add titles or/and containers for the code blocks with customizable properties
• remark-flexible-containers – Remark plugin to add custom containers with customizable properties in markdown
• remark-ins – Remark plugin to add ins element in markdown
• remark-flexible-paragraphs – Remark plugin to add custom paragraphs with customizable properties in markdown
• remark-flexible-markers – Remark plugin to add custom mark element with customizable properties in markdown
• remark-flexible-toc – Remark plugin to expose the table of contents via vfile.data or via an option reference
• remark-mdx-remove-esm – Remark plugin to remove import and/or export statements (mdxjsEsm)

My Rehype Plugins

• rehype-pre-language – Rehype plugin to add language information as a property to pre element
• rehype-highlight-code-lines – Rehype plugin to add line numbers to code blocks and allow highlighting of desired code lines
• rehype-code-meta – Rehype plugin to copy code.data.meta to code.properties.metastring
• rehype-image-toolkit – Rehype plugin to enhance Markdown image syntax ![]() and Markdown/MDX media elements (<img>, <audio>, <video>) by auto-linking bracketed or parenthesized image URLs, wrapping them in <figure> with optional captions, unwrapping images/videos/audio from paragraph, parsing directives in title for styling and adding attributes, and dynamically converting images into <video> or <audio> elements based on file extension.

My Recma Plugins

• recma-mdx-escape-missing-components – Recma plugin to set the default value () => null for the Components in MDX in case of missing or not provided so as not to throw an error
• recma-mdx-change-props – Recma plugin to change the props parameter into the _props in the function _createMdxContent(props) {/* */} in the compiled source in order to be able to use {props.foo} like expressions. It is useful for the next-mdx-remote or next-mdx-remote-client users in nextjs applications.
• recma-mdx-change-imports – Recma plugin to convert import declarations for assets and media with relative links into variable declarations with string URLs, enabling direct asset URL resolution in compiled MDX.
• recma-mdx-import-media – Recma plugin to turn media relative paths into import declarations for both markdown and html syntax in MDX.
• recma-mdx-import-react – Recma plugin to ensure getting React instance from the arguments and to make the runtime props {React, jsx, jsxs, jsxDev, Fragment} is available in the dynamically imported components in the compiled source of MDX.
• recma-mdx-html-override – Recma plugin to allow selected raw HTML elements to be overridden via MDX components.
• recma-mdx-interpolate – Recma plugin to enable interpolation of identifiers wrapped in curly braces within the alt, src, href, and title attributes of markdown link and image syntax in MDX.

License

MIT License © ipikuka