算法与数据结构文档站点导航解析:cp-algorithms 的 navigation.md 与内容组织结构
算法与数据结构文档站点导航解析:cp-algorithms 的 navigation.md 与内容组织结构
本指南以开源仓库 cp-algorithms(src/navigation.md)为核心,系统解析这套"算法与数据结构百科全书"式文档站点的导航文件结构与站点构建机制,讲解如何通过 MkDocs 的 literate-nav 插件将一份 Markdown 导航清单映射为站点侧边栏与全站页面索引,并梳理整个仓库的内容分类组织方式。读完本文,你将掌握 navigation.md 的语法与层级设计、站点配置(mkdocs.yml)中的相关插件联动,以及新增文章时如何同步维护导航与测试,直接可用于同类 MkDocs 文档站点的搭建。
一、navigation.md 在项目中的角色
cp-algorithms 是一个将俄语资源 e-maxx.ru/algo 翻译并扩展为英文竞赛编程算法库的开源项目,全站文档以 Markdown 形式存放在仓库的 src/ 目录中,由 MkDocs + Material for MkDocs 主题编译发布(见 README.md 与 mkdocs.yml 中的 docs_dir: src 配置)。
在这个体系里,navigation.md 承担着 "全站目录" 的职责:它不是普通的技术文章,而是被 mkdocs-literate-nav 插件消费的导航清单。项目在 2022 年 6 月的站点改版中"把导航迁移到一个独立页面",并明确规定:"每当新增文章或将旧文章移动位置时,都应在 navigation.md 中调整结构"(README 的 Changelog 与 contrib.md 中的 "Updating Indexes" 一节都有记载)。由此可见,navigation.md 是站点信息架构的单一事实来源(Single Source of Truth)。
从内容形态看,navigation.md 是一份典型的两级树状清单:顶层是站点通用页与 10 大主题域,第二层在部分主题下还有第三级子分组(如 Algebra 下的 Fundamentals、Prime numbers、Modular arithmetic 等),每个叶子项都是一个指向 src/ 下具体 Markdown 文章的链接。
二、文件头部:YAML Front Matter 的隐藏开关
文件开头是 4 行 YAML 元数据:
---
search:
exclude: true
---
这是导航文件(连同 index.md、contrib.md 等同级页)共有的 Front Matter。其作用是把本页面从 MkDocs 的全文搜索索引中排除——导航页本身只是索引载体,让用户搜索到"导航页"没有实际价值。这是站点作者为降低搜索噪声、提升检索质量所做的一个细节取舍。
除此之外,navigation.md 不再依赖任何标题(H1),整份文件就是一个裸的 Markdown 列表,供 literate-nav 插件解析。
三、navigation.md 的语法与结构
3.1 语法本质:Markdown 列表即导航树
mkdocs-literate-nav 的约定是:导航文件用 Markdown 的嵌套无序列表表达目录树。每个列表项要么是一个链接(指向文章或子导航文件),要么是一个普通文本(作为目录分组标题,其下的子列表是该分组的成员)。
看一个具体片段:
- Home
- <a href="https://link.gitcode.com/i/e05bf8a952843ad0f7044612c601618e" target="_blank">Main Page</a>
- <a href="https://link.gitcode.com/i/1cf6f670f95281a2120fe324abe9058b" target="_blank">Navigation</a>
- <a href="https://link.gitcode.com/i/f229fe6a1aa31c28e66debfd494910c9" target="_blank">Tag index</a>
- How to Contribute
- Code of conduct
- <a href="https://link.gitcode.com/i/a0ae56e9c1e6ae9bac22ce0d690b59c6" target="_blank">Preview</a>
- Algebra
- Fundamentals
- <a href="https://link.gitcode.com/i/0092b7e4af975c3eb6f9bf9d9637055e" target="_blank">Binary Exponentiation</a>
...
- Home、- Algebra这类无链接的条目是分组节点,在站点侧边栏中渲染为可折叠的章节标题;- 子条目
- <a href="https://link.gitcode.com/i/e05bf8a952843ad0f7044612c601618e" target="_blank">Main Page</a>是链接节点,指向仓库根src/下的相对路径文章; - 三层的缩进(如
- Algebra→- Fundamentals→- [Binary Exponentiation])对应侧边栏的三级折叠层级。
值得注意的是链接均为相对路径:由于 docs_dir 为 src/,index.md 指向 src/index.md,algebra/binary-exp.md 指向 src/algebra/binary-exp.md。
3.2 全站 10 大主题域速览
将整份清单归纳,站点内容分为 Home + 10 大主题域:
| 顶层分组 | 主要覆盖内容 | 代表文章 |
|---|---|---|
| Home | 站内导航与贡献页 | index.md、contrib.md |
| Algebra | 数论与代数:幂运算、GCD、素数、模运算、快速傅里叶变换等 | Binary Exponentiation、Chinese Remainder Theorem |
| Data Structures | 基础与树形数据结构 | Sparse Table、Segment Tree、Treap |
| Dynamic Programming | DP 入门、背包、LIS 与优化技巧 | Knapsack Problem、Divide and Conquer DP |
| String Processing | 哈希、KMP、Z 函数、后缀数组/自动机等 | String Hashing、Suffix Automaton |
| Linear Algebra | 高斯消元、行列式、矩阵秩 | Gauss & System of Linear Equations |
| Combinatorics | 组合计数:二项式系数、容斥、Burnside、卡特兰数 | Binomial Coefficients、Catalan Numbers |
| Numerical Methods | 二分/三分搜索、牛顿法、模拟退火、辛普森积分 | Binary Search、Simulated Annealing |
| Geometry | 计算几何全谱系:凸包、扫描线、平面图、Delaunay | Convex hull construction、Half-plane intersection |
| Graphs | 图遍历、最短路、最小生成树、网络流、匹配、LCA、2-SAT | Dinic's algorithm、Hungarian Algorithm、Heavy-light decomposition |
| Miscellaneous | 序列问题、博弈论、调度、杂题 | RMQ task、Sprague-Grundy theorem |
每个域下再按 "Fundamentals / Tasks / Advanced / Miscellaneous" 等语义子分组组织,例如 Graph 域下的层级为:Graph traversal → Connected components, bridges, articulations points → Single-source shortest paths → All-pairs shortest paths → Spanning trees → Cycles → Lowest common ancestor → Flows and related problems → Matchings and related problems → Miscellaneous。这种按问题范式(而非仅按算法名)的分组方式,直接服务于竞赛选手"按题型检索"的习惯。
3.3 分组标题即页面标题的来源
literate-nav 默认用导航文件中链接的锚文本生成侧边栏条目,而文章的 HTML 标题则由文章自身内容决定(见 contrib.md 的 "Setting the HTML Title" 一节:默认取文章第一个 # 标题,也可用 Front Matter 的 title 覆盖)。因此 navigation.md 中写得较长的锚文本(如 "Dijkstra - finding shortest paths from given vertex")会原样出现在侧边栏中,成为用户在站内浏览时看到的条目名。
四、与 MkDocs 配置的联动机制
4.1 literate-nav 插件接线
navigation.md 能驱动侧边栏,靠的是 mkdocs.yml 中的插件声明:
plugins:
- toggle-sidebar:
toggle_button: all
- mkdocs-simple-hooks:
hooks:
on_env: "hooks:on_env"
- search
- tags
- literate-nav:
nav_file: navigation.md
...
literate-nav 的 nav_file 指向 src/navigation.md(路径相对于 docs_dir)。该插件会把这份"文学化"的导航文件与页面自身的 H1 标题合并,生成最终的站点导航树。
4.2 与 tags 插件的配合
导航树中 Home 分组下的 Tag index 对应 tags 插件:文章通过 Front Matter 声明 tags(如 Original / Translated),tags 插件扫描后把标签汇总写入 src/tags.md 中的 <!-- material/tags --> 占位符处,形成全站标签索引页。navigation.md 里为它保留了入口链接。
4.3 主题与站点级配置
同文件中与导航渲染直接相关的站点配置还包括:
theme: name: material(Material for MkDocs),并启用了toc.integrate(目录并入侧边栏)、search.suggest、content.code.copy等特性;use_directory_urls: false,站点页面以.html结尾;extra_javascript引入 MathJax 3,支撑文章内$...$/$$...$$公式渲染(对应 mkdocs.yml 中pymdownx.arithmatex扩展);- 侧边栏交互由 src/javascript/sidebar-toggle-sync.js 等脚本增强。
五、新增文章时如何维护导航
contrib.md 的 "Updating Indexes" 一节给出了明确的维护规则:新增或移动文章时,必须同步更新两份文件:
- navigation.md:在相应分组下追加/调整文章链接;
- README.md:在主页面列出的新文章列表处同步登记。
同时注意两处约定:
- 使用仓库根目录相对路径:导航条目必须指向
src/下的真实 Markdown 文件(如dynamic_programming/knapsack.md),一旦路径写错,该条目将 404; - 移动文章要维护重定向:若旧文章被移动,需放置一个包含
<meta http-equiv="refresh" content="0; url=...">的跳转页,避免历史链接失效(详见 contrib.md 的 "Handling Redirects" 一节)。
六、从导航到可运行的代码与测试验证
navigation.md 罗列的每一篇文章,在仓库中基本都伴随了可复现的 C++ 代码片段与自动化测试,这让整套文档具有"可运行"的工程属性。
6.1 代码片段的抽取机制
文章中的代码块采用带 file 属性的标注语法:
```{.cpp file=snippet-name}
// code here
```
test/extract_snippets.py 会遍历 ../src/ 下所有 .md 文件,用正则 ^\s*```\{.cpp\s+file=(\S+)\}$ 识别以 file= 开头的代码块,并把代码行抽取为 test/ 目录下的同名 .h 头文件。从源码看,该脚本按"进入代码块 → 收集行 → 遇到收尾 ``` → 写出 .h"的流程工作,是文档代码与测试之间的桥梁。
6.2 测试用例与导航条目的对应
抽取出的头文件会被 test/ 目录下的测试程序 include 并做行为验证,例如:
- test_dinic.cpp 验证 Dinic's algorithm(导航中 Graph → Flows 分组条目);
- test_hungarian.cpp 验证 Hungarian Algorithm;
- test_geometry.cpp、test_convex_hull.cpp 验证 Convex hull construction 等几何条目;
- test_suffix_array.cpp、test_aho_corasick.cpp 验证字符串专题条目;
- 另有 test/data/ 存放共享测试数据头文件,如 convex_hull.h、flow_networks.h、sssp.h。
所有测试通过 test/test.sh 统一执行(cd test && ./test.sh),并且每个 PR 都会经由 GitHub Actions 自动跑测试(README 的 Build 徽章)。可以推断,这套"导航条目 ↔ 文章 ↔ 代码片段 ↔ 测试"的联动链,保证了导航中每个算法页都具备经过验证的代码样例,是 cp-algorithms 与其他纯笔记型文档站点的关键差异。
6.3 本地预览
贡献者可按 contrib.md 的流程在本地验证导航改动:
git clone --recursive https://github.com/cp-algorithms/cp-algorithms.git && cd cp-algorithms
scripts/install-mkdocs.sh # 安装 mkdocs-material、literate-nav 等全部插件(见 scripts/install-mkdocs.sh)
mkdocs serve # 本地启动,侧边栏即由 navigation.md 生成
注意:本地构建默认关闭 git-revision-date-localized 与 git-committers 插件(前者会因工作区存在未提交改动而报错,后者需要 GitHub token),可按需通过环境变量 MKDOCS_ENABLE_GIT_REVISION_DATE、MKDOCS_ENABLE_GIT_COMMITTERS / MKDOCS_GIT_COMMITTERS_APIKEY 开启(见 contrib.md 与 mkdocs.yml 中的 !ENV 配置)。
七、总结
navigation.md 虽不是算法文章,却是 cp-algorithms 文档站点的"信息架构中枢":
- 它以裸 Markdown 嵌套列表描述全站目录树,由
mkdocs-literate-nav插件直接消费为侧边栏,实现"导航即文档"的维护模式; - 顶层 Front Matter 的
search.exclude: true避免导航页污染全站搜索索引; - 全站划分为 Home 与 10 大算法主题域,域内再按问题范式细分,服务于竞赛编程的检索习惯;
- 它与 mkdocs.yml、tags.md、contrib.md、README.md 协同工作,构成从"写导航 → 配插件 → 生成侧边栏 → 收录标签 → 测试验证"的完整站点构建流水线。
对于希望搭建同类算法文档站点的开发者,这份文件本身就是一份可移植的 literate-nav 导航语法样例;对于 cp-algorithms 的使用者,它则是快速定位任意一篇算法文章的全站索引。