docs: update docs

2025-02-24 00:33:23 +08:00 · 2025-02-24 00:33:23 +08:00 · b153b90ce6
commit b153b90ce6
parent 1058de5774
5 changed files with 297 additions and 15 deletions
--- a/docs/.vuepress/notes/zh/theme-guide.ts
+++ b/docs/.vuepress/notes/zh/theme-guide.ts
@ -34,11 +34,14 @@ export const themeGuide = defineNoteConfig({
            '基础',
            '扩展',
            '图标',
+            '马克笔',
+            '隐秘文本',
+            '缩写词',
+            '内容注释',
            '卡片',
            '步骤',
            '文件树',
            '选项组',
-            '隐秘文本',
            '示例容器',
            'npm-to',
            'caniuse',
--- a/docs/notes/theme/guide/markdown/内容注释.md
+++ b/docs/notes/theme/guide/markdown/内容注释.md
@ -0,0 +1,82 @@
+---
+title: 内容注释
+icon: iconamoon:comment-add-light
+createTime: 2025/02/23 10:48:35
+permalink: /guide/markdown/annotation/
+---
+
+## 描述
+
+Annotation(注释) 是 Markdown 中的一种特殊的语法，用于在文档中添加额外的信息、说明或者提示。
+
+注释不会直接显示在文档中，需要用户手动点击才会显示。
+
+## 配置
+
+该功能默认不启用，你需要在 `theme` 配置中启用。
+
+::: code-tabs
+@tab .vuepress/config.ts
+
+```ts
+export default defineUserConfig({
+  theme: plumeTheme({
+    plugins: {
+      markdownPower: {
+        annotation: true,
+      },
+    }
+  })
+})
+```
+
+:::
+
+## 语法
+
+Annotation(注释) 语法有两个部分组成：
+
+- **行内注释：** 在行内通过 `[+label]` 语法插入注释。
+- **定义注释：** 在文档单独一行中使用 `[+label]: 内容` 语法定义注释。
+
+::: important 符号 `+` 是必须的
+
+- 行内注释语法由 `[+` + `label` + `]` 组成。
+- 定义注释语法由 `[+` + `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位好汉在梁山泊聚义，反抗朝廷的故事，展现了官逼民反的社会现实。
--- a/docs/notes/theme/guide/markdown/扩展.md
+++ b/docs/notes/theme/guide/markdown/扩展.md
@ -264,20 +264,6 @@ $$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
 | $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t}  = \vec{\mathbf{0}}$                                                          | curl of $\vec{\mathbf{E}}$ is proportional to the rate of change of $\vec{\mathbf{B}}$ |
 | $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}}    \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _wha?_                                                                                 |

-## 标记
-
-使用 `== ==` 进行标记。请注意两边需要有空格。
-
-**输入：**
-
-```md
-vuepress-theme-plume 是一个 ==简洁美观== 的 主题
-```
-
-**输出：**
-
-vuepress-theme-plume 是一个 ==简洁美观== 的 主题
-
 ## 上下角标

 - 使用 `^ ^` 进行上角标标注。
--- a/docs/notes/theme/guide/markdown/缩写词.md
+++ b/docs/notes/theme/guide/markdown/缩写词.md
@ -0,0 +1,61 @@
+---
+title: 缩写词
+icon: mdi:tooltip-question-outline
+createTime: 2025/02/23 10:48:15
+permalink: /guide/markdown/abbreviation/
+---
+
+## 概述
+
+**缩写词** 是指在 Markdown 中使用的简称，例如 一些专业名词如 W3C 、 ECMA 等。
+
+在 鼠标移动到缩写词上时，显示该名词的完整名称，还可以包括缩写词的定义、解释等。
+
+## 配置
+
+该功能默认不启用，你需要在 `theme` 配置中启用。
+
+::: code-tabs
+@tab .vuepress/config.ts
+
+```ts
+export default defineUserConfig({
+  theme: plumeTheme({
+    plugins: {
+      markdownPower: {
+        abbr: true,
+      },
+    }
+  })
+})
+```
+
+:::
+
+## 语法
+
+在 Markdown 中，在单独的一行中使用 `*[缩写词]: 描述` 来定义缩写词，描述可以包括缩写词的定义、解释等。
+
+在 `[]` 中填写缩写词，在 `:` 后面填写描述，在描述中可以使用 Markdown 内联语法。
+
+Markdown 普通文本中如果包含了定义的缩写词，则鼠标移动到该缩写词时自动显示缩写词的解释。
+
+**输入：**
+
+```md
+The HTML specification is maintained by the W3C.
+
+*[HTML]: Hyper Text Markup Language
+*[W3C]:  World Wide Web Consortium
+```
+
+**输出：**
+
+The HTML specification is maintained by the W3C.
+
+*[HTML]: Hyper Text Markup Language
+*[W3C]:  World Wide Web Consortium
+*[ECMA]: European Computer Manufacturers Association
+
+::: warning 缩写词应该是独立的单词或词组。对于中文的缩写词，应该在词的左右加空格以区分。
+:::
--- a/docs/notes/theme/guide/markdown/马克笔.md
+++ b/docs/notes/theme/guide/markdown/马克笔.md
@ -0,0 +1,150 @@
+---
+title: 马克笔
+icon: mingcute:mark-pen-line
+createTime: 2025/02/23 10:46:17
+permalink: /guide/markdown/mark/
+---
+
+## 概述
+
+==马克笔== 是对 Markdown 中的的标记语法 `==Mark==` 的扩展，支持在内容中使用多种不同的颜色来标记文本，
+还可以方便灵活的自定义更多不同的马克笔颜色。
+
+## 语法
+
+### 常规
+
+使用 `== ==` 进行标记。请注意两边需要有空格。
+
+**输入：**
+
+```md
+vuepress-theme-plume 是一个 ==简洁美观== 的 主题
+```
+
+**输出：**
+
+vuepress-theme-plume 是一个 ==简洁美观== 的 主题
+
+### 配色
+
+不同颜色的马克笔通过 [Markdown 属性语法](./扩展.md#属性支持) 进行设置。
+
+在 标记语法 `==Mark==` 之后紧跟 `{.classname}`，可以为马克笔设置不同的颜色。
+
+**输入：**
+
+```md
+==一个提示=={.tip} ==一个警告=={.warning} ==一个错误=={.danger} ==重要内容=={.important}
+```
+
+**输出：**
+
+==一个提示=={.tip} ==一个警告=={.warning} ==一个错误=={.danger} ==重要内容=={.important}
+
+## 内置配色
+
+主题内置了以下的配置方案：
+
+- **default**: `==Default==` - ==Default==
+- **info**: `==Info=={.info}` - ==Info=={.info}
+- **note**: `==Note=={.note}` - ==Note=={.note}
+- **tip**: `==Tip=={.tip}` - ==Tip=={.tip}
+- **warning**: `==Warning=={.warning}` - ==Warning=={.warning}
+- **danger**: `==Danger=={.danger}` - ==Danger=={.danger}
+- **caution**: `==Caution=={.caution}` - ==Caution=={.caution}
+- **important**: `==Important=={.important}` - ==Important=={.important}
+
+## 自定义配色
+
+马克笔可以通过 [自定义样式](../自定义样式.md) 的方式进行自定义。
+
+你可以完全自定义你的马克笔颜色，包括内置的配置方案也可以进行修改。
+
+在主题内部，马克笔通过 `类名` + `CSS 变量` 的方式进行设置。
+
+以下是与马克笔相关的 `CSS 变量`：
+
+- `--vp-mark-text` - 马克笔的文本颜色
+- `--vp-mark-bg` - 马克笔的背景颜色
+- `--vp-mark-bg-image` - 马克笔的背景图片
+- `--vp-mark-linear-color` - 渐变颜色，仅在内置配色中生效
+
+### 修改内置配色
+
+以下是主题内置的马克笔颜色配置，你可以把它们复制到你的 [样式文件](../自定义样式.md#style-文件) 中进行修改。
+
+```css :collapsed-lines
+mark {
+  --vp-mark-text: marktext;
+  --vp-mark-bg: transparent;
+  --vp-mark-bg-image: linear-gradient(to bottom, transparent 25%, var(--vp-c-brand-soft) 30%, var(--vp-c-brand-soft) 50%, var(--vp-c-brand-3) 75%, var(--vp-c-brand-3) 90%, var(--vp-c-brand-soft) 100%);
+}
+
+mark:where(.note, .tip, .info, .warning, .danger, .caution, .important) {
+  --vp-mark-text: currentcolor;
+  --vp-mark-bg: transparent;
+  --vp-mark-bg-image: linear-gradient(to bottom, transparent 55%, var(--vp-mark-linear-color) 55%);
+}
+
+mark.note {
+  --vp-mark-linear-color: #ff0;
+}
+
+mark.info {
+  --vp-mark-linear-color: var(--vp-c-default-1);
+}
+
+mark.tip {
+  --vp-mark-linear-color: #39ff14;
+}
+
+mark.warning {
+  --vp-mark-linear-color: #fc0;
+}
+
+mark.caution, mark.danger {
+  --vp-mark-linear-color: #f99;
+}
+
+mark.important {
+  --vp-mark-linear-color: #ccf;
+}
+
+[data-theme="dark"] mark.note {
+  --vp-mark-linear-color: #660;
+}
+
+[data-theme="dark"] mark.tip {
+  --vp-mark-linear-color: #063;
+}
+
+[data-theme="dark"] mark.warning {
+  --vp-mark-linear-color: #c60;
+}
+
+[data-theme="dark"] mark.caution,
+[data-theme="dark"] mark.danger {
+  --vp-mark-linear-color: #c66;
+}
+
+[data-theme="dark"] mark.important {
+  --vp-mark-linear-color: #66c;
+}
+```
+
+### 添加配色
+
+在 [样式文件](../自定义样式.md#style-文件) 中，通过以下格式添加新的配色:
+
+```css
+mark.classname {
+  --vp-mark-text: marktext;  /* 文本颜色 */
+  --vp-mark-bg-image: none;  /* 背景图片 */
+  --vp-mark-bg: mark;        /* 背景颜色 */
+}
+```
+
+然后在 Markdown 中使用 `==Mark=={.classname}` 进行标记。
+
+你可以随意命名 `classname`，除了修改 CSS 变量，也可以添加其他的 CSS 样式属性。