toc

@vuepress/plugin-toc

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

Usage

npm i -D @vuepress/plugin-toc@next
.vuepress/config.ts
import { tocPlugin } from '@vuepress/plugin-toc'

export default {
  plugins: [
    tocPlugin({
      // options
    }),
  ],
}

Differences with Markdown TOC Syntax

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

<!-- markdown toc syntax -->

[[toc]]

<!-- vue toc component -->
<Toc />

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

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

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

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

Therefore, this plugin is more useful for theme developers.

Options

componentNamestring
Default'Toc'

Specify the name of the TOC component.

headersOptionsGetHeadersOptions
Default{}

Override the default values of the component headersOptions prop.

renderOptionsTocRenderOptions
Default{}

Override the default values of the component renderOptions prop.

Component Props

The TOC component also accepts props for customization.

<template>
  <Toc
    :headers="headers"
    :headers-options="headersOptions"
    :render-options="renderOptions"
  />
</template>
headersPageHeader[]

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

headers[*].levelnumber

The level of the header.

headers[*].titlestring

The title of the header.

headers[*].slugstring

The slug of the header.

headers[*].childrenPageHeader[]

The children headers.

headersOptionsGetHeadersOptions

Customize header extracting behavior.

See GetHeadersOptions for the available options. It can be overridden by the headersOptions option in plugin options.

renderOptionsTocRenderOptions

Customize TOC component render behavior. It can be overridden by the renderOptions option in plugin options.

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 -->
        <RouteLink class="vuepress-toc-link" to="#foo">Foo</RouteLink>
      </li>
      <!-- item with children -->
      <li class="vuepress-toc-item">
        <!-- link (children active) -->
        <RouteLink class="vuepress-toc-link active" to="#bar">Bar</RouteLink>
        <!-- list (children) -->
        <ul class="vuepress-toc-list">
          <!-- item -->
          <li class="vuepress-toc-item">
            <!-- link (active) -->
            <RouteLink class="vuepress-toc-link active" to="#bar-child">
              Bar Child
            </RouteLink>
          </li>
        </ul>
      </li>
    </ul>
  </nav>
</template>
renderOptions.containerTagstring
Default'nav'

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

renderOptions.containerClassstring
Default'vuepress-toc'

Container class name.

renderOptions.listClassstring
Default'vuepress-toc-list'

List class name.

renderOptions.itemClassstring
Default'vuepress-toc-item'

Item class name.

renderOptions.linkTag'a' | 'RouteLink' | 'RouterLink'
Default'RouteLink'

Link tag type.

renderOptions.linkClassstring
Default'vuepress-toc-link'

Link class name.

renderOptions.linkActiveClassstring
Default'active'

Active link class name.

renderOptions.linkChildrenActiveClassstring
Default'active'

Active children link class name.