注释

注释插件，为 Markdown 中的内容添加可交互的注释标记，点击标记后弹出浮层显示注释内容。

注释内容支持完整的块级 Markdown 语法，同一标签可多次定义，所有定义会作为独立条目展示在浮层中。

安装

pnpm

pnpm add vitepress-plugin-annotation

npm

npm install vitepress-plugin-annotation

bun

bun add vitepress-plugin-annotation

deno

deno add vitepress-plugin-annotation

yarn

yarn add vitepress-plugin-annotation

使用

vitepress-tuck 模式 推荐

.vitepress/config.ts

import { defineConfig } from 'vitepress-tuck'
import annotation from 'vitepress-plugin-annotation'

export default defineConfig({
  plugins: [annotation()],
})

查看 vitepress-tuck 了解更多

传统模式

.vitepress/config.ts

import { defineConfig } from 'vitepress'
import { annotationMarkdownPlugin } from 'vitepress-plugin-annotation'

export default defineConfig({
  markdown: {
    config: (md) => {
      md.use(annotationMarkdownPlugin, {
        HTML: 'HyperText Markup Language',
      })
    },
  },
})

在主题中注册组件：

.vitepress/theme/index.ts

import type { Theme } from 'vitepress'
import { enhanceAppWithAnnotation } from 'vitepress-plugin-annotation/client'
import DefaultTheme from 'vitepress/theme'

export default {
  extends: DefaultTheme,
  enhanceApp(ctx) {
    enhanceAppWithAnnotation(ctx) 
  },
} satisfies Theme

语法

使用 [+标签]: 注释内容 语法定义注释，然后在文档中使用 [+标签] 引用。引用会渲染为一个小的可交互标记，点击后弹出浮层显示注释内容。

中国古代 **四大名著** [+名著] 家喻户晓。

[+名著]: **《三国演义》** — 以三国时期为背景的历史小说。

渲染结果：

中国古代 四大名著 家喻户晓。

注释内容支持块级 Markdown

注释内容支持完整的块级 Markdown 语法，包括标题、段落、列表、代码块等。

该框架基于 [+vue] 构建。

[+vue]:
  ## Vue

  渐进式 JavaScript 框架，用于构建用户界面。

  - 响应式数据绑定
  - 组件化架构
  - [了解更多](https://vuejs.org/)

多行定义

注释定义可以跨多行。续行必须至少缩进两个空格。缩进块内的空行会作为注释内容的一部分被保留。非缩进的内容行（如下一个定义或新段落）会终止多行定义。

这个概念在 [+detail] 中有详细说明。

[+detail]:
  这是注释的第一段。

  这是第二段，中间隔了一个空行，
  但仍然是同一个注释的一部分。

这一行没有缩进，注释定义到此结束。

多次定义同一标签

同一标签可以多次定义。所有定义会被收集并作为独立条目展示在浮层中，适合为同一引用提供多条相关信息。

JavaScript 有多个版本 [+js]。

[+js]: **ES2015 (ES6)** — 引入了类、模块、箭头函数等。

[+js]: **ES2020** — 新增了可选链、空值合并运算符、BigInt 等。

渲染结果：

JavaScript 有多个版本 。

全局注释

除了在每个 Markdown 文件中内联定义注释外，还可以通过插件选项配置全局注释预设。这对于需要在所有页面中一致注释的术语很有用。

.vitepress/config.ts

import { defineConfig } from 'vitepress-tuck'
import annotation from 'vitepress-plugin-annotation'

export default defineConfig({
  plugins: [
    annotation({
      HTML: 'HyperText Markup Language',
      CSS: ['Cascading Style Sheets', '一种用于描述文档表现的样式表语言。'],
    }),
  ],
})

每个全局注释值可以是字符串或字符串数组。当提供数组时，每个元素成为浮层中的一个独立条目，就像同一标签的多个内联定义一样。

示例

点击下方注释标记，查看完整内容：

中国古代 **四大名著** [+名著] 家喻户晓。

[+名著]:
  **《三国演义》：**

  以三国时期的历史为背景，描写了魏、蜀、吴三国之间的政治、军事斗争。

[+名著]:
  **《西游记》：**

  讲述了唐僧师徒四人西天取经的故事，充满了神话色彩和奇幻冒险。

[+名著]:
  **《红楼梦》：**

  以贾、史、王、薛四大家族的兴衰为背景，描写了贾宝玉、林黛玉等人的爱情悲剧。

[+名著]:
  **《水浒传》：**

  描写了北宋末年以宋江为首的 108 位好汉在梁山泊聚义的故事。

中国古代 四大名著 家喻户晓。