贡献者指南

作者：2352

前言

Apoc 文档站用于沉淀平台规则、使用教程、航空知识与技术说明。贡献内容时，请优先保证信息准确、结构清晰、来源可追溯。

CAUTION

本文档站仅供模拟飞行使用。涉及航空法规、运行程序或技术数据时，不应写成真实飞行操作建议。

第一章 本地开发

1.1 环境要求

• Node.js 18.0 或更高版本；
• pnpm；
• Git。

如果本地尚未安装 pnpm，可使用 Node.js 自带的 npm 安装：

npm install -g pnpm

npm 仅用于安装 pnpm。项目依赖安装、脚本运行和锁文件维护均使用 pnpm。

1.2 安装项目依赖

pnpm install

CI 当前使用 pnpm 安装依赖和构建。请使用 pnpm，并保持 pnpm-lock.yaml 与依赖变更一致。pnpm-lock.yaml 是唯一应提交的依赖锁文件；如果临时使用 yarn、npm 或其他包管理器，请勿将其生成的锁文件提交到 Git。

1.3 本地预览

pnpm run docs:dev

默认访问地址通常为 http://localhost:5173，实际端口以终端输出为准。

1.4 构建检查

pnpm run docs:build

构建产物位于 docs/.vitepress/dist。不要提交本地生成的构建产物、缓存文件或临时文件。

第二章 文档结构

主要内容位于 docs/：

• docs/general/：平台守则和通用说明；
• docs/tutorial/：使用教程；
• docs/aviation/：航空知识；
• docs/technical/：技术文档；
• docs/about/：项目说明与贡献指南；
• docs/public/：站点公共静态资源。

新增页面时，请根据主题放入对应目录。如果页面需要出现在导航栏或侧边栏中，请同步修改 docs/.vitepress/config.mts。除导航、侧边栏和页面入口相关内容外，不要修改 docs/.vitepress/config.mts 中的其他配置。

第三章 写作要求

3.1 标明作者

每篇站内文档开头必须通过 frontmatter 标明作者：

---
author: 作者名称
---

# 文档标题

3.2 保持重点

文档应先提炼结论、步骤和适用条件，再补充说明。不要大段粘贴外部资料或原文。

长内容建议拆成短段落、列表或表格。关键限制、风险、结论和操作步骤应有选择地突出，避免埋在连续大段文字中。

3.3 沿用现有格式

• 使用简体中文为主，航空术语、软件名称和命令可保留英文；
• 标题层级从 # 开始，按顺序使用 ##、###，不要跳级；
• 教程页面按步骤组织，知识页面可使用“前言”“概念”“示例”“参考资料”等结构；
• 命令、文件路径、配置项、缩写和界面字段使用反引号标记，例如 pnpm run docs:build；
• 涉及真实航空法规、程序或数据时，必须写清楚来源；不确定的信息请标注为待确认。

第四章 图片和资料

4.1 图片位置

页面图片建议放在对应栏目下的 images/<页面名>/ 目录，例如：

docs/tutorial/images/swift/1-1-download.png
docs/aviation/images/via/2-1-transition-type.png

Markdown 中优先使用相对路径引用图片，避免依赖容易失效的外部图片链接。

4.2 图片命名

图片必须按章节区分命名。推荐格式为：

<章节号>-<图片序号>-<简短说明>.<扩展名>

例如 1-1-install-client.png、2-3-submit-plan.png。同一页面内图片编号应跟随章节顺序，不要把不同章节的图片混用同一组连续编号。

4.3 图片处理

• 图片应清晰、必要，并尽量压缩到合理大小；
• 截图中如包含个人信息、账号、Token、服务器地址或未公开资料，请先打码；
• 不要提交与页面无关的原始素材、临时导出文件或重复图片。

4.4 资料引用

引用第三方图片、资料或法规内容时，请在正文或“参考资料”中注明来源。需要引用原文时，只摘录必要内容，并补充自己的解释或适用范围说明。

第五章 提交与审核

5.1 提交流程

1. Fork 本仓库并克隆到本地；
2. 基于 main 创建分支，例如 docs/your-topic；
3. 完成修改，并在本地预览页面效果；
4. 运行 pnpm run docs:build；
5. 提交并推送分支；
6. 在 GitHub 创建 Pull Request。

提交信息建议遵循 Conventional Commits：

docs: update swift tutorial
fix: correct qnh reference
chore: adjust vitepress config

5.2 PR 说明

创建 PR 时，请说明：

• 本次修改的目的和范围；
• 新增或修改的页面路径；
• 已执行的检查，例如 pnpm run docs:build；
• 是否新增外部资料引用、图片或附件；
• 文档开头是否已标明作者；
• 是否需要维护者重点复核航空知识、法规依据或技术细节。

5.3 审核重点

维护者通常会重点检查：

• 内容是否准确、清晰，并符合模拟飞行使用场景；
• 来源引用是否充分；
• 是否避免了大段粘贴，并突出关键重点；
• 页面是否能正常构建；
• 导航、侧边栏和链接是否正确；
• 图片路径、章节命名、大小和可读性是否合适；
• 是否符合行为准则和许可证要求。