Table of contents

Build a nested table of contents from document headings.

The comark/plugins/toc plugin generates a hierarchical table of contents from document headings and stores it in tree.meta.toc. Headings h2 through h6 are included; h1 is always excluded.

Usage

import { parseMarkdown } from 'comark'
import toc from 'comark/plugins/toc'

const result = await parseMarkdown(content, {
  plugins: [toc()]
})

console.log(result.meta.toc) // Toc

API

toc(options?)

Returns a ComarkPlugin that generates a hierarchical TOC from headings.

Parameters:

  • options?: Optional configuration. See Options.

Returns: ComarkPlugin

The result is stored at tree.meta.toc:

interface Toc {
  title: string       // TOC title (from the `title` option)
  depth: number       // Maximum heading depth included
  searchDepth: number // Search depth in nested structures
  links: TocLink[]    // Hierarchical list of links
}

interface TocLink {
  id: string           // Heading ID for anchor links
  text: string         // Heading text
  depth: number        // Heading level (2 to 6)
  children?: TocLink[] // Nested child headings
}

Options

OptionTypeDefaultDescription
depthnumber2Number of heading levels below h1 to include (1 for h2, 2 for h2 through h3, up to 5 for h2 through h6)
searchDepthnumber2How deep to search for headings in nested component structures
titlestring''Title field on the returned Toc

depth

Controls how many heading levels to include, starting at h2: 1 includes h2 only, 2 includes h2 through h3, 3 includes h2 through h4, up to 5 for h2 through h6.

toc({ depth: 3 }) // include h2, h3, and h4

Default: 2

searchDepth

Controls how deep to search for headings in nested component structures. Increase when headings are inside components or containers.

toc({ searchDepth: 3 })

Default: 2

title

Sets the title field on the returned Toc. Has no effect on rendering; use it to label the TOC in your layout component.

toc({ title: 'On This Page' })

Default: ''


Examples

Basic TOC generation

import { parseMarkdown } from 'comark'
import toc from 'comark/plugins/toc'

const content = `## Introduction

## Features

### Performance
### Flexibility

## Conclusion
`

const result = await parseMarkdown(content, { plugins: [toc()] })
console.log(result.meta.toc)

Docs layout

Parse once to get the TOC, then render it alongside the <Markdown> component:

<script setup lang="ts">
import { parseMarkdown } from 'comark'
import { Markdown } from '@comark/vue'
import toc from '@comark/vue/plugins/toc'

const props = defineProps<{ content: string }>()

const plugins = [toc({ depth: 3 })]
const result = await parseMarkdown(props.content, { plugins })
const tocData = result.meta.toc
</script>

<template>
  <div class="docs-layout">
    <aside>
      <h2>{{ tocData.title || 'On This Page' }}</h2>
      <nav>
        <ul>
          <li v-for="link in tocData.links" :key="link.id">
            <a :href="`#${link.id}`">{{ link.text }}</a>
            <ul v-if="link.children">
              <li v-for="child in link.children" :key="child.id">
                <a :href="`#${child.id}`">{{ child.text }}</a>
              </li>
            </ul>
          </li>
        </ul>
      </nav>
    </aside>
    <main>
      <Markdown :plugins="plugins">{{ props.content }}</Markdown>
    </main>
  </div>
</template>
For deeper heading trees, render link.children recursively with a TocLink component that renders itself for each child.
© 2026 Vercel, Inc.