MAA 文档站编写指南：基于 VuePress 与 Plume 主题的 Markdown 扩展语法与实践-创锋一号

MAA 文档站编写指南：基于 VuePress 与 Plume 主题的 Markdown 扩展语法与实践

【免费下载链接】MaaAssistantArknights《明日方舟》小助手，全日常一键长草！| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights

MAA（MaaAssistantArknights）官方文档站基于 VuePress 构建，并采用 vuepress-theme-plume 主题，为文档编写者提供了一套高度可读的 Markdown 扩展能力。本篇指南以仓库中docs/ko-kr/develop/documentation-guidelines.md（韩文版文档编写指南，与docs/zh-cn/develop/documentation-guidelines.md内容一致）为骨架，系统梳理容器卡片、马克笔标记、隐藏文本、步骤容器、智能图片容器、字段容器、图标与 Frontmatter 等全部写作语法，并结合docs目录下的主题配置与组件源码进行纵深解读。读完本文，你将能够在 MAA 文档站（或任何使用 Plume 主题的 VuePress 站点）中写出结构清晰、层次分明、支持亮暗主题适配的文档页面。

一、文档站技术栈与本文档定位

MAA 文档站点全部源代码位于仓库docs/目录下，采用以下技术栈：

VuePress 2（vuepress2.0.0-rc.30）作为静态站点生成器；
vuepress-theme-plume（1.0.0-rc.205）作为主题，提供容器、标记、字段、图标等丰富扩展；
Vite作为打包器（@vuepress/bundler-vite2.0.0-rc.30）；
pnpm作为包管理器。

上述版本信息可以从 docs/package.json 的devDependencies中确认。该文件还通过devEngines声明了推荐环境：pnpm 11.22.0、node 24.19.0。

文档站支持多语言，docs/下按语言划分目录：zh-cn/、zh-tw/、en-us/、ja-jp/、ko-kr/，每种语言下又分为manual/（用户手册）、develop/（开发者文档）、protocol/（协议与接口文档）等子目录。本文关联的documentation-guidelines.md正是develop/目录下指导文档编写者的规范文档，其 Frontmatter 中order: 6决定了它在侧边栏中的排序位置。

二、本地部署：三步启动文档站

想要本地预览或修改文档，按以下步骤操作：

安装 pnpm，并参考 Pull Request 指南将仓库克隆到本地；
在docs目录下打开终端，运行pnpm i安装依赖；
运行pnpm run dev启动本地开发服务器。

关于第 3 步，从 docs/package.json 的scripts可以看到完整命令集：

{ "scripts": { "dev": "vuepress dev .", "build": "vuepress build .", "clean": "vuepress dev . --clean-cache" } }

dev：启动开发服务器，默认监听地址与端口由 docs/.vuepress/config.ts 中的host: '0.0.0.0'、port: 3001决定，即在浏览器访问http://localhost:3001即可预览；
build：构建生产版本；
clean：清理缓存后重新启动开发服务，适用于主题或插件配置变更后缓存异常的场景。

三、容器与卡片

Plume 主题内置了一套容器（Container）语法，用于把提示、注释、信息、注意、警告、详情等内容以卡片形式强调展示，显著提升文档可读性。这也是文档中最常用的排版手段。

3.1 基本语法

标准语法：

::: [容器类型] [容器标题（可选）] 你想写的内容 :::

也可以使用 GitHub 风格语法：

> [!容器类型] > 你想写的内容

两种写法等效，GitHub 风格在纯文本阅读场景下更易读，也便于代码评审时快速识别。

3.2 支持的容器类型

类型	默认标题 / 用途
`tip`	提示
`note`	注
`info`	相关信息
`warning`	注意
`danger`	警告
`details`	详情（可折叠）
`window`	特殊容器（无默认标题，常用于包裹代码示例的"窗口"效果）

例如，下面的window容器常被用来包裹"输入/输出"对照的代码演示：

::: window 示例 输入与输出对照 :::

3.3 嵌套规则：冒号层数

如果容器内部又嵌套了容器，父级容器必须比子级容器多写一个冒号:作为区分。这一点在多级嵌套时极易出错，例如在"步骤（Steps）"容器中再嵌套tip容器，外层需要用::::（四个冒号）闭合、内层用:::（三个冒号），详见下一节的完整示例。

四、马克笔标记（高亮强调）

用标记语法对重点内容进行高亮，语法为：

==标记内容=={标记颜色（可选）}

注意：==两侧需要有空格，否则无法正确渲染。示例：

MaaAssistantArknights 是由 ==很多猪== 开发的

渲染后效果为：MaaAssistantArknights 是由 ==很多猪== 开发的。

主题内置了以下配色方案，通过花括号中的后缀指定：

