SoulBrowser Docs

Appearance

文档站维护 ​

这页用于约束 docs-site/ 自身的维护方式，避免文档重新回到“能搜到但不好用”的状态。

本地运行 ​

bash
cd /mnt/e/projects/soulbrowser/docs-site
npm install
npm run dev

常用脚本：

  • npm run dev
  • npm run build
  • npm run preview

修改前的最低要求 ​

每次改文档，至少确认：

  1. 新页面已经加入导航或侧边栏
  2. 首页不会把迁移页、排障页抬成首屏主入口
  3. API 页描述的是当前代码真实路由，而不是历史印象
  4. 旧文档如果被拆分迁移，要同步更新迁移表

信息架构原则 ​

  • 首页优先放稳定入口，不放一次性问题入口
  • API 总览页负责索引，高频接口页负责联调说明
  • 排障文档放在 troubleshooting/，不要反客为主成为首页核心内容
  • 迁移表是辅助页，不是产品主页

内容原则 ​

  • 主题页可以做抽象总结，但不能和代码当前行为相冲突
  • API 文档如果没有覆盖完整请求体，也要明确写“高频字段”而不是冒充完整参考
  • 对条件字段要写清路径，例如“只在真实执行路径上存在”

推荐维护流程 ​

  1. 先核对代码实际行为
  2. 再修改对应文档
  3. 补上相关导航或迁移映射
  4. 本地跑一次 docs-site
  5. 最后再看首页是否被新内容带偏

当前已知缺口 ​

  • docs-site 还需要持续补充更细的 API 参考
  • 构建校验应成为文档更新后的固定步骤
  • 迁移页仍然只是一张入口表，不等于完整历史文档替代物

SoulBrowser Documentation

Docs in monorepo