# @mdit-vue/plugin-toc

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

Latest version **3.0.2** (published 2025-08-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install @mdit-vue/plugin-toc
pnpm add @mdit-vue/plugin-toc
yarn add @mdit-vue/plugin-toc
bun add @mdit-vue/plugin-toc
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 3.0.2 |
| Published | 2025-08-11 |
| First published | 2022-06-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20.0.0 |
| Dependencies | 4 |
| Unpacked size | 11.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 221 |
| Author | meteorlxy |
| Maintainers | meteorlxy |
| Keywords | markdown-it, markdown-it-plugin, vue, toc, table-of-contents |

## Links

- npm: https://www.npmjs.com/package/@mdit-vue/plugin-toc
- Repository: https://github.com/mdit-vue/mdit-vue
- Homepage: https://github.com/mdit-vue
- Issues: https://github.com/mdit-vue/mdit-vue/issues
- npm.io page: https://npm.io/package/@mdit-vue/plugin-toc

## Dependencies (4)

- [markdown-it](https://npm.io/package/markdown-it.md) ^14.1.0
- [@mdit-vue/types](https://npm.io/package/@mdit-vue/types.md) 3.0.2
- [@mdit-vue/shared](https://npm.io/package/@mdit-vue/shared.md) 3.0.2
- [@types/markdown-it](https://npm.io/package/@types/markdown-it.md) ^14.1.2

## Alternatives

- [@mdxeditor/editor](https://npm.io/package/@mdxeditor/editor.md) — 962.4K weekly downloads
- [mmdb-lib](https://npm.io/package/mmdb-lib.md) — 680.9K weekly downloads
- [playcanvas](https://npm.io/package/playcanvas.md) — 36.2K weekly downloads
- [@glw907/cairn-cms](https://npm.io/package/@glw907/cairn-cms.md) — 967 weekly downloads
- [markdown-to-confluence](https://npm.io/package/markdown-to-confluence.md) — 103 weekly downloads

## Recent versions

- 3.0.2 (latest) — 2025-08-11
- 3.0.1 — 2025-08-11
- 3.0.0 — 2025-08-11
- 2.1.4 — 2025-04-10
- 2.1.3 — 2024-05-13
- 2.1.2 — 2024-04-15
- 2.1.0 — 2024-04-08
- 2.0.0 — 2023-12-08
- 1.0.0 — 2023-09-26
- 0.12.1 — 2023-08-24
- 0.12.0 — 2023-02-10
- 0.11.2 — 2022-12-23
- 0.11.1 — 2022-08-30
- 0.11.0 — 2022-08-25
- 0.10.0 — 2022-08-23
- … 11 more at https://npm.io/package/@mdit-vue/plugin-toc/versions

## README

# @mdit-vue/plugin-toc

[![npm](https://badgen.net/npm/v/@mdit-vue/plugin-toc)](https://www.npmjs.com/package/@mdit-vue/plugin-toc)
[![license](https://badgen.net/github/license/mdit-vue/mdit-vue)](https://github.com/mdit-vue/mdit-vue/blob/main/LICENSE)

A [markdown-it](https://github.com/markdown-it/markdown-it) plugin to generate table-of-contents (TOC) that compatible with [Vue.js](https://vuejs.org).

This plugin is basically a fork of [markdown-it-toc-done-right](https://github.com/nagaozen/markdown-it-toc-done-right), with following enhancement:

- Allows `html_inline` tags in headings to support vue components.
- Supports [containerTag](#containertag), [listTag](#listtag) and [linkTag](#linktag).
- Only allows array in [level](#level) option.
- Code refactor and optimizations.

## Install

```sh
npm i @mdit-vue/plugin-toc
```

## Usage

```ts
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](https://github.com/mdit-vue/mdit-vue/tree/main/packages/shared) package.

  When using this plugin with [markdown-it-anchor](https://github.com/valeriangalliat/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](https://github.com/valeriangalliat/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](https://router.vuejs.org/guide/#html).

### linkClass

- Type: `string`

- Default: `''`

- Details:

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

---
_Source: https://npm.io/package/@mdit-vue/plugin-toc · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._