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 1 的项目
order 2 的项目
...
order 10 的项目
...
// 无 order 的项目
无 order 的项目
无 order 的项目
...
// 负数按从小到大排列
order -10 的项目
// ...
order -2 的项目
order -1 的项目

选项

level 仅限内置组件

• 类型：1 | 2 | 3
• 默认值：3
• 详情：目录项级别的最大深度

index 仅限内置组件

• 类型：boolean
• 默认值：false
• 详情：是否显示目录索引

frontmatter

• 类型：(path: string) => Record<string, any>

• 详情：生成页面的 Frontmatter 获取器

• 示例：

  .vuepress/config.ts

  import { catalogPlugin } from '@vuepress/plugin-catalog'
  
  export default {
    plugins: [
      catalogPlugin({
        frontmatter: (path) => ({
          // 你想要的 frontmatter
          // 你可以自定义标题、作者、时间等
        }),
      }),
    ],
  }

exclude

• 类型：(RegExp | string)[]

• 默认值：[]

• 详情：

  需要排除的目录页路径。

  • "/foo/" 仅排除 /foo/ 文件夹的目录页生成
  • /^\/foo\// 排除 /foo/ 文件夹及其子文件夹的目录页生成

  404 页面会被自动排除。

component

• 类型：string
• 详情：用作目录的组件名称

locales

• 类型：CatalogPluginLocaleConfig

  interface CatalogPluginLocaleData {
    /**
     * 目录标题
     */
    title: string
  
    /**
     * 空目录提示
     */
    empty: string
  }
  
  interface CatalogPluginLocaleConfig {
    [localePath: string]: Partial<CatalogPluginLocaleData>
  }

• 详情：目录组件国际化配置

客户端选项

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);
}