@mdit-vue/plugin-toc 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [0.3.0](https://github.com/mdit-vue/mdit-vue/compare/v0.2.0...v0.3.0) (2022-06-25)
+
+### Features
+
+- **plugin-toc:** add toc plugin ([e64cc2c](https://github.com/mdit-vue/mdit-vue/commit/e64cc2ce3bbc89999d373f8a00fb3a049d6af58f))

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022-present, mdit-vue Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# @mdit-vue/plugin-toc
+
+[![npm](https://badgen.net/npm/v/@mdit-vue/plugin-toc)](https://www.npmjs.com/package/@mdit-vue/plugin-toc)
+
+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 MarkdownIt from 'markdown-it';
+import { tocPlugin } from '@mdit-vue/plugin-toc';
+
+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.
+
+### 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.

package/build.config.ts

@@ -0,0 +1,11 @@
+import { defineBuildConfig } from 'unbuild';
+
+export default defineBuildConfig({
+  clean: true,
+  declaration: true,
+  entries: ['src/index'],
+  rollup: {
+    emitCJS: true,
+    inlineDependencies: false,
+  },
+});

package/dist/index.cjs

@@ -0,0 +1,107 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+const shared = require('@mdit-vue/shared');
+
+const createRenderHeaders = ({
+  listTag,
+  listClass,
+  itemClass,
+  linkTag,
+  linkClass
+}) => {
+  const listTagString = shared.htmlEscape(listTag);
+  const listClassString = listClass ? ` class="${shared.htmlEscape(listClass)}"` : "";
+  const itemTagString = "li";
+  const itemClassString = itemClass ? ` class="${shared.htmlEscape(itemClass)}"` : "";
+  const linkTagString = shared.htmlEscape(linkTag);
+  const linkClassString = linkClass ? ` class="${shared.htmlEscape(linkClass)}"` : "";
+  const linkTo = (slug) => linkTag === "router-link" ? ` to="#${slug}"` : ` href="#${slug}"`;
+  const renderHeaders = (headers) => `<${listTagString}${listClassString}>${headers.map((header) => `<${itemTagString}${itemClassString}${itemClassString}><${linkTagString}${linkClassString}${linkTo(header.slug)}>${header.title}</${linkTagString}>${header.children.length > 0 ? renderHeaders(header.children) : ""}</${itemTagString}>`).join("")}</${listTagString}>`;
+  return renderHeaders;
+};
+
+const createTocBlockRule = ({
+  pattern,
+  containerTag,
+  containerClass
+}) => {
+  return (state, startLine, endLine, silent) => {
+    if (state.sCount[startLine] - state.blkIndent >= 4) {
+      return false;
+    }
+    const pos = state.bMarks[startLine] + state.tShift[startLine];
+    const max = state.eMarks[startLine];
+    const lineFirstToken = state.src.slice(pos, max).split(" ")[0];
+    if (!pattern.test(lineFirstToken))
+      return false;
+    if (silent)
+      return true;
+    state.line = startLine + 1;
+    const tokenOpen = state.push("toc_open", containerTag, 1);
+    tokenOpen.markup = "";
+    tokenOpen.map = [startLine, state.line];
+    if (containerClass) {
+      tokenOpen.attrSet("class", containerClass);
+    }
+    const tokenBody = state.push("toc_body", "", 0);
+    tokenBody.markup = lineFirstToken;
+    tokenBody.map = [startLine, state.line];
+    tokenBody.hidden = true;
+    const tokenClose = state.push("toc_close", containerTag, -1);
+    tokenClose.markup = "";
+    tokenBody.map = [startLine, state.line];
+    return true;
+  };
+};
+
+const tocPlugin = (md, {
+  pattern = /^\[\[toc\]\]$/i,
+  slugify = shared.slugify,
+  format,
+  level = [2, 3],
+  containerTag = "nav",
+  containerClass = "table-of-contents",
+  listTag = "ul",
+  listClass = "",
+  itemClass = "",
+  linkTag = "a",
+  linkClass = ""
+} = {}) => {
+  let headers;
+  md.core.ruler.push("resolveTocHeaders", (state) => {
+    headers = shared.resolveHeadersFromTokens(state.tokens, {
+      level,
+      shouldAllowHtml: true,
+      shouldEscapeText: true,
+      slugify,
+      format
+    });
+    return true;
+  });
+  md.block.ruler.before("heading", "toc", createTocBlockRule({
+    pattern,
+    containerTag,
+    containerClass
+  }), {
+    alt: ["paragraph", "reference", "blockquote"]
+  });
+  const renderHeaders = createRenderHeaders({
+    listTag,
+    listClass,
+    itemClass,
+    linkTag,
+    linkClass
+  });
+  md.renderer.rules.toc_body = () => {
+    if (!headers) {
+      return "";
+    }
+    return renderHeaders(headers);
+  };
+};
+
+exports.createRenderHeaders = createRenderHeaders;
+exports.createTocBlockRule = createTocBlockRule;
+exports.tocPlugin = tocPlugin;

package/dist/index.d.ts

@@ -0,0 +1,83 @@
+import { MarkdownItHeader } from '@mdit-vue/shared';
+import { RuleBlock } from 'markdown-it/lib/parser_block';
+import { PluginWithOptions } from 'markdown-it';
+
+/**
+ * Options of @mdit-vue/plugin-toc
+ */
+interface TocPluginOptions {
+    /**
+     * The pattern serving as the TOC placeholder in your markdown
+     */
+    pattern?: RegExp;
+    /**
+     * A custom slugification function
+     *
+     * Should use the same slugify function with markdown-it-anchor
+     * to ensure the link is matched
+     */
+    slugify?: (str: string) => string;
+    /**
+     * A function for formatting headings
+     */
+    format?: (str: string) => string;
+    /**
+     * Heading level that going to be included in the TOC
+     *
+     * Should be a subset of markdown-it-anchor's `level` option
+     * to ensure the link is existed
+     */
+    level?: number[];
+    /**
+     * HTML tag of the TOC container
+     */
+    containerTag?: string;
+    /**
+     * The class for the TOC container
+     */
+    containerClass?: string;
+    /**
+     * HTML tag of the TOC list
+     */
+    listTag?: 'ul' | 'ol';
+    /**
+     * The class for the TOC list
+     */
+    listClass?: string;
+    /**
+     * The class for the `<li>` tag
+     */
+    itemClass?: string;
+    /**
+     * The tag of the link inside `<li>` tag
+     */
+    linkTag?: 'a' | 'router-link';
+    /**
+     * The class for the link inside the `<li>` tag
+     */
+    linkClass?: string;
+}
+
+declare type RenderHeadersFn = (headers: MarkdownItHeader[]) => string;
+declare const createRenderHeaders: ({ listTag, listClass, itemClass, linkTag, linkClass, }: Pick<Required<TocPluginOptions>, 'listTag' | 'listClass' | 'itemClass' | 'linkTag' | 'linkClass'>) => RenderHeadersFn;
+
+/**
+ * Forked and modified from markdown-it-toc-done-right
+ *
+ * - remove the `inlineOptions` support
+ * - use markdown-it default renderer to render token whenever possible
+ *
+ * @see https://github.com/nagaozen/markdown-it-toc-done-right
+ */
+declare const createTocBlockRule: ({ pattern, containerTag, containerClass, }: Pick<Required<TocPluginOptions>, 'pattern' | 'containerTag' | 'containerClass'>) => RuleBlock;
+
+/**
+ * Generate table of contents
+ *
+ * Forked and modified from markdown-it-toc-done-right:
+ *
+ * @see https://github.com/nagaozen/markdown-it-toc-done-right
+ */
+declare const tocPlugin: PluginWithOptions<TocPluginOptions>;
+
+export { createRenderHeaders, createTocBlockRule, tocPlugin };

package/dist/index.mjs

@@ -0,0 +1,101 @@
+import { htmlEscape, resolveHeadersFromTokens, slugify } from '@mdit-vue/shared';
+
+const createRenderHeaders = ({
+  listTag,
+  listClass,
+  itemClass,
+  linkTag,
+  linkClass
+}) => {
+  const listTagString = htmlEscape(listTag);
+  const listClassString = listClass ? ` class="${htmlEscape(listClass)}"` : "";
+  const itemTagString = "li";
+  const itemClassString = itemClass ? ` class="${htmlEscape(itemClass)}"` : "";
+  const linkTagString = htmlEscape(linkTag);
+  const linkClassString = linkClass ? ` class="${htmlEscape(linkClass)}"` : "";
+  const linkTo = (slug) => linkTag === "router-link" ? ` to="#${slug}"` : ` href="#${slug}"`;
+  const renderHeaders = (headers) => `<${listTagString}${listClassString}>${headers.map((header) => `<${itemTagString}${itemClassString}${itemClassString}><${linkTagString}${linkClassString}${linkTo(header.slug)}>${header.title}</${linkTagString}>${header.children.length > 0 ? renderHeaders(header.children) : ""}</${itemTagString}>`).join("")}</${listTagString}>`;
+  return renderHeaders;
+};
+
+const createTocBlockRule = ({
+  pattern,
+  containerTag,
+  containerClass
+}) => {
+  return (state, startLine, endLine, silent) => {
+    if (state.sCount[startLine] - state.blkIndent >= 4) {
+      return false;
+    }
+    const pos = state.bMarks[startLine] + state.tShift[startLine];
+    const max = state.eMarks[startLine];
+    const lineFirstToken = state.src.slice(pos, max).split(" ")[0];
+    if (!pattern.test(lineFirstToken))
+      return false;
+    if (silent)
+      return true;
+    state.line = startLine + 1;
+    const tokenOpen = state.push("toc_open", containerTag, 1);
+    tokenOpen.markup = "";
+    tokenOpen.map = [startLine, state.line];
+    if (containerClass) {
+      tokenOpen.attrSet("class", containerClass);
+    }
+    const tokenBody = state.push("toc_body", "", 0);
+    tokenBody.markup = lineFirstToken;
+    tokenBody.map = [startLine, state.line];
+    tokenBody.hidden = true;
+    const tokenClose = state.push("toc_close", containerTag, -1);
+    tokenClose.markup = "";
+    tokenBody.map = [startLine, state.line];
+    return true;
+  };
+};
+
+const tocPlugin = (md, {
+  pattern = /^\[\[toc\]\]$/i,
+  slugify: slugify$1 = slugify,
+  format,
+  level = [2, 3],
+  containerTag = "nav",
+  containerClass = "table-of-contents",
+  listTag = "ul",
+  listClass = "",
+  itemClass = "",
+  linkTag = "a",
+  linkClass = ""
+} = {}) => {
+  let headers;
+  md.core.ruler.push("resolveTocHeaders", (state) => {
+    headers = resolveHeadersFromTokens(state.tokens, {
+      level,
+      shouldAllowHtml: true,
+      shouldEscapeText: true,
+      slugify: slugify$1,
+      format
+    });
+    return true;
+  });
+  md.block.ruler.before("heading", "toc", createTocBlockRule({
+    pattern,
+    containerTag,
+    containerClass
+  }), {
+    alt: ["paragraph", "reference", "blockquote"]
+  });
+  const renderHeaders = createRenderHeaders({
+    listTag,
+    listClass,
+    itemClass,
+    linkTag,
+    linkClass
+  });
+  md.renderer.rules.toc_body = () => {
+    if (!headers) {
+      return "";
+    }
+    return renderHeaders(headers);
+  };
+};
+
+export { createRenderHeaders, createTocBlockRule, tocPlugin };

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@mdit-vue/plugin-toc",
+  "version": "0.3.0",
+  "description": "A markdown-it plugin to generate table-of-contents that compatible with Vue.js",
+  "keywords": [
+    "markdown-it",
+    "markdown-it-plugin",
+    "vue",
+    "toc",
+    "table-of-contents"
+  ],
+  "homepage": "https://github.com/mdit-vue",
+  "bugs": {
+    "url": "https://github.com/mdit-vue/mdit-vue/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mdit-vue/mdit-vue.git"
+  },
+  "license": "MIT",
+  "author": "meteorlxy <meteor.lxy@foxmail.com>",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "unbuild",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "@mdit-vue/shared": "0.3.0",
+    "@types/markdown-it": "^12.2.3",
+    "markdown-it": "^13.0.1"
+  },
+  "devDependencies": {
+    "c8": "^7.11.3",
+    "markdown-it-anchor": "^8.6.4",
+    "unbuild": "^0.7.4",
+    "vitest": "^0.15.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "bcbfd4705d747ee71d6c7c32f8be6155261e9c90"
+}

package/src/create-render-headers.ts

@@ -0,0 +1,43 @@
+import { htmlEscape } from '@mdit-vue/shared';
+import type { MarkdownItHeader } from '@mdit-vue/shared';
+import type { TocPluginOptions } from './types';
+
+type RenderHeadersFn = (headers: MarkdownItHeader[]) => string;
+
+export const createRenderHeaders = ({
+  listTag,
+  listClass,
+  itemClass,
+  linkTag,
+  linkClass,
+}: Pick<
+  Required<TocPluginOptions>,
+  'listTag' | 'listClass' | 'itemClass' | 'linkTag' | 'linkClass'
+>): RenderHeadersFn => {
+  const listTagString = htmlEscape(listTag);
+  const listClassString = listClass ? ` class="${htmlEscape(listClass)}"` : '';
+  const itemTagString = 'li';
+  const itemClassString = itemClass ? ` class="${htmlEscape(itemClass)}"` : '';
+  const linkTagString = htmlEscape(linkTag);
+  const linkClassString = linkClass ? ` class="${htmlEscape(linkClass)}"` : '';
+  const linkTo = (slug: string): string =>
+    linkTag === 'router-link' ? ` to="#${slug}"` : ` href="#${slug}"`;
+
+  const renderHeaders: RenderHeadersFn = (headers) => `\
+<${listTagString}${listClassString}>\
+${headers
+  .map(
+    (header) => `\
+<${itemTagString}${itemClassString}${itemClassString}>\
+<${linkTagString}${linkClassString}${linkTo(header.slug)}>\
+${header.title}\
+</${linkTagString}>\
+${header.children.length > 0 ? renderHeaders(header.children) : ''}\
+</${itemTagString}>\
+`,
+  )
+  .join('')}\
+</${listTagString}>`;
+
+  return renderHeaders;
+};

package/src/create-toc-block-rule.ts

@@ -0,0 +1,62 @@
+import type { RuleBlock } from 'markdown-it/lib/parser_block';
+import type { TocPluginOptions } from './types';
+
+/**
+ * Forked and modified from markdown-it-toc-done-right
+ *
+ * - remove the `inlineOptions` support
+ * - use markdown-it default renderer to render token whenever possible
+ *
+ * @see https://github.com/nagaozen/markdown-it-toc-done-right
+ */
+export const createTocBlockRule = ({
+  pattern,
+  containerTag,
+  containerClass,
+}: Pick<
+  Required<TocPluginOptions>,
+  'pattern' | 'containerTag' | 'containerClass'
+>): RuleBlock => {
+  return (state, startLine, endLine, silent): boolean => {
+    // if it's indented more than 3 spaces, it should be a code block
+    if (state.sCount[startLine] - state.blkIndent >= 4) {
+      return false;
+    }
+
+    const pos = state.bMarks[startLine] + state.tShift[startLine];
+    const max = state.eMarks[startLine];
+
+    // use whitespace as a line tokenizer and extract the first token
+    // to test against the placeholder anchored pattern, rejecting if false
+    const lineFirstToken = state.src.slice(pos, max).split(' ')[0];
+    if (!pattern.test(lineFirstToken)) return false;
+
+    if (silent) return true;
+
+    state.line = startLine + 1;
+
+    // generate toc_open token
+    // will be rendered by markdown-it default renderer
+    const tokenOpen = state.push('toc_open', containerTag, 1);
+    tokenOpen.markup = '';
+    tokenOpen.map = [startLine, state.line];
+    if (containerClass) {
+      tokenOpen.attrSet('class', containerClass);
+    }
+
+    // generate toc_body token
+    // will be rendered by our custom renderer
+    const tokenBody = state.push('toc_body', '', 0);
+    tokenBody.markup = lineFirstToken;
+    tokenBody.map = [startLine, state.line];
+    tokenBody.hidden = true;
+
+    // generate toc_close token
+    // will be rendered by markdown-it default renderer
+    const tokenClose = state.push('toc_close', containerTag, -1);
+    tokenClose.markup = '';
+    tokenBody.map = [startLine, state.line];
+
+    return true;
+  };
+};

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './create-render-headers';
+export * from './create-toc-block-rule';
+export * from './toc-plugin';

package/src/toc-plugin.ts

@@ -0,0 +1,79 @@
+import {
+  slugify as defaultSlugify,
+  resolveHeadersFromTokens,
+} from '@mdit-vue/shared';
+import type { MarkdownItHeader } from '@mdit-vue/shared';
+import type { PluginWithOptions } from 'markdown-it';
+import { createRenderHeaders } from './create-render-headers';
+import { createTocBlockRule } from './create-toc-block-rule';
+import type { TocPluginOptions } from './types';
+
+/**
+ * Generate table of contents
+ *
+ * Forked and modified from markdown-it-toc-done-right:
+ *
+ * @see https://github.com/nagaozen/markdown-it-toc-done-right
+ */
+export const tocPlugin: PluginWithOptions<TocPluginOptions> = (
+  md,
+  {
+    pattern = /^\[\[toc\]\]$/i,
+    slugify = defaultSlugify,
+    format,
+    level = [2, 3],
+    containerTag = 'nav',
+    containerClass = 'table-of-contents',
+    listTag = 'ul',
+    listClass = '',
+    itemClass = '',
+    linkTag = 'a',
+    linkClass = '',
+  }: TocPluginOptions = {},
+): void => {
+  let headers: MarkdownItHeader[];
+
+  // push the rule to the end of the chain
+  // resolve headers from the parsed tokens
+  md.core.ruler.push('resolveTocHeaders', (state) => {
+    headers = resolveHeadersFromTokens(state.tokens, {
+      level,
+      shouldAllowHtml: true,
+      shouldEscapeText: true,
+      slugify,
+      format,
+    });
+    return true;
+  });
+
+  // add toc syntax as a block rule
+  md.block.ruler.before(
+    'heading',
+    'toc',
+    createTocBlockRule({
+      pattern,
+      containerTag,
+      containerClass,
+    }),
+    {
+      alt: ['paragraph', 'reference', 'blockquote'],
+    },
+  );
+
+  const renderHeaders = createRenderHeaders({
+    listTag,
+    listClass,
+    itemClass,
+    linkTag,
+    linkClass,
+  });
+
+  // custom toc_body render rule
+  md.renderer.rules.toc_body = () => {
+    /* istanbul ignore if */
+    if (!headers) {
+      return '';
+    }
+    return renderHeaders(headers);
+  };
+};

package/src/types.ts

@@ -0,0 +1,66 @@
+/**
+ * Options of @mdit-vue/plugin-toc
+ */
+
+export interface TocPluginOptions {
+  /**
+   * The pattern serving as the TOC placeholder in your markdown
+   */
+  pattern?: RegExp;
+
+  /**
+   * A custom slugification function
+   *
+   * Should use the same slugify function with markdown-it-anchor
+   * to ensure the link is matched
+   */
+  slugify?: (str: string) => string;
+
+  /**
+   * A function for formatting headings
+   */
+  format?: (str: string) => string;
+
+  /**
+   * Heading level that going to be included in the TOC
+   *
+   * Should be a subset of markdown-it-anchor's `level` option
+   * to ensure the link is existed
+   */
+  level?: number[];
+
+  /**
+   * HTML tag of the TOC container
+   */
+  containerTag?: string;
+
+  /**
+   * The class for the TOC container
+   */
+  containerClass?: string;
+
+  /**
+   * HTML tag of the TOC list
+   */
+  listTag?: 'ul' | 'ol';
+
+  /**
+   * The class for the TOC list
+   */
+  listClass?: string;
+
+  /**
+   * The class for the `<li>` tag
+   */
+  itemClass?: string;
+
+  /**
+   * The tag of the link inside `<li>` tag
+   */
+  linkTag?: 'a' | 'router-link';
+
+  /**
+   * The class for the link inside the `<li>` tag
+   */
+  linkClass?: string;
+}

package/tests/__snapshots__/toc-plugin.spec.ts.snap

@@ -0,0 +1,161 @@
+// Vitest Snapshot v1
+
+exports[`@vuepress/markdown > plugins > tocPlugin > should render class name correctly > complexTree 1`] = `
+"<nav><ul class=\\"toc-list\\"><li class=\\"toc-item\\" class=\\"toc-item\\"><a class=\\"toc-link\\" href=\\"#s1-1\\">s1-1</a><ul class=\\"toc-list\\"><li class=\\"toc-item\\" class=\\"toc-item\\"><a class=\\"toc-link\\" href=\\"#s1-1-1\\">s1-1-1</a></li><li class=\\"toc-item\\" class=\\"toc-item\\"><a class=\\"toc-link\\" href=\\"#s1-1-2\\">s1-1-2</a></li><li class=\\"toc-item\\" class=\\"toc-item\\"><a class=\\"toc-link\\" href=\\"#s1-1-3\\">s1-1-3</a></li></ul></li><li class=\\"toc-item\\" class=\\"toc-item\\"><a class=\\"toc-link\\" href=\\"#s1-2\\">s1-2</a></li><li class=\\"toc-item\\" class=\\"toc-item\\"><a class=\\"toc-link\\" href=\\"#s1-3\\">s1-3</a><ul class=\\"toc-list\\"><li class=\\"toc-item\\" class=\\"toc-item\\"><a class=\\"toc-link\\" href=\\"#s1-3-2\\">s1-3-2</a></li></ul></li></ul></nav>
+<h1>s1</h1>
+<h2>s1-1</h2>
+<h3>s1-1-1</h3>
+<h4>s1-1-1-1</h4>
+<h3>s1-1-2</h3>
+<h3>s1-1-3</h3>
+<h4>s1-1-3-1</h4>
+<h2>s1-2</h2>
+<h2>s1-3</h2>
+<h3>s1-3-2</h3>
+<h4>s1-3-2-1</h4>
+<h5>s1-3-2-1-1</h5>
+<h5>s1-3-2-1-2</h5>
+"
+`;
+
+exports[`@vuepress/markdown > plugins > tocPlugin > should render class name correctly > reversedTree 1`] = `
+"<nav><ul class=\\"toc-list\\"><li class=\\"toc-item\\" class=\\"toc-item\\"><a class=\\"toc-link\\" href=\\"#h3\\">h3</a></li><li class=\\"toc-item\\" class=\\"toc-item\\"><a class=\\"toc-link\\" href=\\"#h2\\">h2</a></li></ul></nav>
+<h6>h6</h6>
+<h5>h5</h5>
+<h4>h4</h4>
+<h3>h3</h3>
+<h2>h2</h2>
+<h1>h1</h1>
+"
+`;
+
+exports[`@vuepress/markdown > plugins > tocPlugin > should render class name correctly > simpleTree 1`] = `
+"<nav><ul class=\\"toc-list\\"><li class=\\"toc-item\\" class=\\"toc-item\\"><a class=\\"toc-link\\" href=\\"#h2\\">h2</a><ul class=\\"toc-list\\"><li class=\\"toc-item\\" class=\\"toc-item\\"><a class=\\"toc-link\\" href=\\"#h3\\">h3</a></li></ul></li></ul></nav>
+<h1>h1</h1>
+<h2>h2</h2>
+<h3>h3</h3>
+<h4>h4</h4>
+<h5>h5</h5>
+<h6>h6</h6>
+"
+`;
+
+exports[`@vuepress/markdown > plugins > tocPlugin > should render toc (h1, h2, h3, h4) > complexTree 1`] = `
+"<nav class=\\"table-of-contents\\"><ul><li><a href=\\"#s1\\">s1</a><ul><li><a href=\\"#s1-1\\">s1-1</a><ul><li><a href=\\"#s1-1-1\\">s1-1-1</a><ul><li><a href=\\"#s1-1-1-1\\">s1-1-1-1</a></li></ul></li><li><a href=\\"#s1-1-2\\">s1-1-2</a></li><li><a href=\\"#s1-1-3\\">s1-1-3</a><ul><li><a href=\\"#s1-1-3-1\\">s1-1-3-1</a></li></ul></li></ul></li><li><a href=\\"#s1-2\\">s1-2</a></li><li><a href=\\"#s1-3\\">s1-3</a><ul><li><a href=\\"#s1-3-2\\">s1-3-2</a><ul><li><a href=\\"#s1-3-2-1\\">s1-3-2-1</a></li></ul></li></ul></li></ul></li></ul></nav>
+<h1>s1</h1>
+<h2>s1-1</h2>
+<h3>s1-1-1</h3>
+<h4>s1-1-1-1</h4>
+<h3>s1-1-2</h3>
+<h3>s1-1-3</h3>
+<h4>s1-1-3-1</h4>
+<h2>s1-2</h2>
+<h2>s1-3</h2>
+<h3>s1-3-2</h3>
+<h4>s1-3-2-1</h4>
+<h5>s1-3-2-1-1</h5>
+<h5>s1-3-2-1-2</h5>
+"
+`;
+
+exports[`@vuepress/markdown > plugins > tocPlugin > should render toc (h1, h2, h3, h4) > reversedTree 1`] = `
+"<nav class=\\"table-of-contents\\"><ul><li><a href=\\"#h4\\">h4</a></li><li><a href=\\"#h3\\">h3</a></li><li><a href=\\"#h2\\">h2</a></li><li><a href=\\"#h1\\">h1</a></li></ul></nav>
+<h6>h6</h6>
+<h5>h5</h5>
+<h4>h4</h4>
+<h3>h3</h3>
+<h2>h2</h2>
+<h1>h1</h1>
+"
+`;
+
+exports[`@vuepress/markdown > plugins > tocPlugin > should render toc (h1, h2, h3, h4) > simpleTree 1`] = `
+"<nav class=\\"table-of-contents\\"><ul><li><a href=\\"#h1\\">h1</a><ul><li><a href=\\"#h2\\">h2</a><ul><li><a href=\\"#h3\\">h3</a><ul><li><a href=\\"#h4\\">h4</a></li></ul></li></ul></li></ul></li></ul></nav>
+<h1>h1</h1>
+<h2>h2</h2>
+<h3>h3</h3>
+<h4>h4</h4>
+<h5>h5</h5>
+<h6>h6</h6>
+"
+`;
+
+exports[`@vuepress/markdown > plugins > tocPlugin > should render toc with RouterLink > complexTree 1`] = `
+"<nav class=\\"table-of-contents\\"><ul><li><RouterLink href=\\"#s1-1\\">s1-1</RouterLink><ul><li><RouterLink href=\\"#s1-1-1\\">s1-1-1</RouterLink></li><li><RouterLink href=\\"#s1-1-2\\">s1-1-2</RouterLink></li><li><RouterLink href=\\"#s1-1-3\\">s1-1-3</RouterLink></li></ul></li><li><RouterLink href=\\"#s1-2\\">s1-2</RouterLink></li><li><RouterLink href=\\"#s1-3\\">s1-3</RouterLink><ul><li><RouterLink href=\\"#s1-3-2\\">s1-3-2</RouterLink></li></ul></li></ul></nav>
+<h1>s1</h1>
+<h2>s1-1</h2>
+<h3>s1-1-1</h3>
+<h4>s1-1-1-1</h4>
+<h3>s1-1-2</h3>
+<h3>s1-1-3</h3>
+<h4>s1-1-3-1</h4>
+<h2>s1-2</h2>
+<h2>s1-3</h2>
+<h3>s1-3-2</h3>
+<h4>s1-3-2-1</h4>
+<h5>s1-3-2-1-1</h5>
+<h5>s1-3-2-1-2</h5>
+"
+`;
+
+exports[`@vuepress/markdown > plugins > tocPlugin > should render toc with RouterLink > reversedTree 1`] = `
+"<nav class=\\"table-of-contents\\"><ul><li><RouterLink href=\\"#h3\\">h3</RouterLink></li><li><RouterLink href=\\"#h2\\">h2</RouterLink></li></ul></nav>
+<h6>h6</h6>
+<h5>h5</h5>
+<h4>h4</h4>
+<h3>h3</h3>
+<h2>h2</h2>
+<h1>h1</h1>
+"
+`;
+
+exports[`@vuepress/markdown > plugins > tocPlugin > should render toc with RouterLink > simpleTree 1`] = `
+"<nav class=\\"table-of-contents\\"><ul><li><RouterLink href=\\"#h2\\">h2</RouterLink><ul><li><RouterLink href=\\"#h3\\">h3</RouterLink></li></ul></li></ul></nav>
+<h1>h1</h1>
+<h2>h2</h2>
+<h3>h3</h3>
+<h4>h4</h4>
+<h5>h5</h5>
+<h6>h6</h6>
+"
+`;
+
+exports[`@vuepress/markdown > plugins > tocPlugin > should render toc with default option (h2, h3) > complexTree 1`] = `
+"<nav class=\\"table-of-contents\\"><ul><li><a href=\\"#s1-1\\">s1-1</a><ul><li><a href=\\"#s1-1-1\\">s1-1-1</a></li><li><a href=\\"#s1-1-2\\">s1-1-2</a></li><li><a href=\\"#s1-1-3\\">s1-1-3</a></li></ul></li><li><a href=\\"#s1-2\\">s1-2</a></li><li><a href=\\"#s1-3\\">s1-3</a><ul><li><a href=\\"#s1-3-2\\">s1-3-2</a></li></ul></li></ul></nav>
+<h1>s1</h1>
+<h2>s1-1</h2>
+<h3>s1-1-1</h3>
+<h4>s1-1-1-1</h4>
+<h3>s1-1-2</h3>
+<h3>s1-1-3</h3>
+<h4>s1-1-3-1</h4>
+<h2>s1-2</h2>
+<h2>s1-3</h2>
+<h3>s1-3-2</h3>
+<h4>s1-3-2-1</h4>
+<h5>s1-3-2-1-1</h5>
+<h5>s1-3-2-1-2</h5>
+"
+`;
+
+exports[`@vuepress/markdown > plugins > tocPlugin > should render toc with default option (h2, h3) > reversedTree 1`] = `
+"<nav class=\\"table-of-contents\\"><ul><li><a href=\\"#h3\\">h3</a></li><li><a href=\\"#h2\\">h2</a></li></ul></nav>
+<h6>h6</h6>
+<h5>h5</h5>
+<h4>h4</h4>
+<h3>h3</h3>
+<h2>h2</h2>
+<h1>h1</h1>
+"
+`;
+
+exports[`@vuepress/markdown > plugins > tocPlugin > should render toc with default option (h2, h3) > simpleTree 1`] = `
+"<nav class=\\"table-of-contents\\"><ul><li><a href=\\"#h2\\">h2</a><ul><li><a href=\\"#h3\\">h3</a></li></ul></li></ul></nav>
+<h1>h1</h1>
+<h2>h2</h2>
+<h3>h3</h3>
+<h4>h4</h4>
+<h5>h5</h5>
+<h6>h6</h6>
+"
+`;

package/tests/toc-plugin.spec.ts

@@ -0,0 +1,193 @@
+import { slugify } from '@mdit-vue/shared';
+import MarkdownIt from 'markdown-it';
+import anchorPlugin from 'markdown-it-anchor';
+import { describe, expect, it } from 'vitest';
+import { tocPlugin } from '../src';
+
+const fixtures = {
+  simpleTree: `\
+[[toc]]
+# h1
+## h2
+### h3
+#### h4
+##### h5
+###### h6
+`,
+  complexTree: `\
+[[toc]]
+# s1
+## s1-1
+### s1-1-1
+#### s1-1-1-1
+### s1-1-2
+### s1-1-3
+#### s1-1-3-1
+## s1-2
+## s1-3
+### s1-3-2
+#### s1-3-2-1
+##### s1-3-2-1-1
+##### s1-3-2-1-2
+`,
+  reversedTree: `\
+[[toc]]
+###### h6
+##### h5
+#### h4
+### h3
+## h2
+# h1
+`,
+};
+
+describe('@vuepress/markdown > plugins > tocPlugin', () => {
+  describe('should render toc with default option (h2, h3)', () => {
+    const md = MarkdownIt().use(tocPlugin);
+
+    Object.entries(fixtures).forEach(([name, source]) => {
+      it(name, () => {
+        const result = md.render(source);
+        expect(result).toMatchSnapshot();
+      });
+    });
+  });
+
+  describe('should render toc (h1, h2, h3, h4)', () => {
+    const md = MarkdownIt().use(tocPlugin, {
+      level: [1, 2, 3, 4],
+    });
+
+    Object.entries(fixtures).forEach(([name, source]) => {
+      it(name, () => {
+        const result = md.render(source);
+        expect(result).toMatchSnapshot();
+      });
+    });
+  });
+
+  describe('should render toc with RouterLink', () => {
+    const md = MarkdownIt().use(tocPlugin, {
+      linkTag: 'RouterLink',
+    });
+
+    Object.entries(fixtures).forEach(([name, source]) => {
+      it(name, () => {
+        const result = md.render(source);
+        expect(result).toMatchSnapshot();
+      });
+    });
+  });
+
+  describe('should render class name correctly', () => {
+    const md = MarkdownIt().use(tocPlugin, {
+      // remove default container class
+      containerClass: '',
+      // add custom list / item / link class
+      listClass: 'toc-list',
+      itemClass: 'toc-item',
+      linkClass: 'toc-link',
+    });
+
+    Object.entries(fixtures).forEach(([name, source]) => {
+      it(name, () => {
+        const result = md.render(source);
+        expect(result).toMatchSnapshot();
+      });
+    });
+  });
+
+  describe('should include html elements and should escape texts', () => {
+    const md = MarkdownIt({
+      html: true,
+    })
+      .use(anchorPlugin, {
+        level: [1, 2, 3, 4, 5, 6],
+        slugify,
+        permalink: anchorPlugin.permalink.ariaHidden({
+          class: 'header-anchor',
+          symbol: '#',
+          space: true,
+          placement: 'before',
+        }),
+      })
+      .use(tocPlugin, { slugify });
+
+    const testCases: [string, { slug: string; title: string; h2: string }][] = [
+      // html element should be kept as is
+      [
+        `\
+[[toc]]
+## foo <bar />
+`,
+        {
+          slug: 'foo',
+          title: 'foo <bar />',
+          h2: 'foo <bar />',
+        },
+      ],
+      // inline code should be escaped
+      [
+        `\
+[[toc]]
+## foo <bar /> \`<code />\`
+`,
+        {
+          slug: 'foo-code',
+          title: 'foo <bar /> &lt;code /&gt;',
+          h2: 'foo <bar /> <code>&lt;code /&gt;</code>',
+        },
+      ],
+      // text should be escaped
+      [
+        `\
+[[toc]]
+## foo <bar/> "baz"
+`,
+        {
+          slug: 'foo-baz',
+          title: 'foo <bar/> &quot;baz&quot;',
+          h2: 'foo <bar/> &quot;baz&quot;',
+        },
+      ],
+      // text should be escaped
+      [
+        `\
+[[toc]]
+## < test >
+`,
+        {
+          slug: 'test',
+          title: '&lt; test &gt;',
+          h2: '&lt; test &gt;',
+        },
+      ],
+    ];
+
+    testCases.forEach(([source, expected], i) =>
+      it(`case ${i}`, () => {
+        expect(md.render(source)).toEqual(`\
+<nav class="table-of-contents"><ul><li><a href="#${expected.slug}">${expected.title}</a></li></ul></nav>
+<h2 id="${expected.slug}" tabindex="-1"><a class="header-anchor" href="#${expected.slug}" aria-hidden="true">#</a> ${expected.h2}</h2>
+`);
+      }),
+    );
+  });
+
+  describe('edge cases', () => {
+    it('should not terminate the blockquote', () => {
+      const md = MarkdownIt().use(tocPlugin);
+
+      const source = `\
+> foo
+    [[toc]]
+`;
+      expect(md.render(source)).toEqual(`\
+<blockquote>
+<p>foo
+[[toc]]</p>
+</blockquote>
+`);
+    });
+  });
+});