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