颜色关键字	语法示例	说明
default	`==Default==`	默认高亮
info	`==Info=={.info}`	信息蓝
note	`==Note=={.note}`	注释
tip	`==Tip=={.tip}`	提示绿
warning	`==Warning=={.warning}`	注意橙
danger	`==Danger=={.danger}`	危险红
caution	`==Caution=={.caution}`	谨慎
important	`==Important=={.important}`	重要

五、隐藏文本（涂黑 / 模糊）

当文档的某部分内容需要暂时遮盖（如剧透、答案、彩蛋）时，可以使用隐藏文本功能。基本语法：

!!需要隐秘的内容!!{配置（可选）}

默认效果为"涂黑 + 悬停显示"。

可用的配置组合如下：

配置	效果
`!!内容!!{.mask .hover}`	遮罩层效果 + 鼠标悬停显示
`!!内容!!{.mask .click}`	遮罩层效果 + 点击显示
`!!内容!!{.blur .hover}`	文本模糊效果 + 鼠标悬停显示
`!!内容!!{.blur .click}`	文本模糊效果 + 点击显示

例如：

+ 遮罩层效果 + 鼠标悬停：!!鼠标悬停看到我了!!{.mask .hover} + 遮罩层效果 + 点击：!!点击看到我了!!{.mask .click} + 文本模糊效果 + 鼠标悬停：!!鼠标悬停看到我了!!{.blur .hover} + 文本模糊效果 + 点击：!!点击看到我了!!{.blur .click}

渲染后，四行内容分别呈现"遮罩/模糊 + 悬停/点击"四种交互形态。这一功能非常适合用于 FAQ 中的答案折叠、攻略中的配队思路防剧透等场景。

六、步骤（Steps）容器

编写分步教程时，普通的有序列表一旦嵌套就会因为缩进而失去层次感。此时steps容器是最佳选择——它会把每个步骤渲染为独立的编号卡片，且支持步骤内自由嵌套代码块、容器等元素。

完整语法如下（注意外层四冒号、内层三冒号）：

:::: steps 1. 步骤 1 ```ts console.log('Hello World!') ``` 2. 步骤 2 这里是步骤 2 的相关内容 3. 步骤 3 ::: tip 提示容器 ::: 4. 结束 ::::

渲染后每个步骤成为独立的卡片，其中第 1 步内嵌 TypeScript 代码块，第 3 步内嵌tip提示容器。这正是"父容器比子容器多写一个冒号"嵌套规则的典型应用场景。

七、智能图片容器（ImageGrid）

MAA 文档站在 Plume 主题基础上自定义封装了一个图片容器组件<ImageGrid>，其核心能力是：

亮/暗主题自动切换：同一张图提供light与dark两个版本，站点处于深色模式时自动展示 dark 版；
自动布局：多张图片以网格卡片形式排列。

7.1 使用方法

在 Markdown 正文中直接以组件形式调用：

<ImageGrid :imageList="[ { light: 'images/ko-kr/readme/1-light.png', dark: 'images/ko-kr/readme/1-dark.png' }, { light: 'images/ko-kr/readme/2-light.png', dark: 'images/ko-kr/readme/2-dark.png' }, { light: 'images/ko-kr/readme/3-light.png', dark: 'images/ko-kr/readme/3-dark.png' }, { light: 'images/ko-kr/readme/4-light.png', dark: 'images/ko-kr/readme/4-dark.png' } ]" />

说明：示例中的图片路径是相对于 docs/.vuepress/public 目录的（构建后映射为站点根路径/images/...），上述ko-kr/readme/系列亮暗双版本图片在仓库 docs/.vuepress/public/images/ko-kr/readme 中真实存在，可直接用于本地复现验证。

7.2 组件实现原理

从源码看，该组件由 docs/.vuepress/components/ImageGrid.vue 实现，其核心逻辑值得文档编写者了解：

通过MutationObserver监听<html>根元素的class与data-theme属性变化，实时感知站点主题切换；
同时通过window.matchMedia('(prefers-color-scheme: dark)')监听系统级深色模式偏好；
最终在computed中根据当前是否深色模式选择item.dark或item.light，并经withBase()处理为正确的部署路径。

此外，docs/.vuepress/client.ts 中通过app.component('ImageGrid', ImageGrid)将组件全局注册，因此任何 Markdown 页面都可直接使用，无需额外 import。

八、字段容器（Field）

字段容器用于结构化展示"配置项"类信息（如类型、默认值、是否必填、版本变更等），非常适合 API 参数与配置文件字段的说明。其语法较复杂，完整规则可参考主题官方文档中关于 Field 的章节（文中不再展开全部细节）。

效果示例如下：

:::: field-group ::: field theme @type ThemeConfig @default { base: '/' } @required 主题配置 ::: ::: field enabled @type boolean @default true @optional 是否启用 ::: ::: field callback @type (...args: any[]) => void @default () => {} @optional <Badge type="tip" text="v1.0.0 新增" /> 回调函数 ::: ::: field other @type string @deprecated <Badge type="danger" text="v0.9.0 弃用" /> 已弃用属性 ::: ::::

