DOM 结构

一个主题必须实现以下 DOM 结构：

• 容器：一个包含整个主题的元素。此元素应该有一个 vp-container 属性。
• 内容：一个包含 markdown 渲染结果的元素。此元素应该有一个 vp-content 属性。

一个主题可以有以下可选元素：

• 导航栏：站点的导航栏。此元素应该有一个 vp-navbar 属性。
• 侧边栏：站点的侧边栏。此元素应该有一个 vp-sidebar 属性。
• 大纲：主要内容的标题或大纲。此元素应该有一个 vp-outline 属性。
• 评论：评论服务（评论框和评论列表）。此元素应该有一个 vp-comment 属性。
• 页脚：站点的页脚。此元素应该有一个 vp-footer 属性。

一个主题必须：

• 在暗色模式下，将 html 元素的 data-theme 设置为 dark。
• 在亮色模式下，将 html 元素的 data-theme 设置为 light。

如果主题只有一种颜色方案，主题仍然需要将 data-theme 设置为 light 或 dark，以指示默认颜色方案。

组件

为了支持搜索插件，主题应检查 <SearchBox /> 是否已全局注册，并在其自己的导航栏或侧边栏中呈现（如果可用）。

颜色变量

一个主题必须实现以下颜色变量：

文字

• --vp-c-text：默认文本颜色。
• --vp-c-text-mute：用于静音文本的颜色，例如“非活动菜单”或“信息文本”。
• --vp-c-text-subtle：用于细微文本的颜色，例如“占位符”或“插入符号”。

背景

• --vp-c-bg：用于主屏幕的背景颜色。
• --vp-c-bg-alt：用于“侧边栏”或“代码块”等地方的备用背景颜色。
• --vp-c-bg-elv：用于“浮动”部分的提升背景颜色，例如“对话框”。

阴影

• --vp-c-shadow：阴影颜色

强调

用于交互组件的强调颜色和品牌颜色。

• --vp-c-accent：主要用于彩色文本的最实色。它必须满足与放在 --vp-c-accent-soft 顶部时的对比度。

• --vp-c-accent-hover：用于悬停状态的颜色。

• --vp-c-accent-bg：用于实色背景的颜色。它必须满足与放在其顶部的 --vp-c-accent-text 的对比度。

• --vp-c-accent-text：用于 --vp-c-accent-bg 背景的文本颜色。它必须满足与 --vp-c-accent-bg 的对比度。

• --vp-c-accent-soft：用于自定义容器或徽章等细微背景的颜色。当将 --vp-c-accent 颜色放在其顶部时，它必须满足对比度。

  软色必须是半透明的 alpha 通道。这是至关重要的，因为它允许将多个“软”颜色叠加在一起以创建强调，例如在自定义容器内部有内联代码块时。

边框

• --vp-c-border：交互组件的边框颜色。例如，这应该用于按钮轮廓。
• --vp-c-border-hard：较暗的边框颜色，用于紧贴文本的“硬”边框，例如表格和 kbd。
• --vp-c-divider：分隔符的颜色，用于在同一组件内分隔部分，例如在“h2”标题上放置分隔符。

控件

• --vp-c-control：用于交互控件（例如按钮或复选框）的背景颜色。
• --vp-c-control-hover：用于交互控件悬停状态的背景颜色。
• --vp-c-control-disabled：用于交互控件禁用状态的颜色。

过渡时间

• --vp-t-color：颜色过渡时间。
• --vp-t-transform：变换过渡时间。

案例

使用方法 (Usage)

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

import { llmsPlugin } from '@vuepress/plugin-llms'

export default {
  plugins: [
    llmsPlugin({
      // 选项
    }),
  ],
}

为什么需要 llms.txt？

大型语言模型（LLM）越来越依赖网络文档来回答用户提问和编写代码。然而，普通网站存在明显的局限性：上下文窗口（Context Window）有限，且充斥着导航栏、脚本和样式的原始 HTML 既浪费 Token 又难以解析。

llms.txt 填补了这一空白。它为 AI Agent 创建了一个标准化的入口点，提供项目的简要摘要以及通往干净、专家级文档的直接链接。这对于开发工具文档尤为重要，能够确保 LLM 准确、无干扰地获取你的 API 和指南。

插件概览

该插件会自动将你的 VuePress 文档转换为针对机器阅读优化的结构化数据集。

在构建过程中，它会在输出目录中生成以下资源：

📂 .vuepress/dist
├── ...
├── llms.txt                # 文档入口点 / 索引映射
├── llms-full.txt           # 包含完整文档的单个合并文件
├── markdown-examples.html  # 你的标准网页
└── markdown-examples.md    # 该页面的纯净 Markdown 版本

输出文件

1. llms.txt

llms.txt 文件充当 AI Agent 的主索引。它包含站点的 标题 (Title)、描述 (Description)、详情 (Details - 可选) 以及 目录 (Table of Contents)。

你可以点击链接查看本文档站点的生成文件：llms.txt。

默认格式：

# Title

> Description

Details (Optional)

## Table of Contents

- [Title](url): Description
- [Title](url): Description
- ...

内容解析逻辑：

插件根据以下优先级顺序（从高到低）确定字段内容：

• 站点标题 (Site Title):

  1. llmsTxtTemplateGetter.title
  2. 首页 Frontmatter 中的 heroText
  3. VuePress 配置中当前语言环境 (locale) 的 title
  4. VuePress 配置中的主 title
  5. 语言环境首页 (README.md) 的页面标题

• 站点描述 (Site Description):

  1. llmsTxtTemplateGetter.description
  2. 语言环境首页 Frontmatter 中的 tagline
  3. VuePress 配置中当前语言环境 (locale) 的 description
  4. VuePress 配置中的主 description
  5. 语言环境首页 (README.md) 的 frontmatter.description

• 站点详情 (Site Details - 可选):

  1. llmsTxtTemplateGetter.details
  2. 语言环境首页 (README.md) 的 frontmatter.details

• 目录 (Table of Contents):
  格式为 - [title](url): description。其中 description 取自页面的 frontmatter.description。

  默认情况下，插件仅生成一级扁平目录。你可以通过在 llmsTxtTemplateGetter 选项中定义自定义函数来修改此行为（例如支持多级嵌套）。

2. llms-full.txt

llms-full.txt 是文档的拼接版本。它将所有 Markdown 文件的内容合并到一个文本流中，允许 LLM 通过一次请求读取你的整个知识库。

你可以点击链接查看本文档站点的完整文件：llms-full.txt。

格式：

该插件主要用于开发主题，并且已经集成到默认主题中。大部分情况下你不需要直接使用它。

使用方法

npm i -D @vuepress/plugin-active-header-links@next

import { activeHeaderLinksPlugin } from '@vuepress/plugin-active-header-links'

export default {
  plugins: [
    activeHeaderLinksPlugin({
      // 配置项
    }),
  ],
}

配置项

headerLinkSelector

• 类型： string

• 默认值： 'a.vp-sidebar-item'

• 详情：

  标题链接 的选择器。

  如果一个 标题锚点 没有对应的 标题链接 ，那么即使滚动到这个 标题锚点 ，该插件也不会更改路由 Hash 。

headerAnchorSelector

• 类型： string

• 默认值： '.header-anchor'

• 详情：

  标题锚点 的选择器。

  你通常不需要设置该选项，除非你通过 markdown.anchor 修改了 markdown-it-anchor 的 permalinkClass 选项。

• 参考：

  • 指南 > Markdown > 语法扩展 > 标题锚点

delay

• 类型： number

• 默认值： 200

• 详情：

  滚动事件监听器的 Debounce 延迟。

offset

• 类型： number

• 默认值： 5

• 详情：

  即便直接点击 标题锚点 的链接， scrollTop 也可能不会完全等于 标题锚点 的 offsetTop ，所以我们添加一个 Offset 偏移量来避免这个误差。

默认主题中的 lastUpdated 和 contributors 功能正是由该插件提供支持的。

该插件主要用于主题开发，在大多数情况下你不需要直接使用它，而是通过主题配置来开启相关功能。

使用方法

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

import { gitPlugin } from '@vuepress/plugin-git'

export default {
  plugins: [
    gitPlugin({
      // 配置项
    }),
  ],
}

Git 仓库

本插件要求你的项目必须在一个 Git 仓库中，以便它能从提交历史中收集信息。

