remark-section-toc

remark plugin to generate section-scoped table of contents (TOC).

• When should I use this?
• Install
• Use
• CLI
• API
  • Options
• Examples
  • Example: maxOffset

When should I use this?

Use remark-section-toc to generate TOCs inside heading sections of your Markdown. This lets you avoid long global TOC, that shifts important content down and forces readers to scroll.

Install

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

npm install -D remark-section-toc

In Deno with esm.sh:

import remarkSectionToc from 'https://esm.sh/remark-section-toc'

In browsers with esm.sh:

<script type="module">
  import remarkSectionToc from 'https://esm.sh/remark-section-toc?bundle'
</script>

Use

Say we have the following file example.md:

# Title

## Section 1

<!--section-toc start-->
<!--section-toc end-->

### Heading 1
### Heading 2
### Heading 3

## Section 2

…and a module example.js:

import {remark} from 'remark'
import remarkSectionToc from 'remark-section-toc'
import {read} from 'to-vfile'

const file = await remark()
  .use(remarkSectionToc)
  .process(await read('example.md'))

console.error(String(file))

…then running node example.js yields:

# Title

## Section 1

<!--section-toc start-->

* [Heading 1](#heading-1)
* [Heading 2](#heading-2)
* [Heading 3](#heading-3)

<!--section-toc end-->

### Heading 1
### Heading 2
### Heading 3

## Section 2

CLI

It’s recommended to use remark-section-toc on the CLI with remark-cli. Install both with npm:

npm install -D remark-cli remark-section-toc

Then run from the terminal:

npx remark README.md --frail -o --use remark-section-toc

Or add a script to package.json:

{
  "scripts": {
    "toc": "remark README.md --frail -o",
  },
  "remarkConfig": {
    "plugins": [
      "remark-section-toc"
    ]
  }
}

Run:

npm run toc

API

This package exports no identifiers. The default export is remarkSectionToc.

unified().use(remarkSectionToc[, options])

Generate section-scoped tables of contents.

Looks for the HTML comments <!-- section-toc start --> and <!-- section-toc end -->, and replaces all between that with a list representing all further headings inside the current section.

Parameters

• options (Options, optional) — configuration

Returns

Transform (Transformer).

Options

Options can be provided in two ways:

• on the plugin level:

  .use(remarkSectionToc, /* options */)

• on the comment level:

  <!-- section-toc start ...options -->
  <!-- section-toc end -->

Fields

• maxOffset (number, default: undefined) — maximum heading depth, relative to the containing section header.
• ...see other fields of remark-toc options

Examples

Example: maxOffset

The option maxOffset can be set to llimit the depth of heading relative to the section heading. For example to include only headings with level=3 inside a section with level=2:

# Title

## Section 1

<!--section-toc start maxOffset=1-->
<!--section-toc end-->

### Heading 1
#### Heading 1.1
### Heading 2
### Heading 3

Output (note Heading 1.1 is omitted):

# Title

## Section 1

<!--section-toc start maxOffset=1-->

* [Heading 1](#heading-1)
* [Heading 2](#heading-2)
* [Heading 3](#heading-3)

<!--section-toc end-->

### Heading 1
#### Heading 1.1
### Heading 2
### Heading 3

Types

This package is fully typed with TypeScript. It exports the additional type Options.

Related

• remark-toc — generate a table of contents.
• remark-validate-links — check that markdown links and images reference existing files and headings.

License

MIT © Vitaliy Potapov