Traefik 文档构建与验证实战：从 MkDocs 本地开发到 html-proofer 质量门禁

本文基于 Traefik 官方贡献文档中的「Building Documentation」指南展开：Traefik 的整套官方文档使用 MkDocs 构建，本文介绍如何在本地拉起带热重载的文档服务、执行仅构建模式，以及如何用 Makefile 驱动的检查镜像完成死链检测与 Markdown 风格校验。读完后你可以独立完成文档的本地预览、增量修改与提交前的质量验证。

文档站的技术栈：MkDocs 加定制主题

Traefik 的文档构建入口位于仓库的 docs/ 目录，核心元数据由 docs/mkdocs.yml 定义：

• docs_dir: content：所有 Markdown 源文件存放在 docs/content/ 下，最终站点树（nav）也在 mkdocs.yml 底部集中维护；
• theme：不是社区原版的 Material for MkDocs，而是 traefik-labs 定制主题（name: 'traefik-labs'），并启用了 content.code.copy 等特性；
• plugins：启用了 search、exclude（通过 **/include-*.md 排除片段文件，如 include-acme-single-domain-example.md 这类被正文 include 的片段）、include-markdown（支持正文内引用其他 Markdown 文件）以及 redirects（维护了数百条旧版 URL 到新路径的 301 映射，例如 migration/v2-to-v3.md → migrate/v2-to-v3.md）；
• markdown_extensions：启用了 admonition、pymdownx.superfences、pymdownx.tabbed、pymdownx.snippets（check_paths: true，include 的路径必须真实存在）等扩展，这也是文档中可以使用 !!! tip 等 admonition 语法的来源。

依赖版本由 docs/requirements.txt 锁定，关键条目包括：

依赖	版本	作用
mkdocs	1.4.3	站点构建框架
mkdocs-include-markdown-plugin	7.2.0	正文中 include 其他 Markdown 文件
mkdocs-exclude	1.0.2	排除片段文件进入站点树
mkdocs-traefiklabs	>=100.1.0	Traefik 定制主题
mkdocs-redirects	1.2.2	旧链接 301 重定向
pymdown-extensions	7.0	superfences/tabbed/snippets 等语法扩展

docs/readme.md 还列出了工具链三方件：mkdocs、mkdocs-material 与 pymdown-extensions，可视为理解这套文档站的阅读起点。

方式一：Docker + Make（推荐）

只需安装 Docker。文档构建与校验流程被封装在 docs/Makefile 中，所有目标围绕三个变量组织：

• TRAEFIK_DOCS_BUILD_IMAGE（默认 traefik-docs）：构建镜像名；
• TRAEFIK_DOCS_CHECK_IMAGE（默认 traefik-docs-check）：校验镜像名；
• DOCKER_RUN_DOC_OPTS：固定挂载 -v $(CURDIR):/mkdocs 并映射 -p 8000:8000。

docs-serve：带热重载的本地预览

$ make docs-serve
docker build -t traefik-docs -f docs.Dockerfile .
# […]
docker run --rm -v <your-docs-dir>:/mkdocs -p 8000:8000 traefik-docs mkdocs serve -a 0.0.0.0:8000
# […]
Serving on http://0.0.0.0:8000
Start watching changes
Start detecting changes

docs-serve 目标依赖 docs-image，先构建构建镜像再以 mkdocs serve -a 0.0.0.0:8000 启动服务。由于绑定到 0.0.0.0 而非仅 localhost，同一局域网内也可以访问；本地默认地址为 http://127.0.0.1:8000。mkdocs serve 会持续监听 content/ 下的文件变更并自动重新构建，这正是“Writer Mode”体验的来源。

构建镜像 docs/docs.Dockerfile 的实现很薄：

FROM alpine:3.24
ENV PATH="${PATH}:/venv/bin"
COPY requirements.txt /mkdocs/
WORKDIR /mkdocs
VOLUME /mkdocs
RUN apk --no-cache --no-progress add py3-pip gcc musl-dev python3-dev \
  && python3 -m venv /venv \
  && source /venv/bin/activate \
  && pip3 install -r requirements.txt

要点：工作目录是 /mkdocs（即挂载进来的 docs/ 目录），Python 依赖装在虚拟环境 /venv 中，因此 mkdocs.yml 里的 docs_dir: content、assets/ 静态资源都以 docs/ 为基准解析。

docs-build：只构建、不serve

如果只需要生成静态站点产物（用于 CI 或离线查看）：

$ make docs-build
...

对应 Makefile 中的实现是在容器内执行 mkdocs build，随后 chown -R $(id -u):$(id -g) ./site 修正产物目录属主，使宿主机上的 docs/site/ 文件归属当前用户。

docs-pull-images：预拉取基础镜像

Makefile 还提供 docs-pull-images 目标：从 docs/ 下所有 *.Dockerfile 中 grep 出 FROM 行，去重后以 -P 6 并发 docker pull，适合网络环境受限、希望提前缓存基础镜像的场景。

方式二：本地 Python 环境 + MkDocs

不想用 Docker 时，需要 Python 与 pip，然后从 docs/ 目录安装依赖并直接运行 mkdocs：

pip install --user -r requirements.txt
mkdocs serve

典型输出：

INFO    -  Building documentation...
INFO    -  Cleaning site directory
[I 160505 22:31:24 server:281] Serving on http://127.0.0.1:8000
[I 160505 22:31:24 handlers:59] Start watching changes
[I 160505 22:31:24 handlers:61] Start detecting changes

