Deep Dive

“The fastest auto dealership site in the world” Hundreds of hours of perf learnings, distilled

ContactSign Up for Free
Community Plugin
View plugin on GitHub

Table of Contents in Gatsby

Downloads Lines

Gatsby plugin using remark to generate a Table of Contents in markdown.

Installation

Requirements

This plugin requires gatsby-remark-autolink-headers to generate the anchor links.

npm i --save gatsby-remark-autolink-headers

Install gatsby-remark-table-of-contents

npm i --save gatsby-remark-table-of-contents

Global Configuration

Global configurations should be set in gatsby-config.js.

module.exports = ({ root }) => ({
  plugins: [
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        plugins: [
          {
            resolve: `gatsby-remark-table-of-contents`,
            options: {
              exclude: "Table of Contents",
              tight: false,
              ordered: false,
              fromHeading: 1,
              toHeading: 6,
              className: "table-of-contents"
            },
          },
          `gatsby-remark-autolink-headers`
        ],
      },
    },
  ],
})

Use

Generate a table of contents:

```toc
# This code block gets replaced with the TOC
```

If you like to overwrite the global settings in place (camelCase or kebab-case):

```toc
# This code block gets replaced with the TOC
exclude: Table of Contents
tight: false
ordered: false
from-heading: 2
to-heading: 6
class-name: "table-of-contents"
```

Options

exclude

string? | array? — default: ''
Exclude titles matching this string (new RegExp('^(' + string + ')$', 'i')). If an array is passed the array gets joined with a pipe (new RegExp('^(' + array.join('|') + ')$', 'i')).

tight

boolean? — default: false
Tight list items.

ordered

boolean? — default: false
Creates an ordered list.

fromHeading

number? — default: 2
Minimum heading depth to include.

toHeading

number? — default: 6
Maximum heading depth to include.

className

string? — default: toc
Set the class-name of the generated div.

Example

Input

# Headline 1.0.0

## Table of Contents

```toc
exclude: Table of Contents
from-heading: 2
to-heading: 6
```

## Headline 1.1.0

### Headline 1.1.1

## Headline 1.2.0

Output

# Headline 1.0.0

## Table of Contents

-   [Headline 1.1.0](#headline-110)

    -   [Headline 1.1.1](#headline-111)

-   [Headline 1.2.0](#headline-120)

## Headline 1.1.0

### Headline 1.1.1

## Headline 1.2.0

License & Authors

MIT · Started by signalwerk supported by several contributors

Version

  • 1.0.0 – FIX: Bugfix when JSX/MDX is used (author: @zeropaper)
  • 0.2.0 – ADD: Option to set ordered (author: @thomasjungblut)
  • 0.1.0 – ADD: Option to set Class-Name (author: @panzerdp)
  • 0.0.9 – ADD: Multiple excludes can now be defined by arrays (author: @signalwerk)
  • 0.0.1 – Initial release (author: @signalwerk)
© 2022 Gatsby, Inc.