跳转至

MkDocs 导航配置经验总结

创建时间： 2026-05-04
问题类型： 导航配置不完整
状态： ✅ 已修复并验证

📋 问题描述

现象

访问 http://101.132.106.49/protocol/ 时，页面只显示总线协议（AXI/APB/PCIe/DDR），没有显示无线协议（蓝牙、WiFi、4G/5G）。

用户反馈

"为啥 http://101.132.106.49/protocol/ 地址不能直接看到 4G5G-tutorials 呢？"

🔍 问题原因

根本原因

protocol/README.md 源文件内容不完整，只包含总线协议，没有无线协议的链接。

具体问题

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# 协议文档

## 概述
本目录包含芯片项目中使用的各种总线协议文档。  ← 只提到"总线协议"

## 文档列表
| 文档 | 描述 |
|------|------|
| [AXI 协议](axi.md) | AMBA AXI4 协议 |
| [APB 协议](apb.md) | AMBA APB 协议 |
| [PCIe 协议](pcie.md) | PCI Express 协议 |
| [DDR 协议](ddr.md) | DDR 内存接口协议 |

← 缺少蓝牙、WiFi、4G/5G 的链接

为什么 MkDocs 构建时没有报错？

  • MkDocs 只负责将 Markdown 转换为 HTML
  • 它不会检查 README.md 内容是否"完整"
  • 只要语法正确，就能成功构建
  • 内容完整性需要人工检查

✅ 修复方案

步骤 1：更新 README.md

编辑 /home/admin/.openclaw/workspace/chip-project/docs/protocol/README.md：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
# 协议文档

## 概述
本目录包含芯片项目中使用的各种协议文档，包括**总线协议**和**无线通信协议**。

## 总线协议
| 文档 | 描述 |
|------|------|
| [AXI 协议](axi.md) | AMBA AXI4 协议 |
| [APB 协议](apb.md) | AMBA APB 协议 |
| [PCIe 协议](pcie.md) | PCI Express 协议 |
| [DDR 协议](ddr.md) | DDR 内存接口协议 |

## 无线协议

### 蓝牙协议
- [蓝牙协议概述](bluetooth/README.md)
- [01-蓝牙协议栈概述](bluetooth/01-蓝牙协议栈概述.md)
- [02-物理层详解](bluetooth/02-物理层详解.md)
- ... (共 8 个章节)

### WiFi 协议
- [WiFi 协议概述](wifi/README.md)
- [01-WiFi 协议栈概述](wifi/01-WiFi 协议栈概述.md)
- ... (共 8 个章节)

### 无线盲检（4G/5G）
- [00-概述与索引](wireless-detection/00-概述与索引.md)
- [01-PBCH 盲检](wireless-detection/01-PBCH 盲检.md)
- ... (共 6 个章节)

## 4G/5G 协议教程
- [教程概述](4g5g-tutorials/README.md)
- [00-概述与对比](4g5g-tutorials/00-概述与对比.md)
- [01-核心概念详解](4g5g-tutorials/01-核心概念详解.md)
- ... (共 12 个章节)

## 协议对比
（添加总线协议和无线协议的对比表格）

步骤 2：重新构建 MkDocs

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
cd /home/admin/.openclaw/workspace/chip-project

# 修复权限（如果需要）
sudo chown -R admin:admin site/

# 重新构建
mkdocs build

# 恢复 Nginx 权限
sudo chown -R nginx:nginx site/

步骤 3：重启 Nginx

1
sudo systemctl restart nginx

步骤 4：验证

1
2
3
4
5
6
7
8
# 检查构建结果
grep -o "无线协议\|蓝牙\|WiFi\|4G/5G" site/protocol/index.html | head -10

# 测试远程访问
curl -s http://101.132.106.49/protocol/ | grep -o "无线协议\|蓝牙\|WiFi\|4G/5G" | head -5

# 浏览器访问
# http://101.132.106.49/protocol/

🎯 验证结果

✅ 修复前

/protocol/ 页面只显示： - AXI、APB、PCIe、DDR（总线协议）

✅ 修复后