mkdocs serve 会在 http://127.0.0.1:8000（对应 mkdocs.yml 中的 dev_addr: localhost:8000）启动本地服务并监听文件变化；只构建则运行 mkdocs build。docs/readme.md 还给出了一种虚拟环境写法：先 virtualenv "$DOCS" 并激活，再 pip install -r requirements.txt，最后 mkdocs serve（或 mkdocs build）。本地方式与 Docker 方式共享同一份 docs/requirements.txt，因此产物一致，只是环境隔离程度不同。

校验门禁：docs-verify 到底检查了什么

官方文档明确要求：文档修改后需通过 docs-verify 目标来保证“无死链、HTML 结构有效”等标准。它依赖 docs-build（即先有 site/ 产物），然后构建并运行校验镜像：

$ make docs-verify
docker build -t traefik-docs-check -f check.Dockerfile ./
docker run --rm -v <your-docs-dir>:/app traefik-docs-check /verify.sh
=== Checking HTML content...
...
= Documentation checked successfully.

校验镜像 docs/check.Dockerfile 安装了三层工具链：

1. Ruby + nokogiri (1.18.6) + html-proofer (5.0.10)：HTML 级校验；
2. Node.js + markdownlint 0.29.0 / markdownlint-cli 0.35.0：Markdown 风格校验；
3. tini + curl + ca-certificates：进程管理与网络依赖，tini 用于在 Ctrl-C 时正确终止并行任务。

镜像把三个脚本 COPY 进去作为入口：/verify.sh、/lint.sh、/lint-yaml.sh。

verify.sh：并行 html-proofer 检查

docs/scripts/verify.sh 的核心逻辑：

• 校验站点目录（容器内默认 /app/site）是否存在，不存在直接失败；
• 读取 /proc/cpuinfo 得到 vCPU 数，用 find ... -not -path "/app/site/theme/*" -name "*.html" | xargs -0 -P <vCPU> htmlproofer 做到每个 vCPU 一个 html-proofer 进程并行检查；
• 关键参数：--check_external_hash（外部资源哈希校验）、--ignore_status_codes="0,500,501,503"（容忍暂时性服务端错误与 0 状态）、--ignore_files="/404.html/"，以及一份 --ignore_urls 白名单（对第三方站点、外部论坛等跳过外链探测）。

这与早期文档中展示的 Running ["HtmlCheck", "ImageCheck", "ScriptCheck", "LinkCheck"] on /app/site/... 行为一致：本质就是死链 + 资源可用性检查。

lint.sh 与 lint-yaml.sh：Markdown 与 YAML 规则

docs-lint 目标运行 docs/scripts/lint.sh：

• 先执行 YAML 检查 docs/scripts/lint-yaml.sh：扫描 content/ 下所有 *.yml/*.yaml，若文件以 --- 开头且 --- 分隔线数量大于 1（即包含多个 Kubernetes 资源），则报错——多资源清单不应以文档分隔符开头；
• 再执行 markdownlint：脚本先收集 content/ 下各目录自带的 .markdownlint.json（目录级规则集），对每个目录用其专属配置 lint 并加入全局 --ignore 列表，最后用根级配置对 content/**/*.md 做整体 lint；
• 所有 lint 跑完后按累计退出码统一返回，保证一次看到全部问题而不是在第一个失败处中断。

一步到位：docs 目标

当你改完文档，最稳妥的做法是执行聚合目标，它会按序串起完整流水线：

$ make docs
# 实际展开为：docs-clean docs-image docs-lint docs-build docs-verify

docs-clean 会 rm -rf docs/site，避免旧产物干扰校验结果——官方文档中“Clean & Verify”的提示（先清理再验证更安全）正是这个设计的动机。

跳过校验：DOCS_VERIFY_SKIP / DOCS_LINT_SKIP

Makefile 顶部定义了 DOCS_VERIFY_SKIP ?= false 与 DOCS_LINT_SKIP ?= false。若外部依赖站点大面积不可达、需要临时跳过验证：

DOCS_VERIFY_SKIP=true make docs-verify
# 输出：DOCS_VERIFY_SKIP is true: no verification done.

DOCS_LINT_SKIP=true make docs-lint 同理，会输出 DOCS_LINT_SKIP is true: no linting done.。注意这只是本地逃生通道，提交上游时仍应保证完整校验通过。

目录结构与关键文件速查

路径	说明
docs/Makefile	docs / docs-serve / docs-build / docs-verify / docs-lint / docs-clean 等全部目标
docs/docs.Dockerfile	构建镜像：alpine + Python venv + requirements
docs/check.Dockerfile	校验镜像：html-proofer + markdownlint + tini
docs/mkdocs.yml	主题、插件、扩展、站点导航树与重定向映射
docs/requirements.txt	锁定的 Python 依赖清单
docs/scripts/verify.sh	并行 html-proofer 站点检查
docs/scripts/lint.sh	Markdown/ YAML lint 编排
docs/scripts/lint-yaml.sh	多资源 YAML 首行 --- 规则检查
docs/content/index.md	站点首页（原贡献文档中指向官方文档首页的链接）

小结

Traefik 的文档体系是一条“内容即代码”的流水线：docs/content/ 下的 Markdown 经 MkDocs 构建为静态站点，docs/Makefile 把构建（docs-image/docs-build）、预览（docs-serve）、风格检查（docs-lint）与死链/HTML 校验（docs-verify）串成可重复执行的目标，并通过 DOCS_VERIFY_SKIP、DOCS_LINT_SKIP 提供受控的跳过开关。对贡献者而言，日常工作流即：修改 docs/content/ 下的文档 → make docs-serve 热重载预览 → 提交前 make docs 完成清理、构建、lint 与验证的全链路检查。