你应该确保在构建站点时可以访问到完整的提交记录。例如，CI 工作流（如 GitHub Actions）通常会使用 [--depth 1](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt

该插件主要用于主题开发，并且已经集成到默认主题中。大部分情况下你不需要直接使用它。

对于主题作者，该插件可以为用户提供自定义样式的能力。

使用方法

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

import { palettePlugin } from '@vuepress/plugin-palette'

export default {
  plugins: [
    palettePlugin({
      // 配置项
    }),
  ],
}

调色板和样式

该插件会提供一个 @vuepress/plugin-palette/palette（调色板文件），用于在你的主题样式中引入。

调色板文件用于定义样式变量，因此它通常会在你主题样式的开头引入。举例来说，用户可以在调色板中定义 CSS 变量、SASS 变量、LESS 变量或 Stylus 变量，然后你可以在你的主题样式中使用这些变量。

教程

在你的主题中使用该插件，假设你使用 SASS 作为 CSS 预处理器：

export default {
  // ...
  plugins: [palettePlugin({ preset: 'sass' })],
}

使用调色板

在你主题需要使用对应变量的地方引入该插件的调色板文件，比如在 Layout.vue 中：

<template>
  <h1 class="palette-title">你好，调色板！</h1>
</template>

<style lang="scss">
/* 从该插件的调色板中引入变量 */
@use '@vuepress/plugin-palette/palette' as *;

/* 设置变量的默认值 */
$color: red !default;

/* 在你的样式中使用变量 */
.palette-title {
  color: $color;
}
</style>

然后，用户就可以在 .vuepress/styles/palette.scss 中自定义变量：

$color: green;

配置项

preset

• 类型： 'css' | 'less' | 'sass' | 'stylus'

• 默认值： 'css'

• 详情：

  为其他配置项设置预设值。

  如果你不需要对插件进行高级自定义，建议只设置该配置项并省略其他配置项。

userPaletteFile

• 类型： string

• 默认值：

  • css: '.vuepress/styles/palette.css'
  • less: '.vuepress/styles/palette.less'
  • sass: '.vuepress/styles/palette.scss'
  • stylus: '.vuepress/styles/palette.styl'

• 详情：

  用户调色板文件的路径，相对于源文件目录。

  默认值依赖于 preset 配置项。

  此文件用于用户定义样式变量，建议保持默认文件路径作为约定。

tempPaletteFile

• 类型： string

• 默认值：

  • css: 'styles/palette.css'
  • less: 'styles/palette.less'
  • sass: 'styles/palette.scss'
  • stylus: 'styles/palette.styl'

• 详情：

  生成的调色板临时文件的路径，相对于临时文件目录。

  默认值依赖于 preset 配置项。

  你应该通过 '@vuepress/plugin-palette/palette' 别名引入调色板文件，因此大部分情况下你不需要修改该配置项。

importCode

• 类型： (filePath: string) => string

• 默认值：

  • css: (filePath) => `@import '${filePath}';\n`
  • less: (filePath) => `@import '${filePath}';\n`
  • sass: (filePath) => `@forward 'file:///${filePath}';\n`
  • stylus: (filePath) => `@require '${filePath}';\n`

• 详情：

  生成引入代码的函数。

  默认值依赖于 preset 配置项。

  该配置项用于生成 tempPaletteFile，大部分情况下你不需要修改该配置项。

使用方法

npm i -D @vuepress/plugin-reading-time@next

import { readingTimePlugin } from '@vuepress/plugin-reading-time'

export default {
  plugins: [
    readingTimePlugin({
      // 选项
    }),
  ],
}

页面数据（Node.js 端）

初始化后，插件会计算每个页面的统计信息，并将它们注入到 page.data.readingTime 属性中。该对象包含：

• minutes: 预计阅读时间，单位为分钟 (number)。
• words: 总字数 (number)。

你可以在 Node.js 端的构建过程中直接访问此数据，例如在 extendsPage 或 onInitialized 生命周期中：

export default {
  // ...
  extendsPage: (page) => {
    // 访问当前正在处理页面的阅读时间数据
    console.log(page.data.readingTime) // { minutes: 3.2, words: 934 }
  },

  onInitialized: (app) => {
    // 遍历 VuePress 应用中的所有页面
    app.pages.forEach((page) => {
      console.log(page.data.readingTime) // { minutes: 3.2, words: 934 }
    })
  },
}

组合式 API (客户端)

要在主题或组件中显示阅读时间信息，你可以使用客户端模块提供的组合式 API（Composables）。

引入 useReadingTimeData 获取原始数值，或引入 useReadingTimeLocale 获取本地化的文本字符串：

<script setup lang="ts">
import {
  useReadingTimeData,
  useReadingTimeLocale,
} from '@vuepress/plugin-reading-time/client'

// 获取原始值（例如用于自定义逻辑或排序）
const readingTimeData = useReadingTimeData() // { minutes: 1.1, words: 100 }

// 根据当前站点配置获取本地化文本
const readingTimeLocale = useReadingTimeLocale() // { time: "1 minute", words: "100 words" }
</script>

选项

wordPerMinute

• 类型：number
• 默认值：300
• 详情：每分钟阅读的字数。

locales

• 类型：ReadingTimePluginLocaleConfig

  interface ReadingTimePluginLocaleData {
    /**
     * 字数模板，`$word` 会被自动替换为实际字数
     */
    word: string
  
    /**
     * 小于一分钟时的文本
     */
    less1Minute: string
  
    /**
     * 时间模板，`$time` 会被自动替换为实际时间
     */
    time: string
  }
  
  interface ReadingTimePluginLocaleConfig {
    [localePath: string]: Partial<ReadingTimePluginLocaleData>
  }

• 详情：阅读时间和字数文本的多语言配置。

客户端 API

你可以从 @vuepress/plugin-reading-time/client 导入并使用这些 API：

useReadingTimeData

interface ReadingTime {
  /** 预计阅读时间（分钟） */
  minutes: number
  /** 内容字数 */
  words: number
}

const useReadingTimeData: () => ComputedRef<ReadingTime | null>

当插件被禁用时返回 null。

useReadingTimeLocale

interface ReadingTimeLocale {
  /** 本地化的预计阅读时间文本 */
  time: string
  /** 本地化的字数统计文本 */
  words: string
}

const useReadingTimeLocale: () => ComputedRef<ReadingTimeLocale>

主题集成

对于插件和主题开发者，我们提供了一个编程式的 "Use API"。相比于直接在你的主题 plugins 数组中添加该插件，我们更推荐这种方式，因为它能处理注册顺序并防止重复注册。

import { useReadingTimePlugin } from '@vuepress/plugin-reading-time'

export default (options) => (app) => {
  useReadingTimePlugin(app, {
    // 你的配置选项
  })

  return {
    name: 'vuepress-plugin-xxx', // or vuepress-theme-xxx
  }
}

如果你需要强制应用特定配置或重置插件状态，可以使用 removeReadingTimePlugin：

import { useReadingTimePlugin } from '@vuepress/plugin-reading-time'

export default (options) => (app) => {
  // 移除此时任何已存在的阅读时间插件实例
  removeReadingTimePlugin(app)

  // 重新注册插件，以确保你的特定配置生效
  useReadingTimePlugin(app, {
    // 你的配置选项
  })

  return {
    name: 'vuepress-plugin-xxx', // or vuepress-theme-xxx
  }
}

使用方法

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

import { rtlPlugin } from '@vuepress/plugin-rtl'

export default {
  plugins: [
    rtlPlugin({
      // 配置项
      locales: ['/ar/'],
    }),
  ],
}

示例

选项

locales

• 类型：string[]
• 默认值：['/']
• 详情：启用 RTL 布局的语言路径。

selector

• 类型：SelectorOptions

  interface SelectorOptions {
    [cssSelector: string]: {
      [attr: string]: string
    }
  }

• 默认值：{ 'html': { dir: 'rtl' } }

• 详情：启用 RTL 布局的选择器配置。默认设置意味着在 RTL 语言中，html 元素的 dir 属性将被设置为 rtl。

该插件主要用于开发主题，并且已经集成到默认主题中。大部分情况下你不需要直接使用它。

对于主题作者，该插件可以提供与 VuePress 及默认主题相同的多语言支持机制。但是如果你的主题不需要提供多语言支持，或者你想用自己的方式来实现多语言支持，那么你不需要使用该插件。

使用方法

npm i -D @vuepress/plugin-theme-data@next

import { themeDataPlugin } from '@vuepress/plugin-theme-data'

export default {
  plugins: [
    themeDataPlugin({
      // 配置项
    }),
  ],
}

配置项

themeData

• 类型：ThemeData

• 必填：是

• 详情：

  你希望在客户端中使用的主题数据对象。

  你可以通过该配置项，在 Node 端提供主题数据，然后在客户端通过 useThemeData 和 useThemeLocaleData 来使用主题数据。

• 示例：

export default {
  plugins: [
    themeDataPlugin({
      themeData: {
        foo: 'foo',
        locales: {
          '/zh/': {
            foo: 'zh-foo',
          },
        },
      },
    }),
  ],
}

Composition API

useThemeData

• 详情：

  返回主题数据的响应式引用对象。

  数据是通过 themeData 配置项提供的。

• 示例：

import type { ThemeData } from '@vuepress/plugin-theme-data/client'
import { useThemeData } from '@vuepress/plugin-theme-data/client'

type MyThemeData = ThemeData<{
  foo: string
}>

export default {
  setup(): void {
    const themeData = useThemeData<MyThemeData>()
    console.log(themeData.value)
  },
}

useThemeLocaleData

• 详情：

  返回当前语言环境下主题数据的响应式引用对象。

  当前语言环境中的字段已被合并到顶层字段中。

• 示例：

import type { ThemeData } from '@vuepress/plugin-theme-data/client'
import { useThemeLocaleData } from '@vuepress/plugin-theme-data/client'

type MyThemeData = ThemeData<{
  foo: string
}>

export default {
  setup(): void {
    const themeLocaleData = useThemeLocaleData<MyThemeData>()
    console.log(themeLocaleData.value)
  },
}

使用方法

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

import { tocPlugin } from '@vuepress/plugin-toc'

export default {
  plugins: [
    tocPlugin({
      // 配置项
    }),
  ],
}

与 Markdown 目录语法的区别

与 Markdown 目录语法 类似，该插件提供的目录组件可以直接在你的 Markdown 内容中使用：

<!-- Markdown 目录语法 -->

[[toc]]

<!-- Vue 目录组件 -->
<Toc />

在 Build 模式中，它们都可以被正确地预渲染。然而，它们之间存在一些区别。

Markdown 语法 [[toc]] 仅能在 Markdown 文件中使用。它是由 markdown-it 解析的，生成的目录是静态内容。

组件 <Toc/> 既可以用在 Markdown 文件中，也可以用在 Vue 文件中。它是由 Vue 加载的，生成的目录是一个 Vue 组件。

该插件可以和 @vuepress/plugin-active-header-links 协同工作，你只需要将 headerLinkSelector 与该插件的 linkClass 匹配即可。当页面滚动至某个标题锚点后，对应的链接就会被加上 linkActiveClass 类名。

因此，该插件对于主题开发者来说更为有用。

配置项

componentName

• 类型： string

• 默认值： 'Toc'

• 详情：

  指定目录组件的名称。

headersOptions

• 类型： Partial<GetHeadersOptions>

• 默认值： {}

• 详情：

  覆盖组件 headersOptions Prop 的默认值。

renderOptions

• 类型： Partial<TocPropsOptions>

• 默认值： {}

• 详情：

  覆盖组件 renderOptions Prop 的默认值。

组件 Props

目录组件可以通过 Props 来进行自定义。

<template>
  <Toc
    :headers="headers"
    :headers-options="headersOptions"
    :render-options="renderOptions"
  />
</template>

headers

• 类型： PageHeader[]

interface PageHeader {
  level: number
  title: string
  slug: string
  children: PageHeader[]
}

• 详情：

  指定要渲染的标题数组。

  如果该 Prop 没有被设置，默认会使用当前页面的标题。

headersOptions

• 类型： Partial<GetHeadersOptions>

  详见 GetHeadersOptions

• 默认值：

  详见 GetHeadersOptions，可以通过插件配置项中的 headersOptions 来覆盖。

• 详情：

  自定义标题提取行为。

renderOptions

• 类型： TocRenderOptions

interface TocRenderOptions {
  /**
   * Container tag name
   *
   * @default 'nav'
   */
  containerTag?: string

  /**
   * Container class name
   *
   * @default 'vuepress-toc'
   */
  containerClass?: string

  /**
   * List class name
   *
   * @default 'vuepress-toc-list'
   */
  listClass?: string

  /**
   * Item class name
   *
   * @default 'vuepress-toc-item'
   */
  itemClass?: string

  /**
   * Link tag type
   *
   * @default 'RouteLink'
   */
  linkTag?: 'a' | 'RouteLink' | 'RouterLink'

  /**
   * Link class name
   *
   * @default 'vuepress-toc-link'
   */
  linkClass?: string

  /**
   * Active link class name
   *
   * @default 'active'
   */
  linkActiveClass?: string

  /**
   * Active children link class name
   *
   * @default 'active'
   */
  linkChildrenActiveClass?: string
}

• 默认值：

  下列默认值可以通过插件配置项中的 renderOptions 来覆盖：

const defaultOptions = {
  containerTag: 'nav',
  containerClass: 'vuepress-toc',
  listClass: 'vuepress-toc-list',
  itemClass: 'vuepress-toc-item',
  linkTag: 'RouteLink',
  linkClass: 'vuepress-toc-link',
  linkActiveClass: 'active',
  linkChildrenActiveClass: 'active',
}

• 详情：

  自定义目录组件渲染行为。

  如果 containerTag 设置为空字符串 '' ，那么最外层的 <nav> Container 会被完全移除。

• 示例：

  使用默认 options 的目录组件的渲染结果类似以下结构：

<template>
  <!-- container -->
  <nav class="vuepress-toc">
    <!-- list -->
    <ul class="vuepress-toc-list">
      <!-- item -->
      <li class="vuepress-toc-item">
        <!-- link -->
        <RouteLink class="vuepress-toc-link" to="#foo">Foo</RouteLink>
      </li>
      <!-- item with children -->
      <li class="vuepress-toc-item">
        <!-- link (children active) -->
        <RouteLink class="vuepress-toc-link active" to="#bar">Bar</RouteLink>
        <!-- list (children) -->
        <ul class="vuepress-toc-list">
          <!-- item -->
          <li class="vuepress-toc-item">
            <!-- link (active) -->
            <RouteLink class="vuepress-toc-link active" to="#bar-child">
              Bar Child
            </RouteLink>
          </li>
        </ul>
      </li>
    </ul>
  </nav>
</template>

该插件已经集成到默认主题中。

使用方法

npm i -D @vuepress/plugin-back-to-top@next

import { backToTopPlugin } from '@vuepress/plugin-back-to-top'

export default {
  plugins: [backToTopPlugin()],
}

选项

threshold

• 类型：number
• 默认值：100
• 详情：滚动距离阈值，用于显示返回顶部按钮（单位：像素）

progress

• 类型：boolean
• 默认值：true
• 详情：是否显示滚动进度

样式

你可以通过 CSS 变量来自定义 返回顶部 按钮的样式：

@use 'pkg:@vuepress/helper';

$back-to-top-icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48"><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="4" d="M24.008 14.1V42M12 26l12-12 12 12M12 6h24"/></svg>';

:root {
  --back-to-top-z-index: 5;
  --back-to-top-icon: #{helper.encode-svg($back-to-top-icon)};
  --back-to-top-c-bg: var(--vp-c-bg);
  --back-to-top-c-accent-bg: var(--vp-c-accent-bg);
  --back-to-top-c-accent-hover: var(--vp-c-accent-hover);
  --back-to-top-c-shadow: var(--vp-c-shadow);
  --back-to-top-c-icon: currentcolor;
}

使用方法

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

该插件已集成到默认主题中。

使用

npm i -D @vuepress/plugin-copy-code@next

import { copyCodePlugin } from '@vuepress/plugin-copy-code'

export default {
  plugins: [
    copyCodePlugin({
      // options
    }),
  ],
}

选项

selector

• 类型：string | string[]

• 默认值：'[vp-content] div[class*="language-"] pre'

• 详情：

  代码块的 CSS 选择器，用于确定需添加复制按钮的代码块范围

showInMobile

• 类型：boolean

• 默认值：false

• 详情：

  是否在移动端设备上显示复制按钮。默认情况下，移动端不显示复制按钮以避免干扰内容浏览

duration

• 类型：number

• 默认值：2000

• 详情：

  复制成功提示消息的显示时间（毫秒）。设置为 0 将禁用提示信息

ignoreSelector

• 类型：string[] | string

• 默认值：""

• 详情：

  指定复制代码时需要忽略的元素选择器。匹配的元素在复制时将被排除。

  例如：['.token.comment'] 将在复制时忽略代码块中所有带有类名 .token.comment 的元素（在 prismjs 高亮情况下，这会自动跳过注释内容）

inline

• 类型：string[] | string | boolean

• 默认值：false

• 详情：

  配置行内代码（inline code）的双击复制功能：

  • 设置为 true：启用默认选择器 '[vp-content] :not(pre) > code' 匹配行内代码元素
  • 设置为 false：禁用行内代码双击复制功能
  • 设置为自定义选择器：使用指定的选择器匹配行内代码元素

transform

• 类型：(preElement: HTMLPreElement) => void

• 详情：

  一个转换器，用于在复制之前对 <pre> 中代码块内容进行修改。该选项仅在使用 useCopyCode() 时有效。

• 示例：

  .vuepress/client.ts

  import { useCopyCode } from '@vuepress/plugin-copy-code/client'
  
  export default {
    setup() {
      useCopyCode({
        transform: (preElement) => {
          // 删除 `.ignore` 类名的元素
          preElement.querySelectorAll('.ignore').forEach((el) => el.remove())
          // 插入版权信息
          preElement.innerHTML += `\n Copied by VuePress`
        },
        // ...其它选项
      })
    },
  }

locales

• 类型：CopyCodePluginLocaleConfig

  interface CopyCodePluginLocaleData {
    /**
     * 复制文字
     */
    copy: string
  
    /**
     * 已复制文字
     */
    copied: string
  }
  
  interface CopyCodePluginLocaleConfig {
    [localePath: string]: Partial<CopyCodePluginLocaleData>
  }

• 详情：

  复制按钮插件的国际化配置。

• 示例：

  .vuepress/config.ts

  import { copyCodePlugin } from '@vuepress/plugin-copy-code'
  
  export default {
    locales: {
      '/': {
        // 这是一个支持的语言
        lang: 'zh-CN',
      },
      '/xx/': {
        // 这是一个没有收到插件支持的语言
        lang: 'mm-NN',
      },
    },
  
    plugins: [
      copyCodePlugin({
        locales: {
          '/': {
            // 覆盖复制按钮标签文字
            copy: '复制此段代码',
          },
  
          '/xx/': {
            // 在这里完整设置 `mm-NN` 的多语言配置
          },
        },
      }),
    ],
  }

样式

你可以通过 CSS 变量来自定义复制按钮的样式：

@use 'pkg:@vuepress/helper';

$copy-icon: '<svg viewBox="0 0 24 24"><path fill="none" stroke="#808080" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" d="M9 5H7a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V7a2 2 0 0 0-2-2h-2M9 5a2 2 0 0 0 2 2h2a2 2 0 0 0 2-2M9 5a2 2 0 0 1 2-2h2a2 2 0 0 1 2 2"/></svg>';
$copied-icon: '<svg viewBox="0 0 24 24"><path fill="none" stroke="#808080" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" d="M9 5H7a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V7a2 2 0 0 0-2-2h-2M9 5a2 2 0 0 0 2 2h2a2 2 0 0 0 2-2M9 5a2 2 0 0 1 2-2h2a2 2 0 0 1 2 2m-6 9l2 2 4-4"/></svg>';

:root {

使用

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

import { copyrightPlugin } from '@vuepress/plugin-copyright'

export default {
  plugins: [
    copyrightPlugin({
      // options
    }),
  ],
}

启用版权信息

此插件默认全局禁用。你可以:

• 在特定页面的 frontmatter 中设置 copy: true 手动开启。
• 在插件选项中设置 global: true 让其全局生效，并在页面的 frontmatter 中设置 copy: false 禁用它。

处于不打扰用户的考虑，默认配置下仅当复制长度超过 100 时才会追加版权信息。如果你希望改变这个触发值，你可以插件选项中设置 triggerLength，或在页面 frontmatter 单独设置 copy.triggerLength。

你可以通过插件的 author 和 license 选项设置全局作者和协议信息。

如果文档的不同部分拥有不同的作者和协议，你可以通过 authorGetter 和 licenseGetter 传入一个使用当前页面对象作为参数的函数 (page: Page) => string 并通过它返回相应信息。

插件会默认通过模板从作者、协议和页面链接生成版权信息，并在复制时追加。如果你认为这不够灵活，你可以设置 copyrightGetter 返回一个完全由你自定义的版权信息，或返回 null 以使用默认模板。

禁用复制和选择

如果你希望禁止用户复制较长内容，你可以在插件选项中设置 maxLength 控制这个临界值，或在页面 frontmatter 中设置 copy.maxLength。

• 如果你不希望用户复制你的整个站点或特定页面文字，你可以在插件选项中设置 disableCopy 或在页面 frontmatter 中设置 copy.disableCopy 来禁用复制。后者具有更高优先级。
• 如果你不希望用户选择你的整个站点或特定页面文字，你可以在插件选项中设置 disableSelection 或在页面 frontmatter 中设置 copy.disableSelection 来禁用文字选择。后者具有更高优先级。

选项

author

• 类型：string
• 详情：默认作者信息

license

• 类型：string
• 详情：默认协议信息

authorGetter

• 类型：(page: Page) => string | null
• 详情：作者信息获取器

licenseGetter

• 类型：(page: Page) => string | null
• 详情：协议信息获取器

copyrightGetter

• 类型：(page: Page) => string | null
• 详情：版权信息获取器

canonical

• 类型：string

• 详情：首选部署位置

  例子

  如果你在 https://myblog.com 和 https://blog.com/username/ 下部署相同的内容，你可能希望选择一个站点作为首选链接。

  • 如果你倾向于使用第一个，你应该将 canonical 设置为 https://myblog.com
  • 如果你倾向于使用第二个，你应该将 canonical 设置为 https://blog.com/username/

  这样，在另一个站点触发的版权信息也会指向你的首选站点。

global

• 类型：boolean
• 默认值：false
• 详情：是否全局启用

disableCopy

• 类型：boolean
• 默认值：false
• 详情：禁用复制

disableSelection

• 类型：boolean
• 默认值：false
• 详情：禁用选择

triggerLength

• 类型：number
• 默认值：100
• 详情：触发附加版权的最小内容长度

maxLength

• 类型：number
• 默认值：0
• 详情：允许复制的最大内容长度，0 意味着无限制

locales

• 类型：CopyrightPluginLocaleConfig

  interface CopyrightPluginLocaleData {
    /**
     * 作者文字
     *
     * `:author` 将会被作者替换
     */
    author: string
  
    /**
     * 协议文字
     *
     * `:license` 会被当前协议替换
     */
    license: string
  
    /**
     * 链接文字
     *
     * `:link` 会替换为当前页面链接
     */
    link: string
  }
  
  interface CopyrightPluginLocaleConfig {
    [localePath: string]: Partial<CopyrightPluginLocaleData>
  }

• 详情：版权插件的国际化配置。

• 示例：

  .vuepress/config.ts

  import { copyrightPlugin } from '@vuepress/plugin-copyright'
  
  export default {
    locales: {
      '/': {
        // this is a supported language
        lang: 'en-US',
      },
      '/xx/': {
        // the plugin does not support this language
        lang: 'mm-NN',
      },
    },
  
    plugins: [
      copyrightPlugin({
        locales: {
          '/': {
            // Override link text
            link: 'Original posted at :link',
          },
  
          '/xx/': {
            // Complete locale config for `mm-NN` language here
          },
        },
      }),
    ],
  }

Frontmatter

copy.triggerLength

• 类型：number
• 默认值：100
• 详情：触发附加版权的最小内容长度

copy.maxLength

• 类型：number
• 默认值：0
• 详情：允许复制的最大内容长度，0 意味着无限制

copy.disableCopy

• 类型：boolean
• 默认值：false
• 详情：禁用复制

copy.disableSelection

• 类型：boolean
• 默认值：false
• 详情：禁用选择

使用

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

import { iconPlugin } from '@vuepress/plugin-icon'

export default {
  plugins: [
    iconPlugin({
      // 选项
    }),
  ],
}

我们支持多种类型的图标：

• iconify（默认）
• fontawesome
• iconfont

此外，你也可以使用任何图像链接作为图标（不支持相对链接）。

如果你想要一个新的图标类型，请提交一个议题或提交 PR。

在 Markdown 中，你可以使用 ::icon decorators... =size /color key=value complex-key="complex value"...:: 插入自定义图标。

• 以 = 开头的字符串将被视为尺寸定义。
• 以 / 开头的字符串将被视为颜色定义。
• 任何本身是有效 html 属性的字符串将被解析、标准化并添加到图标元素中。
• 其余部分将被视为图标名称。

::icon =16 /red:: <!-- <VPIcon icon="icon" color="red" size="16px" /> -->

::icon rotate vertical-align=middle:: <!-- <VPIcon icon="icon rotate" vertical-align="middle" /> -->

图标类型

Iconify

有关完整的图标列表，请参见 https://icon-sets.iconify.design/。要使用图标，请复制选择器中的 iconify-icon 的图标名称。

此外，iconify 支持以下属性：

• mode：svg（默认）style bg 或 mask 以更改渲染图标模式
• inline：false 以禁用内联图标
• flip：horizontal 或 vertical 以翻转图标
• rotate：90、180、270 以旋转图标

如果你主要使用 1 个图标集，可以将前缀设置为图标集名称（例如：mdi:），然后你可以使用图标名称而无需前缀。手动声明完整图标名称将覆盖前缀：

::home:: <!-- mdi:home -->
::svg-spinners:180-ring:: <!-- svg-spinners:180-ring -->

Font Awesome

有关免费图标列表，请参见 https://fontawesome.com/v6/search?o=r&m=free。要使用图标，请复制选择器中的图标名称。

fontawesome 关键字仅包括免费的实心和常规图标。如果要使用品牌图标，则需要使用 fontawesome-with-brands 关键字。

实心图标可以直接使用。如果要使用常规或品牌图标，则需要在图标名称前添加 regular: 或 brands: 前缀：

::home:: <!-- fas fa-home (实心是默认的) -->
::solid:home:: <!-- fas fa-home -->
::regular:heart:: <!-- far fa-heart -->
::brands:apple:: <!-- fab fa-apple -->

此外，还支持三个字母前缀、第一个字母或完整类名：

::s:home:: <!-- fas fa-home -->
::fas:home:: <!-- fas fa-home -->
::fa-solid:home:: <!-- fa-solid fa-home -->

::b:apple:: <!-- fab fa-apple -->
::fab:apple:: <!-- fab fa-apple -->
::fa-brands:apple:: <!-- fa-brands fa-apple -->

::r:heart:: <!-- far fa-heart -->
::far:heart:: <!-- far fa-heart -->
::fa-regular:heart:: <!-- fa-regular fa-heart -->

你可以在图标名称后添加其他 fontawesome 支持的类，并用空格分隔，其中 fa- 前缀是可选的：

<!-- 一个小尺寸 icon -->

::home fa-sm:: <!-- fas fa-home fa-sm -->

<!-- 旋转 180° -->

::home rotate-180:: <!-- fas fa-home fa-rotate-180 -->

有关所有可用类的详细信息，请参见 https://docs.fontawesome.com/web/style/styling。

Iconfont

Iconfont 是阿里妈妈 MUX 创建的矢量图标管理和交流平台。

每个设计师都可以将图标上传到 Iconfont 平台，用户可以从这些图标中创建项目。项目可以以各种格式使用。

生成自己的 Iconfont 链接

创建项目

首先，你需要创建一个新项目来设置和管理你网站的图标：

1. 登录 Iconfont。
2. 在网站顶部找到 "资源管理 → 我的项目"，点击右上角的 "新建项目" 图标。
3. 设置一个可识别的项目名称。
4. 使用 FontClass/Symbol 前缀 填写 icon-。你也可以根据自己的喜好填写，但是你需要在前面加上一个额外的 "iconfont" 类手动设置这个值为 prefix 选项，例如：iconfont icon-。

导入图标

搜索并找到你想要使用的图标，点击图标上的 "添加到图标库" 按钮。

当你完成搜索后，点击右上角的 "添加到图库" 图标，点击下面的 "添加到项目"，选择你创建的项目然后确认。

编辑图标

在项目页面上，你可以编辑项目中的图标，包括调整位置、大小、旋转、颜色、Unicode 编码和字体类/符号。

生成链接

点击项目上方的 "字体类" 按钮，然后点击 "生成链接"。

然后使用生成的链接设置 assets 选项。

图片

任何图标类型都支持图像链接（不支持相对链接）。

<!-- 完整链接 -->

::https://example.com/icon.png::

<!-- icon.png 应该放在 .vuepress/public 文件夹中 -->

<VPIcon icon="/icon.png" /> <!-- ::/icon.png:: 是不被支持的，因为它会被解析为颜色 -->

选项

assets

• 类型：IconAsset

  export type BuiltInIcon =
    | 'fontawesome-with-brands'
    | 'fontawesome'
    | 'iconify'
  
  export type IconLink =
    | `//${string}`
    | `/${string}`
    | `http://${string}`
    | `https://${string}`
  
  export type IconAsset = (BuiltInIcon | IconLink)[] | BuiltInIcon | IconLink

• 默认值："iconify"

• 详情：

  要使用的图标资源。

  支持以下关键字，你可以使用其他 CDN 链接甚至你自己的：

  • iconify：Iconify
  • fontawesome：仅限 Font Awesome 免费图标
  • fontawesome-with-brands：Font Awesome 免费图标和品牌图标

type

• 类型：IconType

  export type IconType = 'fontawesome' | 'iconfont' | 'iconify' | 'unknown'

• 默认值：从 assets 中推断

• 详情：

  图标的类型，插件将尝试从资源中推断类型，并回退到 unknown。

  特别地，插件可以识别：

  • iconfont css 链接
  • fontawesome kits
  • fontawesome 和 iconify 的 CDN 链接

prefix

• 类型：string

• 默认值：从 assets 和 type 推断

• 详情：

  图标组件的前缀。默认情况下，插件将使用：

  • iconfont icon- 用于 iconfont 类型
  • 空字符串用于所有其他类型

component

• 类型：string
• 默认值："VPIcon"
• 详情：图标组件的名称

markdown

• 类型：boolean
• 默认值：true
• 详情：是否在 Markdown 中启用图标语法（::icon::）

组件属性

icon

• 类型：string
• 必填：是
• 详情：图标名称

color

• 类型：string
• 默认值："inherit"
• 详情：图标颜色

size

• 类型：number | string
• 默认值：当前字体大小
• 详情：图标尺寸

verticalAlign

• 类型：string
• 默认值："-0.125em"
• 详情：图标垂直对齐方式

sizing

• 类型："width" | "height" | "both"
• 默认值："height"
• 详情：图标尺寸调整方式
  • width：仅设置宽度
  • height：仅设置高度
  • both：设置宽度和高度

该插件已经集成到默认主题中。

使用方法

npm i -D @vuepress/plugin-medium-zoom@next

import { mediumZoomPlugin } from '@vuepress/plugin-medium-zoom'

export default {
  plugins: [
    mediumZoomPlugin({
      // 配置项
    }),
  ],
}

配置项

selector

• 类型：string

• 默认值：'[vp-content] > img, [vp-content] :not(a) > img'

• 详情：

  可缩放图片的选择器。

  默认情况下，该插件会使 <a> 标签以外的所有图片都支持缩放。

zoomOptions

• 类型：Object

• 详情：

  medium-zoom 的配置项。

• 参考：

  • medium-zoom > Options

样式

你可以通过 zoomOptions 对大部分缩放样式进行自定义，该插件还提供了一些 CSS 变量用于补充自定义：

:root {
  --medium-zoom-z-index: 100;
  --medium-zoom-c-bg: var(--vp-c-bg-elv, #fff);
  --medium-zoom-opacity: 1;
}

Composition API

useMediumZoom

• 详情：

  返回该插件使用的 Zoom 实例，便于你直接使用实例上的 methods。

  该插件会在切换路由进入当前页面时使图片支持缩放。但如果你要动态添加新图片，那么你可能就需要这个方法来让这些新图片也支持缩放。

  该插件在 Zoom 实例上额外添加了一个 refresh 方法，它将使用 selector 作为默认参数，先调用 zoom.detach() 再调用 zoom.attach()，便于你快速刷新当前页面图片的缩放状态。

• 示例：

import { useMediumZoom } from '@vuepress/plugin-medium-zoom/client'
import { nextTick } from 'vue'

export default {
  setup(): void {
    const zoom = useMediumZoom()

    // ... 进行了一些操作，在当前页面添加了新的图片

    // 此时你可能需要手动调用 `refresh` 来让这些新图片支持缩放
    nextTick(() => {
      zoom.refresh()
    })
  },
}

使用

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

import { noticePlugin } from '@vuepress/plugin-notice'

export default {
  plugins: [
    noticePlugin({
      // 选项
    }),
  ],
}

你可以为站点的不同路径设置多个通知。

每个通知配置需要包含一个 path 或 match 选项，用于匹配路径。path 选项为字符串，匹配所有以此开头的路径，match 选项为正则表达式，用于测试页面路由路径。

一个通知配置包括:

• title: 通知标题，支持文本和 HTMLString

• content: 通知内容，支持文本、HTMLString 和 Markdown

  • 使用 Markdown 作为内容时，应设置 contentType 为 markdown
  • 还可以使用 contentFile 指定文件绝对路径，文件格式为 .md 或 .html，从文件中读取通知内容。

• actions: 通知操作

  应该是包含以下内容的对象数组:

  • text: 动作文本

  • link (可选): 操作链接。

    路径名会被当作内部路由链接处理，完整 URL 会被当作外部链接在新窗口打开。

  • type (可选): "default" 或 "primary"

    默认值为 "default"。

这是一个例子:

import { noticePlugin } from '@vuepress/plugin-notice'
import { path } from 'vuepress/utils'

export default {
  plugins: [
    noticePlugin({
      config: [
        {
          path: '/',
          title: 'Notice Title',
          content: 'Notice Content',
          actions: [
            {
              text: 'Primary Action',
              link: 'https://theme-hope.vuejs.press/',
              type: 'primary',
            },
            { text: 'Default Action' },
          ],
        },
        {
          path: '/zh/',
          title: 'Notice Title',
          contentType: 'markdown',
          content: '**Notice Content** [link](https://example.com)',
          actions: [
            {
              text: 'Primary Action',
              link: 'https://theme-hope.vuejs.press/',
              type: 'primary',
            },
            { text: 'Default Action' },
          ],
        },
        {
          path: '/example/',
          title: 'Notice Title',
          contentFile: path.resolve(__dirname, 'notice.md'),
          actions: [
            {
              text: 'Primary Action',
              link: 'https://theme-hope.vuejs.press/',
              type: 'primary',
            },
            { text: 'Default Action' },
          ],
        },
      ],
    }),
  ],
}

此外，我们还为你提供了一些高级选项来控制通知显示。

选项

config

• 类型：NoticeOptions[]

  interface NoticeItemOptions {
    /**
     * 通知标题
     */
    title: string
  
    /**
     * 通知内容
     */
    content?: string
  
    /**
     * 通知内容类型
     * @default 'html'
     */
    contentType?: 'html' | 'markdown'
  
    /**
     * 通知内容文件绝对路径, 文件格式支持 `.md` 或 `.html`
     * 优先使用文件内容作为 `content`
     * @example '/path/to/notice.md'
     */
    contentFile?: string
  
    /**
     * 通知键值
     *
     * 用于标识和存储通知的状态
     */
    key?: string
  
    /**
     * 是否只显示一次通知
     *
     * @default false
     */
    showOnce?: boolean
  
    /**
     * 通知是否需要确认
     *
     * @default false
     */
    confirm?: boolean
  
    /**
     * 通知是否应该全屏显示
     *
     * @default false
     */
    fullscreen?: boolean
  
    /**
     * 通知操作
     */
    actions?: NoticeActionOption[]
  }
  
  interface NoticePathOptions extends NoticeItemOptions {
    /**
     * 路径前缀匹配
     */
    path: string
  }
  
  interface NoticeMatchOptions extends NoticeItemOptions {
    /**
     * 匹配通知路径的正则表达式
     */
    match: RegExp
  }
  
  type NoticeOptions = NoticeMatchOptions | NoticePathOptions

• 详情：

  通知配置

该插件已经集成到默认主题中。

使用方法

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

import { nprogressPlugin } from '@vuepress/plugin-nprogress'

export default {
  plugins: [nprogressPlugin()],
}

样式

你可以通过 CSS 变量来自定义进度条的样式：

:root {
  --nprogress-c: var(--vp-c-accent);
  --nprogress-z-index: 1031;
}

使用方法

npm i -D @vuepress/plugin-photo-swipe@next

import { photoSwipePlugin } from '@vuepress/plugin-photo-swipe'

export default {
  plugins: [
    photoSwipePlugin({
      // 选项
    }),
  ],
}

在图片预览模式中，你可以:

• 左右滑动按顺序浏览页面内其他的图片
• 查看图片的描述
• 对图片进行缩放
• 全屏浏览图片
• 下载图片
• 分享图片

选项

selector

• 类型：string | string[]
• 默认值："[vp-content] :not(a) > img:not([no-view])"
• 详情：图片选择器

download

• 类型：boolean
• 默认值：true
• 详情：是否显示下载按钮

fullscreen

• 类型：boolean
• 默认值：true
• 详情：是否显示全屏按钮

scrollToClose

• 类型：boolean
• 默认值：true
• 详情：是否在滚动时关闭当前图片

locales

• 类型：PhotoSwipePluginLocaleConfig

  interface PhotoSwipePluginLocaleData {
    /**
     * 关闭按钮标签文字
     */
    close: string
  
    /**
     * 下载按钮标签文字
     */
    download: string
  
    /**
     * 全屏按钮标签文字
     */
    fullscreen: string
  
    /**
     * 缩放按钮标签文字
     */
    zoom: string
  
    /**
     * 上一张图片按钮标签文字
     */
    arrowPrev: string
  
    /**
     * 下一张图片按钮标签文字
     */
    arrowNext: string
  }
  
  interface PhotoSwipePluginLocaleConfig {
    [localePath: string]: Partial<PhotoSwipePluginLocaleData>
  }

• 详情：Photo Swipe 插件的国际化配置

• 示例：

  .vuepress/config.ts

  import { photoSwipePlugin } from '@vuepress/plugin-photo-swipe'
  import { defineUserConfig } from 'vuepress'
  
  export default defineUserConfig({
    locales: {
      '/': {
        // 这是一个支持的语言
        lang: 'zh-CN',
      },
      '/xx/': {
        // 插件不支持这个语言
        lang: 'mm-NN',
      },
    },
  
    plugins: [
      photoSwipePlugin({
        locales: {
          '/': {
            // 覆盖关闭标签文字
            close: '关闭图片',
          },
  
          '/xx/': {
            // 在这里完整设置 `mm-NN` 的多语言配置
          },
        },
      }),
    ],
  })

Frontmatter

photoSwipe

• 类型：string | false
• 详情：当前页面的图片选择器，或 false 以在当前页面禁用 photo-swipe

客户端配置

definePhotoSwipeConfig

传递给 photo-swipe 的选项

import { definePhotoSwipeConfig } from '@vuepress/plugin-photo-swipe/client'

definePhotoSwipeConfig({
  // 在此设置 PhotoSwipe 选项
})

API

你也可以通过 API 调用 PhotoSwipe。

createPhotoSwipe 允许你以编程方式使用 PhotoSwipe 查看图片链接：

<script setup lang="ts">
import { createPhotoSwipe } from '@vuepress/plugin-photo-swipe/client'
import { onMounted, onUnmounted } from 'vue'

let state: PhotoSwipeState | null = null

const openPhotoSwipe = (index: number): void => {
  state?.open(index - 1)
}

onMounted(async () => {
  // 通过图片链接创建一个新的 PhotoSwipe 实例
  state = await createPhotoSwipe(
    [
      'https://example.com/image1.png',
      'https://example.com/image2.png',
      'https://example.com/image3.png',
    ],
    {
      // PhotoSwipe 选项
    },
  )
})

onUnmounted(() => {
  state?.destroy()
})
</script>

<template>
  <button v-for="i in 3" :key="i" type="button" @click="openPhotoSwipe(i)">
    打开图片 {{ i }}
  </button>
</template>

样式

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

:root {
  --photo-swipe-c-bullet: var(--vp-c-bg-elv);
  --photo-swipe-c-bullet-active: var(--vp-c-accent);
}

此插件可在页面中添加水印，你可以选择为全局页面或部分页面添加水印，还可以选择添加文字水印或图片水印。

使用

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

import { watermarkPlugin } from '@vuepress/plugin-watermark'

export default {
  plugins: [
    watermarkPlugin({
      enabled: true,
      watermarkOptions: {
        content: 'My Site',
      },
    }),
  ],
}

配置项

enabled

• 类型：boolean | ((page: Page) => boolean)

• 默认值：true

• 详情：

  指定哪些页面需要添加水印。

  拥有 true 值的页面将会被添加水印。

watermarkOptions

• 类型：WatermarkOptions

• 默认值：undefined

• 详情：配置项请参考 watermark-js-plus。

watermarkOptions.parent

• 类型：string

• 默认值：'body'

• 详情：添加水印的父元素选择器。

  默认插入到 body 中，可以指定插入到页面的某个元素中。

Frontmatter

watermark

• 类型：boolean | WatermarkOptions

• 详情：

  当类型为 boolean 时，表示是否启用水印。

  当类型为 WatermarkOptions 时，表示当前页面水印配置。

  可以参考 watermark-js-plus 。

Usage

npm i -D @vuepress/plugin-baidu-analytics@next

import { baiduAnalyticsPlugin } from '@vuepress/plugin-baidu-analytics'

export default {
  plugins: [
    baiduAnalyticsPlugin({
      // 选项s
    }),
  ],
}

事件追踪

配置完成后，插件会自动在用户访问页面及路由切换时上报页面浏览（PV）事件。

对于更高级的统计需求，百度统计的全局对象 _hmt 已挂载在 window 对象上。你可以通过它来手动上报自定义事件。

// 示例：手动上报一个自定义事件
window._hmt = window._hmt || []
window._hmt.push(['_trackEvent', 'category', 'action', 'label', 'value'])

选项

id

• 类型：string
• 必填：是
• 详情：百度统计的 ID。通常是百度统计提供的代码中 hm.js 链接后的字符串参数（例如 hm.js?your_tracking_id）。

使用方法

npm i -D @vuepress/plugin-clarity-analytics@next

import { clarityAnalyticsPlugin } from '@vuepress/plugin-clarity-analytics'

export default {
  plugins: [
    clarityAnalyticsPlugin({
      // 选项
    }),
  ],
}

功能介绍

Microsoft Clarity 是一款免费且易用的行为分析工具，旨在帮助你深入了解用户如何与网站进行交互。本插件简化了集成流程，无需复杂的配置即可获取可付诸行动的洞察数据。

主要功能包括：

• 会话录像 (Session Recordings)： 完整回放用户会话，直观地查看用户在网站上的浏览路径与操作细节。
• 热力图 (Heatmaps)： 通过可视化点击、滚动和区域互动数据，精准识别用户最关注的内容区域。
• 智能洞察 (Smart Insights)： 利用 Copilot 的 AI 分析能力，快速总结用户行为模式与趋势。

如需了解更多功能详情，请参阅 Clarity 功能概览。

高级用法

插件启用后，全局 window 对象上将暴露 clarity() 函数。你可以通过该函数调用 Clarity Client API 来处理高级任务，例如：

• 识别特定用户身份。
• 追踪自定义事件 (Custom Events)。
• 管理 Cookie 同意状态。

选项

id

• 类型：string
• 必填：是
• 详情：Microsoft Clarity 分配的项目 ID (Project ID)。你可以在 Clarity 控制台的“设置 (Settings)”页面中找到此 ID。

crossOrigin

• 类型：string
• 默认值：undefined
• 详情：注入脚本标签的 crossorigin 属性。用于配置加载 Clarity 资源时的 CORS 设置。

该插件通过引入 Global Site Tag (gtag.js) 来支持强大的流量分析与用户追踪功能。

Usage

npm i -D @vuepress/plugin-google-analytics@next

import { googleAnalyticsPlugin } from '@vuepress/plugin-google-analytics'

export default {
  plugins: [
    googleAnalyticsPlugin({
      // 选项
    }),
  ],
}

上报事件

Google Analytics 4 默认自动收集多种事件，例如 page_view（页面浏览）、first_visit（首次访问）和 scroll（滚动）等。

如果你只需要收集基础的站点数据，只需配置正确的 Measurement ID（测定 ID）即可。

如需更高级的追踪能力，该插件会在 window 对象上暴露全局 gtag() 函数。你可以利用该函数，基于用户在站点内的交互行为，通过编程方式上报自定义事件。

Options

id

• 类型：string

• 必填：是

• 详情：

  Google Analytics 4 的测定 ID（Measurement ID），通常以 'G-' 开头。

  请参考官方指南查找你的测定 ID。请注意区分 Google Analytics 4 的测定 ID（"G-" ID）与 Universal Analytics 的追踪 ID（"UA-" ID）。

• 示例：

  .vuepress/config.ts

  export default {
    plugins: [
      googleAnalyticsPlugin({
        id: 'G-XXXXXXXXXX',
      }),
    ],
  }

debug

• 类型：boolean

• 详情：
  设置为 true 以启用向 Google Analytics DebugView 发送事件的功能。这对于在开发过程中验证配置和调试事件数据非常有用。了解更多关于 DebugView 的信息。

• 示例：

  .vuepress/config.ts

  export default {
    plugins: [
      googleAnalyticsPlugin({
        id: 'G-XXXXXXXXXX',
        debug: true,
      }),
    ],
  }

使用方法

npm i -D @vuepress/plugin-umami-analytics@next

import { umamiAnalyticsPlugin } from '@vuepress/plugin-umami-analytics'

export default {
  plugins: [
    umamiAnalyticsPlugin({
      // 选项
    }),
  ],
}

该插件同时支持 Umami Cloud 和 自托管（Self-host） 实例。

上报事件

插件开箱即用，会自动捕获首次访问和后续路由切换时的页面浏览事件，从而确保单页应用（SPA）流量数据的准确性。

针对高级追踪需求，插件在 window 实例上暴露了全局 umami 对象。你可以通过调用 umami.track() 编程式地触发自定义事件。

选项

id

• 类型：string
• 必填： 是
• 详情： Umami 控制台提供的唯一网站 ID (Website ID)。

link

• 类型：string
• 默认值：'https://us.umami.is/script.js'
• 详情： Umami 追踪脚本的源地址 URL。

autoTrack

• 类型：boolean

• 默认值：true

• 详情：

  控制是否自动追踪页面浏览和事件。

  如果希望禁用自动数据收集并仅依赖手动追踪函数，请将此项设置为 false。

cache

• 类型：boolean

• 详情：

  启用缓存以提高追踪脚本的性能。

  注意： 此功能会使用 Session Storage。根据你所在地区的法规，你可能需要向用户告知这一情况。

domains

• 类型：string[]

• 详情：

  允许的域名列表。只有通过这些特定域名访问站点时，才会进行追踪。

hostUrl

• 类型：string

• 默认值：link

• 详情：

  用于发送分析数据的自定义端点。如果未指定，默认使用 link 中定义的脚本位置。

使用方法

npm i -D @vuepress/plugin-append-date@next

import { appendDatePlugin } from '@vuepress/plugin-append-date'

export default {
  plugins: [appendDatePlugin()],
}

选项

key

• 类型：string
• 默认值："date"
• 详情：追加时间时使用的 frontmatter 键名

format

• 类型："date" | "time" | "full"

• 默认值："date"

• 详情：

  追加时间时使用的日期格式：

  • "date"：YYYY-MM-DD 格式
  • "time"：HH:MM:SS 格式
  • "full"：YYYY-MM-DD HH:MM:SS 格式

此插件已集成到默认主题中。

使用

npm i -D @vuepress/plugin-links-check@next

import { linksCheckPlugin } from '@vuepress/plugin-links-check'

export default {
  plugins: [
    linksCheckPlugin({
      // 选项
    }),
  ],
}

选项

dev

• 类型：boolean

• 默认值：true

• 详情：

  是否在开发服务器中检查 Markdown 中的死链接。

build

• 类型：boolean | 'error'

• 默认值：true

• 详情：

  是否在构建时检查 Markdown 中的死链接。如果设置为 'error'，则在发现死链接时构建将失败。

exclude

• 类型：(string | RegExp)[] | ((link: string, isDev: boolean) => boolean)

• 详情：

  检查时需要排除的链接。你可以使用字符串或正则表达式的列表，或者返回布尔值的函数。

• 示例：

  .vuepress/config.ts

  import { linksCheckPlugin } from '@vuepress/plugin-links-check'
  
  export default {
    plugins: [
      linksCheckPlugin({
        exclude: [
          // 通过字符串排除链接
          '/exclude-link',
          // 通过正则表达式排除链接
          /\/exclude-link-regex/,
        ],
  
        // 或者通过函数排除链接
        exclude: (link, isDev) => {
          if (isDev) {
            return link.startsWith('/exclude-link-dev')
          }
          return link.startsWith('/exclude-link-build')
        },
      }),
    ],
  }

该插件简化了 markdown-it-container 的使用方法，但同时也保留了其原本的能力。

使用方法

npm i -D @vuepress/plugin-markdown-container@next

import { markdownContainerPlugin } from '@vuepress/plugin-markdown-container'

export default {
  plugins: [
    markdownContainerPlugin({
      // 配置项
    }),
  ],
}

容器语法

::: <type> [info]
[content]
:::

• type 是必需的，应通过 type 配置项来指定。
• info 是可选的，其默认值可以通过 locales 的 defaultInfo 配置项来指定。
• content 可以是任何合法的 Markdown 内容。

配置项

type

• 类型：string

• 必填：是

• 详情：

  容器的类型。

  它将会被用作 markdown-it-container 的 name 参数。

locales

• 类型：Record<string, { defaultInfo: string }>

• 默认值：{}

• 详情：

  容器在不同 locales 下的默认 info。

  如果没有指定该配置项，默认 info 会使用大写的 type。

• 示例：

export default {
  plugins: [
    markdownContainerPlugin({
      type: 'tip',
      locales: {
        '/': {
          defaultInfo: 'TIP',
        },
        '/zh/': {
          defaultInfo: '提示',
        },
      },
    }),
  ],
}

• 参考：
  • 指南 > 多语言支持

before

• 类型：(info: string) => string

• 默认值：

  ;(info: string): string =>
    `<div class="custom-container ${type}">${info ? `<p class="custom-container-title">${info}</p>` : ''}\n`

• 详情：

  一个用于渲染容器起始标签的函数。

  第一个参数是 容器语法 的 info 部分。

  如果你没有设置 after 配置项，则该配置项也不会生效。

after

• 类型：(info: string) => string

• 默认值：

  ;(): string => '</div>\n'

• 详情：

  一个用于渲染容器结束标签的函数。

  第一个参数是 容器语法 的 info 部分。

  如果你没有设置 before 配置项，则该配置项也不会生效。

render

• 类型：

  type MarkdownItContainerRenderFunction = (
    tokens: Token[],
    index: number,
    options: unknown,
    env: MarkdownEnv,
    self: Renderer,
  ) => string

• 详情：

  markdown-it-container 的 render 配置项。

  该插件使用了一个默认的 render 函数。但如果你指定了该配置项，那么默认的 render 函数就会被替换掉，此时 locales、before 和 after 配置项都会被忽略。

validate

• 类型：(params: string) => boolean

• 详情：

  markdown-it-container 的 validate 配置项。

marker

• 类型：string

• 默认值：':'

• 详情：

  markdown-it-container 的 marker 配置项。

使用

npm i -D @vuepress/plugin-markdown-ext@next

import { markdownExtPlugin } from '@vuepress/plugin-markdown-ext'

export default {
  plugins: [
    markdownExtPlugin({
      // 选项
    }),
  ],
}

语法

脚注

• 在 Markdown 中使用 [^锚点文字] 来定义脚注。

• 在之后的任何位置使用 [^锚点文字]: ... 来描述脚注内容。

• 如果脚注包含多个段落，其后的段落应当保持双层缩进。

任务列表

• 使用 - [ ] 一些文字 渲染一个未勾选的任务项
• 使用 - [x] 一些文字 渲染一个勾选了的任务项 (我们也支持大写的 X)

组件

你可以使用 component 代码块来在 Markdown 中添加组件。YAML 和 JSON 的数据格式均受支持:

• YAML :

  ```component 组件名称
  # 组件数据
  ```

• JSON:

  ```component 组件名称
  {
    // 组件数据
  }
  ```

v-pre

你可以使用 v-pre 容器来渲染将任何 mustache 语法作为纯文本渲染。

选项

gfm

• 类型：boolean

• 详情：

  是否调整行为和功能，使其更类似于 GitHub Flavored Markdown。

  markdown-it 已经默认支持表格与删除线。如果此选项为 true，则会启用以下新功能：

  • 自动链接（在 markdown-it 中命名为 linkify）
  • 硬换行
  • 脚注
  • 任务列表

  请注意：并不是所有行为都与 GitHub Flavored Markdown 完全相同。

footnote

• 类型：boolean
• 详情：是否启用脚注格式支持。
• 在 GFM 中启用：是

tasklist

• 类型：MarkdownItTaskListOptions | boolean

  interface MarkdownItTaskListOptions {
    /**
     * 是否禁用 checkbox
     *
     * @default true
     */
    disabled?: boolean
  
    /**
     * 是否使用 `<label>` 来包裹文字
     *
     * @default true
     */
    label?: boolean
  }

• 详情：

  是否启用任务列表格式支持。你可以传递一个对象来配置任务列表。

• 在 GFM 中启用：是

breaks

• 类型：boolean
• 详情：是否将段落中的 \n 转换为 <br>。
• 在 GFM 中启用：是

linkify

• 类型：boolean
• 详情：是否将类似 URL 的文本转换为链接。
• 在 GFM 中启用：是

component

• 类型：boolean
• 详情：是否启用组件代码块支持。

vPre

• 类型：boolean
• 详情：是否启用 v-pre 容器支持。

cjkFriendly

• 类型：boolean
• 详情：是否启用对强调标记的 CJK 友好支持。未设置时，检测到 CJK 语言（zh、ja、ko）将自动启用。

使用

npm i -D @vuepress/plugin-markdown-file-tree@next

import { markdownFileTreePlugin } from '@vuepress/plugin-markdown-file-tree'

export default {
  plugins: [markdownFileTreePlugin()],
}

语法

在 ::: file-tree 容器，使用内置的 Markdown 无序列表语法 指定文件和目录的组织结构。
使用嵌套的列表项创建子目录；若希望某个目录不显示具体内容，可在列表项末尾添加斜杠 / 。

以下语法可用于自定义文件树的外观：

• 通过加粗文件名或目录名来突出显示，例如 **README.md**
• 通过在名称后添加以 # 开头的更多文本来为文件或目录添加注释
• 通过在名称前添加 ++ 或 -- 来标记文件或目录为 新增 或 删除
• 使用 ... 或 … 作为名称来添加占位符文件和目录。
• 在 :::file-tree 后空格添加任意文本 可以为文件树添加标题。

示例

输入：

::: file-tree

- docs
  - .vuepress
    - ++ config.ts
  - -- page1.md
  - README.md
- theme # 一个 **主题** 目录
  - client
    - components
      - **Navbar.vue**
    - composables
      - useNavbar.ts
    - styles
      - navbar.css
    - config.ts
  - node/
- package.json
- pnpm-lock.yaml
- .gitignore
- README.md
- …
  :::

输出：

该插件已经集成到默认主题中。

使用方法

npm i -D @vuepress/plugin-markdown-hint@next

import { markdownHintPlugin } from '@vuepress/plugin-markdown-hint'

export default {
  plugins: [
    markdownHintPlugin({
      // 启用提示容器，默认启用
      hint: true,
      // 启用 GFM 警告
      alert: true,
    }),
  ],
}

指南

默认情况下，我们支持 important、info、note、tip、warning、caution、details 容器与 markdown 容器：

要自定义容器的标题，你可以在命名容器后添加标题：

容器可以只包含一个标题：

插件也提供了 alert 选项，以支持 GFM 警告：

> [!note]
> This is note text

> [!important]
> This is important text

> [!tip]
> This is tip text

> [!warning]
> This is warning text

> [!caution]
> This is caution text

选项