mkdocs-for-agent main README.md

help-docs 帮助中心

这套 help-docs 是给客户端使用、同时也给 AI Agent 阅读的帮助站。它解释 mkdocs-net 文档应该如何组织、导航应该怎么写、页面内容应该怎么落地，以及 AI Agent 在生成或阅读文档时应该遵守哪些稳定规则。

如果你是第一次进入这套帮助文档，先看这一页总览，再按导航进入专题页即可。

适用对象

  • 需要为 mkdocs-net 新增或维护文档的人。
  • 需要为文档站补菜单、拆页面、整理链接的人。
  • 会读取这套帮助文档并继续生成 Markdown 的 AI Agent。

先记住的硬规则

  1. mkdocs-net 文档通常以 docs/README.md 作为首页入口。
  2. 文档导航通常由 docs/navmenu.md 提供。
  3. navmenu.md 的层级来自标题，不来自列表缩进。
  4. navmenu.md 当前只支持 # 到 #### 四级标题。
  5. 内容页应有清晰的一级标题，并优先使用相对链接和相对图片路径。
  6. 页面会自动补 [TOC]，因此标题层级要稳定、连续、可读。
  7. markdown project page 采用无头无尾三栏布局：左导航固定、右 TOC 固定、只有中间正文向下滚动。

帮助站导览

  • 导航栏写法：说明 navmenu.md 的真实解析方式、推荐模板和错误示例。
  • 页面写作规范：说明内容页的标题、摘要、代码块、链接、模板和反例。
  • AI Agent 工作流：说明 AI Agent 的写作要求、阅读顺序、生成流程和自检方法。

推荐阅读顺序

  1. 先看 导航栏写法，理解菜单如何被系统读取。
  2. 再看 页面写作规范，确认单页内容应该怎么写。
  3. 最后看 AI Agent 工作流，把写作要求、阅读策略和交付前检查串起来。

当前帮助站结构

help-docs/
  README.md
  navmenu.md
  navmenu-spec.md
  page-writing-spec.md
  agent-workflow.md

这套结构是第一版轻量帮助站：

  • 首页只负责总览，不再承载全部细节。
  • 专题页各自聚焦一个问题，便于查找和维护。
  • 所有页面都位于 help-docs/ 根目录，导航简单、路径稳定。

使用建议

相关页面