​

Auto TOC Plugin

​

Features

• Automatic Insertion - No manual TOC creation needed
• Smart Placement - Inserts before the first H2 heading
• Internationalized - TOC title respects your locale settings
• Styled Component - Uses built-in <Toc> component

​

How It Works

1. Scans the markdown AST for the first ## Heading (depth 2)
2. Inserts a TOC section before that heading
3. Uses the useTranslation hook for the “Table of Contents” title
4. Renders the built-in <Toc> component

​

Configuration

export const autoTocPlugin = (): RspressPlugin => {
  return {
    name: 'doom-auto-toc',
    markdown: {
      remarkPlugins: [remarkAutoToc],
    },
  }
}

​

Implementation

export const remarkAutoToc: Plugin<[], Root> = function () {
  return (root) => {
    let foundIndex = -1

    for (const [index, node] of root.children.entries()) {
      if (node.type === 'heading' && node.depth === 2) {
        foundIndex = index
        break
      }
    }

    if (foundIndex === -1) {
      return
    }
    // ... inserts TOC
  }
}

​

Generated Output

# Page Title

Introduction text.

## First Section

Content...

## Second Section

More content...

# Page Title

Introduction text.

<div className="doom-auto-toc rp-toc-exclude">
  <h2>{useTranslation()('toc')} {#toc}</h2>
  <Toc />
</div>

## First Section

Content...

​

Customization

​

Excluding from Rspress TOC

​

Translation

en:
  toc: "Table of Contents"
zh:
  toc: "目录"

​

Styling

.doom-auto-toc {
  margin: 2rem 0;
  padding: 1rem;
  border: 1px solid var(--rp-c-divider);
  border-radius: 8px;
}

​

When TOC is Not Generated

• No ## Heading (H2) is found in the page
• The page only has H1 or H3+ headings
• The page is too short to warrant a TOC

​

Disabling Auto TOC

1. Use only H1 headings - The plugin requires an H2 to trigger
2. Remove the plugin - Comment it out in your config:

export default defineConfig({
  plugins: [
    // autoTocPlugin(),  // Disabled
  ]
})

3. Create a custom plugin - Override the behavior for specific routes

​

Manual TOC

import { Toc } from '@rspress/runtime'

# My Page

<Toc />

## Section 1

​

Best Practices

1. Use H2 for Major Sections - The plugin triggers on the first H2
2. Consistent Heading Hierarchy - Follow H1 → H2 → H3 order
3. Descriptive Headings - Headings appear in the TOC, make them clear
4. Not Too Many Headings - Keep TOC manageable (5-10 items ideal)

​

Integration with Rspress

• Auto TOC - In-page TOC before content
• Sidebar TOC - Right sidebar navigation

​

Related

• Auto Sidebar Plugin
• Directives Plugin
• Creating Plugins