/protocol/ 页面显示： - 总线协议：AXI、APB、PCIe、DDR - 无线协议： - 蓝牙协议（8 个章节） - WiFi 协议（8 个章节） - 无线盲检（6 个章节） - 4G/5G 协议教程（12 个章节） - 协议对比表格

📝 经验教训

教训 1：README.md 内容需要人工审查

错误假设： "MkDocs 构建成功 = 内容完整"

实际情况： - MkDocs 只负责转换格式 - 不检查内容是否"完整"或"合理" - README.md 缺少的内容，构建后也会缺少

正确做法： - 构建前检查 README.md 内容 - 确认所有重要链接都已包含 - 构建后人工验证页面内容

教训 2：目录索引文件很重要

问题： protocol/README.md 是 /protocol/ 页面的内容来源

影响： - 如果 README.md 不完整，索引页面就不完整 - 即使子目录（bluetooth/、wifi/、4g5g-tutorials/）内容存在 - 用户从索引页面看不到这些内容的链接

正确做法： - 每个目录的 README.md 应该包含该目录所有重要内容的链接 - 使用清晰的分类（如"总线协议"、"无线协议"） - 提供导航链接到子目录

教训 3：构建后需要验证内容

错误做法： "构建成功就认为没问题"

正确做法： 

1
2
3
4
5
6
7
8
# 1. 检查生成的 HTML 是否包含预期内容
grep "关键词" site/目录/index.html

# 2. 测试远程访问
curl http://服务器/目录/

# 3. 浏览器实际访问验证
# 人工检查页面显示是否正确

✅ 下次构建 MkDocs 时的检查清单

构建前检查

  • 检查每个目录的 README.md 是否包含完整内容
  • 确认所有重要子目录都在 README.md 中有链接
  • 检查导航分类是否清晰（如"总线协议"vs"无线协议"）
  • 确认概述描述准确（不要只说"总线协议"如果还有无线协议）

构建后验证

  • 检查生成的 HTML 文件是否包含预期关键词
  • 测试远程访问是否正常
  • 浏览器实际访问验证（最重要！）
  • 检查索引页面是否显示所有重要内容
  • 点击导航链接确认能正常跳转

具体内容检查

对于 protocol/README.md 这类索引文件：

  • 是否包含所有子目录的链接？
  • 分类是否清晰（总线协议、无线协议等）？
  • 概述是否准确描述了包含的内容？
  • 是否有对比表格或总结信息？
  • 链接路径是否正确（相对路径）？

🔧 快速修复命令

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# 1. 编辑 README.md
vim docs/protocol/README.md

# 2. 重新构建
mkdocs build

# 3. 修复权限
sudo chown -R admin:admin site/ && mkdocs build && sudo chown -R nginx:nginx site/

# 4. 重启 Nginx
sudo systemctl restart nginx

# 5. 验证
curl -s http://101.132.106.49/protocol/ | grep -o "无线协议\|蓝牙\|WiFi\|4G/5G" | head -5

📊 对比总结

项目 修复前 修复后
README.md 概述 "各种总线协议文档" "各种协议文档，包括总线协议和无线通信协议"
总线协议 ✅ 4 个链接 ✅ 4 个链接
蓝牙协议 ❌ 无链接 ✅ 8 个链接
WiFi 协议 ❌ 无链接 ✅ 8 个链接
无线盲检 ❌ 无链接 ✅ 6 个链接
4G/5G 教程 ❌ 无链接 ✅ 12 个链接
协议对比 只有总线协议 总线协议 + 无线协议

记忆要点

下次构建 MkDocs 时记住：

  1. MkDocs 构建成功 ≠ 内容完整

  2. 构建只检查语法，不检查内容完整性

  3. README.md 决定索引页面内容

  4. 索引页面显示什么，取决于 README.md 写什么

  5. 缺少的链接不会自动补充

  6. 构建后必须人工验证

  7. 用浏览器实际访问
  8. 检查所有重要内容是否显示

  9. 点击导航链接测试跳转

  10. 权限问题处理

  11. 构建前：sudo chown -R admin:admin site/
  12. 构建后：sudo chown -R nginx:nginx site/

本文档基于 2026-05-04 的实际问题编写