6.7 KiB
title, icon, createTime, permalink
| title | icon | createTime | permalink |
|---|---|---|---|
| 内容注释 | iconamoon:comment-add-light | 2025/02/23 10:48:35 | /guide/markdown/annotation/ |
描述
==Annotation(注释)== 是 Markdown 中的一种特殊的语法，用于在文档中添加额外的信息、说明或者提示。
注释不会直接显示在文档中，需要用户手动点击才会显示。
配置
该功能默认不启用，你需要在 theme 配置中启用。
export default defineUserConfig({
theme: plumeTheme({
markdown: {
annotation: true, // [!code ++]
}
})
})
语法
==Annotation(注释)== 语法由两个部分组成：
行内注释
在行内通过 [+label] 语法插入注释标签。
注释标签由 [+ + label + ] 组成。为方便与内容做区分，在 [+label] 的左边边缘应该有一个空格。
label 为注释的标签，可以是任意字符串。
::: important 符号 + 是必须的
:::
定义注释
在文档的单独区域中使用 [+label]: 语法开始定义注释。
注释定义区域由 [+ + label + ]: + 内容 组成。
label 应该与上述的 [+label] 一致，用于标记注释的标签。
内容 可以跟随在 : 之后开始写：
[+label]: 这里是内容，可以使用 **Markdown** 语法。
内容 也可以从下一行开始写，但需要添加缩进，多行时应该保持一致的缩进。
[+label]:
这里是内容。
缩进一致，此行也是内容。
即使上一行空行，但此行缩进也是一致的，也是内容。
可以使用 **Markdown** 语法。
此行不再缩进，该标签的注释定义在上一行结束。
定义注释的内容不会直接渲染在文档中，而是在 行内注释 的 [+label] 被点击后呈现。
示例
示例一
输入：
站点由 VuePress [+vuepress] 驱动。
[+vuepress]:
VuePress 是一个 [静态站点生成器](https://en.wikipedia.org/wiki/Static_site_generator) (SSG) 。
专为构建快速、以内容为中心的站点而设计。
输出：
站点由 VuePress [+vuepress] 驱动。
[+vuepress]: VuePress 是一个 静态站点生成器 (SSG) 。 专为构建快速、以内容为中心的站点而设计。
示例二
同一个 label 定义多个注释，多个定义以列表的形式渲染。
输入：
中国古代 **四大名著** [+名著] 家喻户晓。
[+名著]:
**《三国演义》：**
以三国时期的历史为背景，描写了魏、蜀、吴三国之间的政治、军事斗争，塑造了诸葛亮、曹操、关羽、刘备等众多历史人物形象。
[+名著]:
**《西游记》：**
讲述了唐僧师徒四人（孙悟空、猪八戒、沙僧、白龙马）西天取经的故事，充满了神话色彩和奇幻冒险。
[+名著]:
**《红楼梦》：**
以贾、史、王、薛四大家族的兴衰为背景，描写了贾宝玉、林黛玉、薛宝钗等人的爱情悲剧，展现了封建社会的腐朽与没落。
[+名著]:
**《水浒传》：**
描写了北宋末年以宋江为首的108位好汉在梁山泊聚义，反抗朝廷的故事，展现了官逼民反的社会现实。
输出：
中国古代 四大名著 +名著 家喻户晓。
以三国时期的历史为背景，描写了魏、蜀、吴三国之间的政治、军事斗争，塑造了诸葛亮、曹操、关羽、刘备等众多历史人物形象。
讲述了唐僧师徒四人（孙悟空、猪八戒、沙僧、白龙马）西天取经的故事，充满了神话色彩和奇幻冒险。
以贾、史、王、薛四大家族的兴衰为背景，描写了贾宝玉、林黛玉、薛宝钗等人的爱情悲剧，展现了封建社会的腐朽与没落。
描写了北宋末年以宋江为首的108位好汉在梁山泊聚义，反抗朝廷的故事，展现了官逼民反的社会现实。
全局预设
为了方便使用，可以在配置中预设一些常用的内容注释，从而避免在每个 markdown 文件中重复定义。
export default defineUserConfig({
theme: plumeTheme({
markdown: {
annotation: {
vuepress: 'VuePress 是一个 [静态站点生成器](https://en.wikipedia.org/wiki/Static_site_generator) (SSG) 。专为构建快速、以内容为中心的站点而设计。',
名著: [
'**《三国演义》：**\n以三国时期的历史为背景，描写了魏、蜀、吴三国之间的政治、军事斗争，塑造了诸葛亮、曹操、关羽、刘备等众多历史人物形象。',
'**《西游记》：**\n讲述了唐僧师徒四人（孙悟空、猪八戒、沙僧、白龙马）西天取经的故事，充满了神话色彩和奇幻冒险。',
'**《红楼梦》：**\n以贾、史、王、薛四大家族的兴衰为背景，描写了贾宝玉、林黛玉、薛宝钗等人的爱情悲剧，展现了封建社会的腐朽与没落。',
'**《水浒传》：**\n描写了北宋末年以宋江为首的108位好汉在梁山泊聚义，反抗朝廷的故事，展现了官逼民反的社会现实。',
],
}
}
})
})
也可以通过 markdown.env 配置 annotations 选项来实现。
export default defineUserConfig({
theme: plumeTheme({
markdown: {
env: {
annotations: {
vuepress: 'VuePress 是一个 [静态站点生成器](https://en.wikipedia.org/wiki/Static_site_generator) (SSG) 。专为构建快速、以内容为中心的站点而设计。',
名著: [
'**《三国演义》：**\n以三国时期的历史为背景，描写了魏、蜀、吴三国之间的政治、军事斗争，塑造了诸葛亮、曹操、关羽、刘备等众多历史人物形象。',
'**《西游记》：**\n讲述了唐僧师徒四人（孙悟空、猪八戒、沙僧、白龙马）西天取经的故事，充满了神话色彩和奇幻冒险。',
'**《红楼梦》：**\n以贾、史、王、薛四大家族的兴衰为背景，描写了贾宝玉、林黛玉、薛宝钗等人的爱情悲剧，展现了封建社会的腐朽与没落。',
'**《水浒传》：**\n描写了北宋末年以宋江为首的108位好汉在梁山泊聚义，反抗朝廷的故事，展现了官逼民反的社会现实。',
],
}
}
}
})
})
全局预设的内容注释可以在任何 markdown 文件中使用。
输入：
中国古代 **四大名著** [+名著] 家喻户晓。
输出：
中国古代 四大名著 +名著 家喻户晓。