mkdocs-for-agent main navmenu-spec.md

导航栏写法

这页专门说明 mkdocs-net 如何解析 navmenu.md。重点不是通用 Markdown 菜单习惯，而是当前系统真实支持的规则。AI Agent 生成导航文件时，应以这页为准。

核心规则

  1. navmenu.md 的菜单层级来自标题层级。
  2. 页面入口来自 Markdown 链接。
  3. 当前只支持 # 到 #### 四级标题。
  4. 标题层级不要跳级。
  5. 不要依赖列表缩进表达导航层级。

当前实现按“标题 + 链接”解析：

  • # 是一级分组。
  • ## 是二级分组。
  • ### 是三级分组。
  • #### 是四级分组。
  • 每个链接会被挂到最近的标题分组下。

推荐心智模型：

  • 标题负责分组。
  • 链接负责入口。

不推荐心智模型：

  • 列表缩进决定层级。
  • - 下嵌套 - 就等于子菜单。

推荐写法

下面这个例子完全符合当前解析逻辑，并且链接都指向 help-docs 内真实存在的页面：

# Help Docs

[帮助中心首页](https://mkdocs.feinian.net:443/mkdocs-for-agent/README.md)

## 导航规范

[导航栏写法](./navmenu-spec.md)

## 页面写作

[页面写作规范](https://mkdocs.feinian.net:443/mkdocs-for-agent/page-writing-spec.md)

## AI 协作

[AI Agent 工作流](https://mkdocs.feinian.net:443/mkdocs-for-agent/agent-workflow.md)

推荐做法：

  • 顶层保留一个 H1 作为导航容器。
  • 每个专题分组使用 ##。
  • 每个页面入口单独写成一个 Markdown 链接。
  • 链接文案直接表达用户能到达什么页面。

容器标题的含义

如果 navmenu.md 最外层只有一个一级标题，这个一级标题通常只是整个导航的容器。最终展示时，重点是这个容器下面的链接和子分组，而不是把 H1 本身当成一个内容页。

因此常见写法是：

# 文档导航

[首页](https://mkdocs.feinian.net:443/mkdocs-for-agent/README.md)

## 专题一

[AI Agent 工作流](https://mkdocs.feinian.net:443/mkdocs-for-agent/agent-workflow.md)

不推荐写法

错误示例 1：完全依赖列表树

# Help Docs

- [帮助中心首页](https://mkdocs.feinian.net:443/mkdocs-for-agent/README.md)
  - [页面写作规范](https://mkdocs.feinian.net:443/mkdocs-for-agent/page-writing-spec.md)

问题：

  • 当前系统不会根据列表缩进建立稳定的菜单层级。
  • 这种写法容易让维护者和 AI Agent 误判真实导航结构。

错误示例 2：标题跳级

# Help Docs

### 页面写作

[页面写作规范](https://mkdocs.feinian.net:443/mkdocs-for-agent/page-writing-spec.md)

问题：

  • 当前实现要求层级连续。
  • 从 # 直接跳到 ### 会让结构不稳定。

错误示例 3：使用四级以上标题

# Help Docs

##### 更深层导航

[页面](https://mkdocs.feinian.net:443/mkdocs-for-agent/page-writing-spec.md)

问题：

  • 当前实现只支持四级标题。
  • 五级及以上标题不应作为导航分组使用。

写导航时的检查清单

  • 是否只有一个顶层导航容器标题。
  • 是否用标题表达分组，而不是用列表缩进表达分组。
  • 是否只使用到四级标题。
  • 是否没有跳级。
  • 是否所有链接都指向真实存在的页面。
  • 是否链接文案可以让用户一眼理解目的地。

相关页面