
MAA 文档站编写指南基于 VuePress 与 Plume 主题的 Markdown 扩展语法与实践【免费下载链接】MaaAssistantArknights《明日方舟》小助手全日常一键长草| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknightsMAAMaaAssistantArknights官方文档站基于 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 2vuepress2.0.0-rc.30作为静态站点生成器vuepress-theme-plume1.0.0-rc.205作为主题提供容器、标记、字段、图标等丰富扩展Vite作为打包器vuepress/bundler-vite2.0.0-rc.30pnpm作为包管理器。上述版本信息可以从 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 是由 很多猪 开发的。主题内置了以下配色方案通过花括号中的后缀指定颜色关键字语法示例说明defaultDefault默认高亮infoInfo{.info}信息蓝noteNote{.note}注释tipTip{.tip}提示绿warningWarning{.warning}注意橙dangerDanger{.danger}危险红cautionCaution{.caution}谨慎importantImportant{.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提示容器。这正是父容器比子容器多写一个冒号嵌套规则的典型应用场景。七、智能图片容器ImageGridMAA 文档站在 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 typetip textv1.0.0 新增 / 回调函数 ::: ::: field other type string deprecated Badge typedanger textv0.9.0 弃用 / 已弃用属性 ::: ::::渲染后每个field会成为独立的配置项卡片展示type类型、default默认值、required/optional必填/可选、deprecated弃用标注等注解行并可配合Badge徽章标注版本信息。这一语法需要主题在 markdown 选项中启用field: trueMAA 文档站的 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 namematerial-symbols:home colorcurrentColor size1em / - vscode - Icon nameskill-icons:vscode-dark size2em / - twitter - Icon nameskill-icons:twitter size2em /在 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: trueB 站视频嵌入支持。十一、FrontmatterFrontmatter 是 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.jsonVuePress 站点配置docs/.vuepress/config.tsPlume 主题配置docs/.vuepress/plume.config.ts全局组件注册docs/.vuepress/client.tsImageGrid 组件实现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即可实时预览所有效果。【免费下载链接】MaaAssistantArknights《明日方舟》小助手全日常一键长草| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考