文档贡献说明

这页写给准备改 AsterYggdrasil 文档的人。每一页都应该帮读者完成一个明确任务：跑起来、创建 profile、接启动器、配公开 URL、排查材质、备份数据，或者理解项目边界。

先判断放在哪里

你要写什么	放哪里	例子
第一次运行、玩家操作、启动器接入	guide/	快速开始、用户手册、启动器登录
Yggdrasil 协议和材质行为	guide/	Yggdrasil API、材质处理、玩家档案
管理员配置和运行时策略	guide/	配置和密钥、对象存储、审计与后台任务
部署、反向代理、备份、上线检查	deployment/	Docker 部署
项目边界、贡献规则、问题分流	guide/ 的参考页	关于项目、文档贡献说明

拿不准时，先问一句：读者打开这页是为了完成什么任务？

• 是“我要先跑起来” -> guide/getting-started
• 是“我想用这个功能” -> guide/
• 是“我要接启动器或服务端” -> guide/launcher-login 或 guide/yggdrasil-api
• 是“我要配置生产环境” -> guide/configuration 或 deployment/
• 是“我看不懂项目边界” -> guide/about

谨慎调整顶栏

顶栏只做大方向跳转：

• 首页
• 快速开始
• 使用指南
• 接入
• 部署
• 关于
• 版本

新增页面优先放进固定侧边栏的阅读流程里。只有出现新的一级读者任务时，才考虑调整顶栏。

侧边栏是一条阅读流程

侧边栏全站固定，不按文件名排序。默认顺序：

1. 开始
2. 玩家使用
3. 接入协议
4. 管理维护
5. 部署
6. 项目参考

新增页面时，按读者第一次需要它的位置插入。

术语要和产品域一致

文档里优先使用产品和界面上的叫法。必要时第一次出现可以补英文或内部名。

推荐写法：

• 站点账号
• Minecraft profile
• 玩家档案
• profile name
• wardrobe
• skin
• cape
• 材质
• Yggdrasil API
• authlib-injector
• 公开站点地址
• skinDomains
• 签名密钥
• 审计日志

不要把旧模板或其他项目的“文件管理、分享、团队、回收站、云盘”概念带进来。保存 skin/cape 文件时，也应该从 Minecraft 材质域解释，避免写成通用文件系统教程。

页面开头先帮读者定位

长页开头最好有三样东西：

• 这页覆盖什么。
• 什么时候该看这页。
• 读者下一步应该去哪里操作。

推荐结构：

# 页面标题

::: tip 这一篇覆盖什么
一句话说明边界。避免重复相邻页面的大段内容。
:::

## 入口速查

| 你想做什么 | 去哪里 |
| --- | --- |
| ... | ... |

链接规则

站内链接优先用绝对路径：

[配置和密钥](/guide/configuration)
[Yggdrasil API](/guide/yggdrasil-api)
[Docker 部署](/deployment/docker)

同目录短链接也能用，但跨目录应避免复杂的 ../guide/...。绝对路径更容易读，后续移动文件也更稳。

写法规则

• 先给结论，再给细节。
• 用表格做速查，用列表做步骤。
• 配置项、路径、命令、API 路径用反引号。
• 危险操作用 warning。
• 可选背景知识用 details。
• 不写还没合并的功能承诺。
• 不为了“完整”复制另一页的大段内容，应该链接过去。
• Yggdrasil 协议 API 和 /api/v1 站点 API 要分开讲，避免混用响应格式。

改完必须验证

改完文档至少跑：

cd docs
bun run docs:build

如果改了导航、侧边栏或首页，最好再跑：

cd docs
bun run docs:dev

然后自己点一遍：

• 首页入口
• 顶栏
• 固定侧边栏
• 新增页面
• 中英文对应页
• 深色/浅色模式下的代码块和表格

文档能构建只是底线，还要确认真实用户能顺着入口找到内容。