渲染后，每个field会成为独立的配置项卡片，展示@type（类型）、@default（默认值）、@required/@optional（必填/可选）、@deprecated（弃用标注）等注解行，并可配合<Badge>徽章标注版本信息。这一语法需要主题在 markdown 选项中启用field: true，MAA 文档站的 docs/.vuepress/config.ts 已确认开启。

九、图标（Icon）

主题提供全面的图标支持，可在以下三个位置使用图标：

文档标题旁：在 Frontmatter 中设置icon字段；
导航栏 / 侧边栏：在导航配置中为条目设置图标；
文档正文：通过<Icon />组件内联使用。

9.1 设置文档图标

在文档 Frontmatter 中通过icon字段设置，该图标会显示在文档标题旁边。本文档自身的 Frontmatter 即包含icon: jam:write-f：

--- icon: jam:write-f ---

9.2 在正文中使用图标

通过<Icon />组件在 Markdown 中添加图标，主要属性如下：

name（也可写作icon）：接受图标关键字及 URL，如jam:write-f、ic:round-home、material-symbols:home等；
color：接受 CSS 风格的颜色值，如#fff、red等（该选项仅对 SVG 图标有效）；
size：接受 CSS 风格的尺寸值，如1rem、2em、100px等。

示例：

- home - <Icon name="material-symbols:home" color="currentColor" size="1em" /> - vscode - <Icon name="skill-icons:vscode-dark" size="2em" /> - twitter - <Icon name="skill-icons:twitter" size="2em" />

在 docs/.vuepress/config.ts 的 markdown 配置中，图标提供方被设置为icon: { provider: 'iconify' }，同时@iconify/vue也在 docs/package.json 中被声明为直接依赖。

9.3 图标关键字的获取

本文档使用的图标均来自 Iconify 图标集，你可以在其官方图标搜索界面中检索所需图标并复制关键字。仓库内大量文档页面的 Frontmatter（如jam:write-f、jam:book等）即是使用该方式选取的。

十、更多 Markdown 扩展能力

除上述功能外，docs/.vuepress/config.ts 的markdown配置中还开启了多项 Plume 扩展，可作为文档编写的补充手段：

annotation: true：代码块注释标注；
image.lazyload / mark / size：图片懒加载、水印标记与尺寸属性支持；
math: { type: 'katex' }：KaTeX 数学公式渲染；
plot: true：文本绘图支持；
bilibili: true：B 站视频嵌入支持。

十一、Frontmatter

Frontmatter 是 Markdown 文档开头一段用---包裹起来的内容，内部使用 YAML 语法。通过 Frontmatter，可以标识文档的编辑时间、使用的图标、分类、标签等元信息，文档站的主题与导航系统会据此渲染标题、侧边栏排序等。

完整示例：

--- date: 1919-08-10 icon: jam:write-f order: 1 --- # 文档标题 ...

各字段含义如下：

字段	含义
`date`	文档的编辑时间
`icon`	文档标题旁边的图标（来自 Iconify 图标集）
`order`	文档在侧边栏中的排序（数值越小越靠前）

在本文档的 Frontmatter 中，order: 6与icon: jam:write-f即分别控制其在develop/侧边栏中的位置与标题旁显示的图标。此外，从 docs/.vuepress/config.ts 可以看到主题开启了editLink: true与docsRepo、docsDir、docsBranch配置，读者可通过页面上的编辑链接直接跳转到对应文档源文件。

十二、仓库路径速查

用途	路径
本文档（韩文版）	docs/ko-kr/develop/documentation-guidelines.md
本文档（中文版，内容同源）	docs/zh-cn/develop/documentation-guidelines.md
文档依赖与脚本	docs/package.json
VuePress 站点配置	docs/.vuepress/config.ts
Plume 主题配置	docs/.vuepress/plume.config.ts
全局组件注册	docs/.vuepress/client.ts
ImageGrid 组件实现	docs/.vuepress/components/ImageGrid.vue
亮暗主题示例图片	docs/.vuepress/public/images/ko-kr/readme
克隆与贡献流程	docs/ko-kr/develop/pr-tutorial.md

结语

掌握容器、标记、隐藏文本、步骤、图片网格、字段、图标与 Frontmatter 这八类语法，就掌握了 MAA 文档站绝大多数高级排版能力。实际写作时建议遵循"内容优先、强调克制"的原则：步骤教程优先用steps容器、重点概念用tip/warning容器提示、亮暗双版本截图用<ImageGrid>呈现，再配合规范的 Frontmatter 元信息，即可写出与 MAA 官方文档一致的高质量技术文档。在本地运行pnpm i && pnpm run dev即可实时预览所有效果。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析