toc

@vuepress/plugin-toc

This plugin will provide a table-of-contents (TOC) component.

Differences with Markdown TOC Syntax

Similar to the Table of Contents Markdown Syntax, the TOC component that provided by this plugin could be used in your markdown content directly:

<!-- markdown toc syntax -->
[[toc]]

<!-- vue toc component -->
<Toc />
1
2
3
4
5

Both of them can be pre-rendered correctly in build mode. However, there are some differences between them.

The markdown syntax [[toc]] could only be used in markdown files. It is parsed by markdown-it, and the generated TOC is static content.

The component <Toc/> could be used in both markdown files and vue files. It is loaded by vue, and the generated TOC is a vue component.

This plugin could work together with @vuepress/plugin-active-header-links by setting the headerLinkSelector to match the linkClass option. When the page scroll to a certain header anchor, this corresponding link will be added linkActiveClass class name.

Therefore, this plugin is more useful for theme developers.

Options

componentName

  • Type: string

  • Default: Toc

  • Details:

    Specify the name of the TOC component.

defaultPropsOptions

  • Type: Partial<TocPropsOptions>

  • Default: {}

  • Details:

    Override the default values of the component options prop.

Component Props

The TOC component also accepts props for customization.

<template>
  <Toc :headers="headers" :options="options" />
</template>
1
2
3

headers

  • Type: PageHeader[]
interface PageHeader {
  level: number
  title: string
  slug: string
  children: PageHeader[]
}
1
2
3
4
5
6
  • Details:

    Specify the headers array to render.

    If this prop is not specified, the headers of current page will be used.

options

  • Type: Partial<TocPropsOptions>
interface TocPropsOptions {
  containerTag: string
  containerClass: string
  listClass: string
  itemClass: string
  linkTag: 'a' | 'RouterLink'
  linkClass: string
  linkActiveClass: string
  linkChildrenActiveClass: string
}
1
2
3
4
5
6
7
8
9
10
const defaultOptions = {
  containerTag: 'nav',
  containerClass: 'vuepress-toc',
  listClass: 'vuepress-toc-list',
  itemClass: 'vuepress-toc-item',
  linkTag: 'RouterLink',
  linkClass: 'vuepress-toc-link',
  linkActiveClass: 'active',
  linkChildrenActiveClass: 'active',
}
1
2
3
4
5
6
7
8
9
10
  • Details:

    Customize the TOC component.

    If the containerTag is set to an empty string '', the <nav> container will be removed totally.

  • Example:

    The rendered TOC component with default options looks like:

<template>
  <!-- container -->
  <nav class="vuepress-toc">
    <!-- list -->
    <ul class="vuepress-toc-list">
      <!-- item -->
      <li class="vuepress-toc-item">
        <!-- link -->
        <RouterLink class="vuepress-toc-link" to="#foo">Foo</RouterLink>
      </li>
      <!-- item with children -->
      <li class="vuepress-toc-item">
        <!-- link (children active) -->
        <RouterLink class="vuepress-toc-link active" to="#bar">Bar</RouterLink>
        <!-- list (children) -->
        <ul class="vuepress-toc-list">
          <!-- item -->
          <li class="vuepress-toc-item">
            <!-- link (active) -->
            <RouterLink class="vuepress-toc-link active" to="#bar-child">Bar Child</RouterLink>
          </li>
        </ul>
      </li>
    </ul>
  </nav>
</template>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26