文档编写与排序规范

本文面向仓库维护者，用于统一文档命名、展示顺序和阅读路径设计。

主要作用是：

• 给维护者统一文档命名方式
• 约束首页文档展示顺序
• 避免新文档把新手带进高级坑

维护仓库中的文档时，建议先核对这里的规则。

核心规则

1. 文档展示顺序不是按字母，而是按学习路径

同一分类下，文档必须遵守：

新手先看 -> 日常使用 -> 维护排障 -> 进阶方案 -> 旧版参考

这条规则优先于文件名字母顺序。

2. 标题必须一眼看出用途

标题不要只写成笼统名词。

推荐标题风格：

• 入门
• 快速开始
• 部署指南
• 恢复指南
• 进阶版
• 旧版参考
• 排障

避免：

• 两篇文档标题几乎一样
• 标题无法看出是否适合新手
• 旧方案和新方案名字太接近

3. 高风险文档必须显式标明等级

例如：

• （进阶版）
• （旧版参考）
• （高风险）

这样读者在目录里就能立即判断是否该点进去。

4. 同一主题只能有一个主教程

同一个操作主题必须由一份主文档提供完整步骤，其余文档仅包含：

• 入口说明
• 适用范围说明
• 风险提示
• 跳转到主文档

不要把同一套操作步骤分别写进多个文档。

例如：

• 存储扩容的主文档可以负责识别系统类型、选择方案和提供主要流程
• extroot 文档只负责 squashfs + overlay 的进阶方案
• 系统维护文档只保留日常检查与跳转入口，不重复展开完整扩容步骤

当前文档顺序

网站的主学习路线固定为：

1. docs/Quick_Start.md
2. docs/Write_Image.md
3. docs/Lan_Connectioin.md（PPPoE 作为场景分支）
4. docs/Openclash_Config.md
5. docs/OpenWrt_Backup_Resotre.md
6. docs/System_Maintenance.md

主路线由 frontend/lib/learning-path.ts 统一维护。首页、文档侧栏和上一篇/下一篇导航必须使用同一份数据，不要分别硬编码。

对于首页维护类文档，当前顺序应为：

1. docs/OpenWrt_Backup_Resotre.md
2. docs/System_Maintenance.md
3. docs/Storage_Expansion_Guide.md
4. docs/ExtendOverlaySize.md
5. docs/OpenWrt_AutoBackup.md

理由：

• 先给读者恢复和维护基础
• 再讲存储扩容总览
• 再讲 extroot 这种进阶方案
• 旧版自动备份参考放后面

新增文档时必须同步修改的地方

如果新增了用户可见文档，且它会出现在首页目录中，必须同时检查：

1. README.md
2. README_EN.md
3. frontend/lib/docs.ts
4. 如果属于主路线：frontend/lib/learning-path.ts
5. 对应的更新日志 changelogs/*.md

如果新文档属于某个学习路径中的一环，还必须确认它在前端展示中的顺序是否正确。 如果新文档与已有文档讨论同一主题，应先确定负责完整流程的主文档，避免出现内容高度重复的教程。

前端排序机制

主学习路线和参考文档库都不是按文件名字母自动猜测的。

请同步维护：

• frontend/lib/learning-path.ts 中的主路线
• frontend/components/HomePage.tsx 中的参考库分组
• frontend/lib/docs.ts 中的 DOC_CATALOG_ORDER

如果你只新增文档文件，但不更新这个顺序表，新文档可能会排到不合适的位置。

命名示例

好的标题示例：

• ImmortalWrt 存储扩容与分区入门
• ImmortalWrt Overlay 与 Extroot 扩容（进阶版）
• ImmortalWrt GitHub 自动备份（旧版参考）

不好的标题示例：

• 智能自动备份
• 扩容教程
• 系统说明

因为这些名字太宽泛，读者很难判断差异。

排序原则

文档应按照配置顺序排列，使首次使用者可以连续完成操作，并减少在多个页面之间重复查找。

主教程的固定结构

面向操作的主教程应尽量按以下顺序组织：

1. 简要说明适用场景
2. 可观察的验收结果
3. 动手前的前置条件和风险
4. 按顺序编号的操作
5. 每个阶段的验证方法
6. 按现象组织的故障排查
7. 下一篇明确入口

避免将个人经历、项目背景和操作步骤混在同一篇教程中。背景信息可以放在 README，操作细节由唯一的主教程负责。