@mdit-vue/plugin-toc

@mdit-vue/plugin-toc

A markdown-it plugin to generate table-of-contents (TOC) that compatible with Vue.js.

This plugin is basically a fork of markdown-it-toc-done-right, with following enhancement:

• Allows html_inline tags in headings to support vue components.
• Supports containerTag, listTag and linkTag.
• Only allows array in level option.
• Code refactor and optimizations.

Install

npm i @mdit-vue/plugin-toc

Usage

import { tocPlugin } from '@mdit-vue/plugin-toc';
import MarkdownIt from 'markdown-it';

const md = MarkdownIt({ html: true }).use(tocPlugin, {
  // options
});

Options

pattern

• Type: RegExp

• Default: /^\[\[toc\]\]$/i

• Details:

  The pattern serving as the TOC placeholder in your markdown.

slugify

• Type: (str: string) => string

• Default: slugify from @mdit-vue/shared

• Details:

  A custom slugification function.

  The default slugify function comes from @mdit-vue/shared package.

  When using this plugin with markdown-it-anchor (recommended), this option will be ignored because the id of the headings have already been determined by markdown-it-anchor's slugify option.

format

• Type: (str: string) => string

• Details:

  A function for formatting headings.

level

• Type: number[]

• Default: [2, 3]

• Details:

  Heading level that going to be included in the TOC.

  When using this plugin with markdown-it-anchor (recommended), this option should be a subset of markdown-it-anchor's level option to ensure the target links are existed.

shouldAllowNested

• Type: boolean

• Default: false

• Details:

  Should allow headers inside nested blocks or not.

  If set to true, headers inside blockquote, list, etc. would also be included.

containerTag

• Type: string

• Default: 'nav'

• Details:

  HTML tag of the TOC container.

containerClass

• Type: string

• Default: 'table-of-contents'

• Details:

  The class for the TOC container.

listTag

• Type: 'ul' | 'ol'

• Default: 'ul'

• Details:

  HTML tag of the TOC list.

listClass

• Type: string

• Default: ''

• Details:

  The class for the TOC list.

itemClass

• Type: string

• Default: ''

• Details:

  The class for the <li> tag.

linkTag

• Type: 'a' | 'router-link'

• Default: 'a'

• Details:

  The tag of the link inside the <li> tag.

  You can set this option to render to links as vue-router's router-link.

linkClass

• Type: string

• Default: ''

• Details:

  The class for the link inside the <li> tag.

Changelog

2.1.3 (2024-05-13)

Note: Version bump only for package @mdit-vue/monorepo