Table of Contents in Gatsby

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)