贡献指南
本内容可能会随着项目的发展而变更。请在撰写指南前先阅读 最新版本 的本指南。
本指南使用 [*Mintlify*](https://mintlify.com/) 构建，页面使用 MDX 编写
参阅 Mintlify 组件 文档来了解可用组件。
文件结构
文本
所有需要维护的文本文件均位于content 文件夹下。除首页外，指南页面统一位于 content/guide/。根目录中的 index.mdx 和 guide/ 目录由脚本生成，仅供 Mintlify 本地预览和构建使用，请勿直接编辑。
docs.json 控制。新增页面后，需要同时把页面路径加入 docs.json 的 navigation.tabs[].groups[].pages。
例如：
content/ 中的源文件同步到 Mintlify 需要的根目录路径。可以手动运行：
.gitignore 忽略。提交前请确认没有把 index.mdx、根目录 guide/、.vercel/output 或 export.zip 加入版本控制。
图片
所有图片文件均位于public/img 文件夹下，文件夹结构如下：
public/img 下。引用图片时使用 /img/... 路径，不要写成 public/img/...。
图片推荐分辨率为 1920x1080 ，使用PNG格式。可使用 Squoosh 中的 OxiPNG 压缩，effort 为 2。
文档编写
行文准则
- 正文使用简体中文，专有名词保留原文或在首次出现时补充说明。
- 尽量避免使用第一人称和第二人称，把重点放在概念、操作和结果上。
- 行文保持中立客观，仅描述技术、工具和流程，不涉及无关立场表达。
- 面向初学者时，优先说明“为什么要这样做”和“这样做会影响什么”，不要只堆命令。
- 涉及 AI 相关内容时，重点说明它如何进入真实项目流程，而不是只描述生成结果。
Frontmatter
Mintlify Frontmatter 所有页面均需要添加 frontmatter。title 和 description 必须存在，description 会用于页面摘要、SEO 信息和 AI 友好的静态输出。
示例：
title 应和页面一级标题一致。description 应使用一句完整、具体的中文说明，避免写成“介绍某某内容”这类过于空泛的描述。
如需隐藏目录栏，可在 frontmatter 中添加 toc: false。
标题
一级标题# 仅用于页面标题。正文层级从 ## 开始。
同一层级的章节使用相同标题级别，不要跳级。例如 ## 下一级使用 ###，不要直接使用 ####。
换行
- 每个标题下换行一次，在下一个标题前换行两次。
- 章节间请添加一次换行。
- 代码框前后添加换行。
也可在单行末尾添加<br />换行来解决特殊位置的换行问题。（请注意<br />前需添加空格）
文本格式
文本撰写可参考 中文文案排版指北。涉及标点符号用法时，以中国国家标准 标点符号用法（GB/T 15834-2011） 为准。 本指南中对格式使用有如下特殊规范：- 软件名、产品名和特定称谓可使用斜体，例如 Git、GitHub、Visual Studio Code。
- 命令、参数、路径、文件名、快捷键等使用行内代码，例如
git status、content/guide/、Ctrl + S。 - 对文章或内容进行引用时，如需使用引号包裹，请将引号放在链接之外。示例：
“[Shift to Modern](https://shift2modern.dev/)”。 - 中文与英文、数字之间是否加空格，以清晰易读为准；同一页面内保持一致。
代码块和命令
Mintlify Code Blocks 代码片段使用代码块并标注语言：--help、Ctrl + Shift + P、docs.json。
如果同一操作存在多种平台或工具写法，优先拆成清晰的小节。只有在确实能提升阅读效率时，再使用 Mintlify 的分组代码块组件。
本地预览与校验
常用命令如下：pnpm，可以使用：
pnpm run validate。涉及 URL、导航、AI 静态输出或 Vercel 导出逻辑时，还应运行 pnpm run build，并检查生成的 .md、llms.txt 和页面路径是否符合预期。
AI 和 SEO 相关内容
每个页面的description 应当准确概括页面内容。它会影响页面摘要、搜索引擎展示和 llms.txt 等 AI 友好入口。
新增或移动页面时，请同步检查：
docs.json中的导航路径是否正确。- 页面 URL 是否符合当前
/guide/...结构。 - 页面标题和描述是否能独立说明内容。
- 内部链接是否指向新的公开路径。
docs.json，不要在单个页面里重复配置。