122 lines
4.1 KiB
Markdown
122 lines
4.1 KiB
Markdown
|
# MkDocs 导航结构参考
|
||
|
|
|
||
|
|
本文档记录文档站的 mkdocs.yml 配置和导航组织规范。
|
||
|
|
|
||
|
|
## 导航结构
|
||
|
|
|
||
|
|
文档站的导航由 `mkdocs.yml` 的 `nav` 字段控制。文档本身不使用 YAML frontmatter。
|
||
|
|
|
||
|
|
### 当前目录结构
|
||
|
|
|
||
|
|
```
|
||
|
|
docs/
|
||
|
|
├── index.md # 首页
|
||
|
|
├── javascripts/mathjax.js # MathJax 配置
|
||
|
|
├── algorithm/ # 算法
|
||
|
|
│ ├── index.md # 章节首页
|
||
|
|
│ ├── bloom-filter.md
|
||
|
|
│ ├── bloom-filter-deletion.md
|
||
|
|
│ ├── counting-bloom-filter.md
|
||
|
|
│ ├── cuckoo-filter.md
|
||
|
|
│ ├── heavykeeper.md
|
||
|
|
│ ├── binary-tree-traversal.md
|
||
|
|
│ └── queue.md
|
||
|
|
├── architecture/ # 架构
|
||
|
|
│ ├── index.md
|
||
|
|
│ └── cache/
|
||
|
|
│ ├── index.md
|
||
|
|
│ ├── cache-breakdown.md
|
||
|
|
│ ├── cache-avalanche.md
|
||
|
|
│ └── cache-penetration.md
|
||
|
|
├── project/ # 项目
|
||
|
|
│ ├── index.md
|
||
|
|
│ ├── openapi-billing-architecture.md
|
||
|
|
│ ├── openapi-billing-resume.md
|
||
|
|
│ └── qdata/
|
||
|
|
│ ├── index.md
|
||
|
|
│ ├── architecture.md
|
||
|
|
│ ├── data-governance-etl.md
|
||
|
|
│ ├── deployment.md
|
||
|
|
│ └── resume.md
|
||
|
|
└── qiniu-cloud/ # 七牛云
|
||
|
|
├── index.md
|
||
|
|
├── architecture.md
|
||
|
|
├── ansible-automation.md
|
||
|
|
├── deployment-cicd.md
|
||
|
|
├── security-auth-data.md
|
||
|
|
└── resume-tech-points.md
|
||
|
|
```
|
||
|
|
|
||
|
|
### nav 格式示例
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
nav:
|
||
|
|
- 首页: index.md
|
||
|
|
- 项目:
|
||
|
|
- 项目概述: project/index.md
|
||
|
|
- OpenAPI 计费:
|
||
|
|
- 架构设计: project/openapi-billing-architecture.md
|
||
|
|
- 简历亮点: project/openapi-billing-resume.md
|
||
|
|
- qData:
|
||
|
|
- 概述: project/qdata/index.md
|
||
|
|
- 架构设计: project/qdata/architecture.md
|
||
|
|
- 数据治理: project/qdata/data-governance-etl.md
|
||
|
|
- 部署方案: project/qdata/deployment.md
|
||
|
|
- 简历亮点: project/qdata/resume.md
|
||
|
|
- 架构:
|
||
|
|
- 架构概述: architecture/index.md
|
||
|
|
- 缓存:
|
||
|
|
- 缓存概述: architecture/cache/index.md
|
||
|
|
- 缓存击穿: architecture/cache/cache-breakdown.md
|
||
|
|
- 缓存雪崩: architecture/cache/cache-avalanche.md
|
||
|
|
- 缓存穿透: architecture/cache/cache-penetration.md
|
||
|
|
- 算法:
|
||
|
|
- 算法概述: algorithm/index.md
|
||
|
|
- 布隆过滤器: algorithm/bloom-filter.md
|
||
|
|
- 布隆过滤器删除: algorithm/bloom-filter-deletion.md
|
||
|
|
- 计数布隆过滤器: algorithm/counting-bloom-filter.md
|
||
|
|
- 布谷鸟过滤器: algorithm/cuckoo-filter.md
|
||
|
|
- HeavyKeeper: algorithm/heavykeeper.md
|
||
|
|
- 二叉树遍历: algorithm/binary-tree-traversal.md
|
||
|
|
- 队列: algorithm/queue.md
|
||
|
|
- 七牛云:
|
||
|
|
- 概述: qiniu-cloud/index.md
|
||
|
|
- 架构设计: qiniu-cloud/architecture.md
|
||
|
|
- Ansible 自动化: qiniu-cloud/ansible-automation.md
|
||
|
|
- 部署与 CI/CD: qiniu-cloud/deployment-cicd.md
|
||
|
|
- 安全与认证: qiniu-cloud/security-auth-data.md
|
||
|
|
- 简历技术亮点: qiniu-cloud/resume-tech-points.md
|
||
|
|
```
|
||
|
|
|
||
|
|
## 添加新文档的步骤
|
||
|
|
|
||
|
|
1. **确定章节**：新文档属于哪个顶级章节（algorithm/architecture/project/qiniu-cloud）？是否有子章节？
|
||
|
|
2. **创建文件**：在对应目录下创建 `.md` 文件（kebab-case 命名）
|
||
|
|
3. **更新 nav**：在 `mkdocs.yml` 的 `nav` 中对应位置添加条目
|
||
|
|
4. **更新 index.md**（如需）：如果是新子章节，可能需要更新章节的 `index.md`
|
||
|
|
|
||
|
|
## Section Index 规范
|
||
|
|
|
||
|
|
每个章节目录下的 `index.md` 是该章节的首页/概述页。使用 MkDocs Material 的 `navigation.indexes` 功能：
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
# mkdocs.yml 中启用
|
||
|
|
theme:
|
||
|
|
features:
|
||
|
|
- navigation.indexes
|
||
|
|
```
|
||
|
|
|
||
|
|
`index.md` 通常包含：
|
||
|
|
- H1 标题（章节名称）
|
||
|
|
- 一句话概述
|
||
|
|
- 子文章的链接表格（如有子文章）
|
||
|
|
|
||
|
|
## 命名规范
|
||
|
|
|
||
|
|
| 类型 | 规范 | 示例 |
|
||
|
|
|------|------|------|
|
||
|
|
| 目录名 | 小写 kebab-case | `architecture/`、`qiniu-cloud/` |
|
||
|
|
| 文件名 | 小写 kebab-case | `cache-breakdown.md` |
|
||
|
|
| 章节标题 | 中文 | `# 缓存击穿` |
|
||
|
|
| nav 标签 | 中文 | `缓存击穿: architecture/cache/cache-breakdown.md` |
|