# 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` |