自动扫描 MkDocs 项目的 docs/ 目录，生成或更新 mkdocs.yml 中的 nav 导航配置。当用户需要同步文档结构与导航配置、批量更新导航、或初始化新项目的导航时使用此 skill。支持按目录层级生成导航、排除隐藏目录、readme 优先排序、index.md 索引页等功能。
自动同步 MkDocs 文档目录结构与 mkdocs.yml 导航配置。
uv run python scripts/sync_nav.py --docs-dir <docs路径> --config <mkdocs.yml路径>
示例：
# 基本用法
uv run python scripts/sync_nav.py --docs-dir ./docs --config ./mkdocs.yml
# 预览模式（不实际修改文件）
uv run python scripts/sync_nav.py --docs-dir ./docs --config ./mkdocs.yml --dry-run
# 指定排除目录
uv run python scripts/sync_nav.py --docs-dir ./docs --config ./mkdocs.yml --exclude ".obsidian,.git"
.obsidian、.git 等隐藏目录readme.md 放在导航最前面index.md| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--docs-dir | 是 | - | docs 目录路径 |
--config | 是 | - | mkdocs.yml 文件路径 |
--dry-run | 否 | false | 预览模式，不修改文件 |
--exclude | 否 | .obsidian | 额外排除的目录（逗号分隔） |
.md 后缀）readme.md 始终在最前index.md，使用 navigation.indexes 特性.md 文件