catalog

此插件可以自动生成目录页面，并提供目录组件。

使用方法

npm i -D @vuepress/plugin-catalog@next

import { catalogPlugin } from '@vuepress/plugin-catalog'

export default {
  plugins: [
    catalogPlugin({
      // 你的选项
    }),
  ],
}

指南

目录信息

首先，你需要在路由元信息中设置目录信息：

import { catalogPlugin } from '@vuepress/plugin-catalog'

export default {
  extendsPage: (page) => {
    // 在 routeMeta 中设置目录信息
    page.routeMeta = {
      // 目录标题
      title: page.title,
      // ... 其他信息
    }
  },
}

然后导入 defineCatalogInfoGetter 并在客户端配置文件中使用它来从路由元信息中提取目录信息。

import { defineCatalogInfoGetter } from '@vuepress/plugin-catalog/client'

defineCatalogInfoGetter((meta) => (meta.title ? { title: meta.title } : null))

目录信息应包含：

• title：目录标题
• order：目录顺序（可选）
• content：目录内容组件（可选）

通过 order 排序

插件会按以下顺序通过 order 对页面进行排序：

// 正数按从小到大排列
order 1 的项目
order 2 的项目
...
order 10 的项目
...
// 无 order 的项目
无 order 的项目
无 order 的项目
...
// 负数按从小到大排列
order -10 的项目
// ...
order -2 的项目
order -1 的项目

选项

import { catalogPlugin } from '@vuepress/plugin-catalog'

export default {
  plugins: [
    catalogPlugin({
      frontmatter: (path, app) => ({
        // 你想要的 frontmatter
        // 你可以自定义标题、作者、时间等
      }),
    }),
  ],
}

客户端选项

defineCatalogInfoGetter

interface CatalogInfo {
  /** 目录标题 */
  title: string
  /** 目录顺序 */
  order?: number
  /** 目录内容 */
  content?: Component
}

type CatalogInfoGetter = (meta: Record<string, unknown>) => CatalogInfo | null

const defineCatalogInfoGetter: (options: CatalogInfoGetter) => void

自定义如何从路由元信息中提取目录信息。

组件

Catalog

• 详情：

  该插件默认会全局注册一个 <Catalog /> 组件（除非你设置了 component 选项）。

  你可以在主题布局中或直接在 Markdown 文件中使用 <Catalog />。

  组件支持以下属性：

  • level：更改显示层次深度（最大支持 3 层），默认为 3
  • base：显示指定文件夹的目录，默认显示当前文件夹目录
  • index：为目录项添加索引号，默认无标号
  • hideHeading：隐藏组件标题，默认显示 目录 标题

样式

你可以通过 CSS 变量来自定义目录样式：

:root {
  --catalog-c-accent: var(--vp-c-accent);
  --catalog-c-accent-text: var(--vp-c-accent-text);
  --catalog-c-control: var(--vp-c-bg-alt);
  --catalog-c-control-hover: var(--vp-c-bg-alt);
  --catalog-c-divider: var(--vp-c-divider);
  --catalog-header-offset: var(--header-offset, 3.6rem);
}