Hello Algo 开源教程贡献指南：从内容微调到 Docker 本地部署的完整实践

2026-09-07 16:46:12作者：邓越浪Henry

本文以《Hello 算法》（hello-algo）俄文版附录中的贡献指南为核心，完整讲解两种参与方式——网页端"内容微调"与 Fork + Pull Request 的"内容创作"流程，并结合仓库中的 docker-compose.yml、Dockerfile 与 ru/mkdocs.yml 等实际配置，说明如何在本地通过 Docker 一键部署整套多语言文档站点，从而在提交修改前完成真实环境的验证。

一、为什么要贡献：开源书的更新优势

原文档开篇说明：由于笔者能力有限，书中难免存在遗漏和错误，欢迎读者协助修正笔误、失效链接、内容缺失、文字歧义、解释不清晰或行文结构不合理等问题，以提供更优质的学习资源。同时承诺：所有撰稿人的 GitHub ID 将在本书仓库、网页版和 PDF 版的主页上进行展示，以感谢其贡献。

原文档还用一段醒目的提示框对比了纸质书与开源书的更新节奏：

开源的魅力：纸质图书两次印刷的间隔时间往往较久，内容更新非常不方便；而在本开源书中，内容更迭的时间被缩短至数日甚至数小时。

这一特性从仓库结构上可以得到印证：全书文档以 Markdown 源文件形式直接存放在各语言目录下（如 ru/docs/chapter_appendix/contribution.md），且每个语言目录配套独立的 mkdocs.yml，任何被合并的修改在重新构建后几乎可以立即生效。此外，ru/README.md 的"Участие"（参与）章节也列出了三类贡献方向：修正内容、将代码翻译到其他编程语言、以及翻译与校对——这正是本文后续两条流程（微调与创作）的延伸。

二、内容微调：利用页面右上角的"编辑图标"

对于笔误级别的修改，无需本地克隆仓库，直接在网页上操作即可。这一功能由 MkDocs Material 主题的 content.action.edit 特性提供：在根目录的 mkdocs.yml 中，主题 features 列表显式启用了 content.action.edit，并配置了仓库地址与编辑入口：

repo_name: krahets/hello-algo
repo_url: https://github.com/krahets/hello-algo
edit_uri: tree/main/docs

需要注意的是，各语言版本会覆盖 edit_uri，使编辑按钮直接跳转到对应语言的源文件目录。以俄文版为例，ru/mkdocs.yml 中写有：

INHERIT: ../mkdocs.yml   # 继承根配置
edit_uri: tree/main/ru/docs

INHERIT 声明表明俄文版继承了根 mkdocs.yml 的全部主题、插件与扩展配置，仅覆盖站点元信息与 edit_uri。因此，当你在俄文版页面上点击编辑图标时，浏览器会定位到 ru/docs 目录下的对应 Markdown 文件，这与 ru/mkdocs.yml 中 docs_dir 指向的文档源路径一致。

具体修改步骤（继承自原文档）：

点击"编辑图标"。每个页面右上角都有一个编辑图标，点击后如果页面提示"You need to fork this repository"（需要 Fork 此仓库），同意该操作即可——GitHub 会自动在你名下创建一个该仓库的 Fork 副本。
修改 Markdown 源文件内容。编辑时请检查内容的正确性，并尽量保持排版格式与全文统一（本项目大量使用 MkDocs 的 admonition 提示框、代码围栏与标签页语法，格式细节可见 mkdocs.yml 中的 markdown_extensions 配置，如 admonition、pymdownx.superfences、pymdownx.tabbed 等）。
提交修改。在页面底部填写修改说明，点击"Propose file change"按钮；页面跳转后，再点击"Create pull request"按钮发起拉取请求。

页面右上角编辑图标的位置示意（出自原文档配图）：

关于图片的特殊说明：文档中的插图无法通过上述方式直接修改。如果发现图片有问题，应通过新建 Issue 或在评论区留言的方式描述问题，维护者会尽快重新绘制并替换图片。

三、内容创作：完整的 Fork + Pull Request 工作流程

如果参与的是更实质性的工作——例如将代码翻译成其他编程语言、扩展文章内容——原文档要求遵循以下 Pull Request 流程：

Fork 仓库：登录 GitHub，将本书的代码仓库 Fork 到自己的个人账号下。
克隆到本地：进入 Fork 仓库的网页，使用 git clone 命令将仓库克隆至本地。
本地创作与测试：在本地进行内容创作，并做完整测试，验证代码的正确性。
提交并推送：将本地更改 Commit，然后 Push 到远程仓库（即自己的 Fork）。
发起 PR：刷新仓库网页，点击"Create pull request"按钮发起拉取请求。

"完整测试"这一步在仓库层面有明确的落点：各语言的算法代码按章节组织在 codes/ 目录下，每个语言目录都带有独立的工程配置，可以就地构建运行。例如：

C/C++ 使用 CMake，每个章节目录（如 codes/c/chapter_sorting/CMakeLists.txt）都有构建脚本；
Go 模块定义在 codes/go/go.mod；
Rust 使用 codes/rust/Cargo.toml；
Swift 使用 codes/swift/Package.swift；
而 Python 与 JavaScript 则各提供了一份 test_all 脚本（codes/python/test_all.py、codes/javascript/test_all.js），Ruby 对应 codes/ruby/test_all.rb。

因此，若你的 PR 涉及新增语言实现或算法代码，应在 PR 前利用上述工程配置完成本地编译与运行验证，这也是原文档"进行完整测试，验证代码的正确性"的具体含义。

四、Docker 部署：在本地验证整套文档站点

原文档"Деплой с Docker"（Docker 部署）一节给出两条命令：在 hello-algo 根目录下执行

docker-compose up -d

即可通过 http://localhost:8000 访问项目；执行以下命令即可删除部署：

```shell 对应的清理命令
docker-compose down

下面结合仓库内的真实配置，说明这两条命令背后实际发生了什么。

4.1 docker-compose.yml 服务定义

仓库根目录的 docker-compose.yml 内容非常简洁：

version: '3'
services:
  hello-algo:
    build: .
    image: hello-algo
    container_name: hello-algo
    ports:
      - "8000:8000"

即：从仓库根目录构建一个名为 hello-algo 的镜像，并建立 8000:8000 的端口映射——宿主机 8000 端口对应容器内 8000 端口，这正是文档中"项目可通过 http://localhost:8000 访问"的来源。

4.2 Dockerfile 中的五语言构建链

镜像由仓库根目录的 Dockerfile 构建，其构建过程值得逐段理解，因为它解释了为何本地站点与线上多语言站点的结构一致：

基础环境与依赖：基于 python:3.10.0-alpine 镜像，先升级 pip，再安装文档构建所需的两组核心依赖：mkdocs-material==9.5.5（主题）与 mkdocs-glightbox（图片灯箱插件）。Dockerfile 中还保留了切换到 PyPI 镜像源的注释行，供官方源不可达的环境参考。
依次构建五个语言版本：将各语言目录的 docs 与 mkdocs.yml 复制进容器，然后逐语言执行 mkdocs build：
```
COPY docs ./build/docs
COPY mkdocs.yml mkdocs.yml
RUN mkdocs build -f mkdocs.yml

COPY zh-hant/docs ./build/zh-hant/docs
COPY zh-hant/mkdocs.yml ./zh-hant/mkdocs.yml
RUN mkdocs build -f ./zh-hant/mkdocs.yml
# ... 后续以同样方式构建 en、ja、ru
```
构建顺序为：简中（根目录）、繁中（zh-hant/）、英文（en/）、日文（ja/）、俄文（ru/），产物分别输出到各语言 mkdocs.yml 中 site_dir 指定的目录（如俄文版为 ../site/ru，见 ru/mkdocs.yml）。
以纯 Python 静态服务器对外提供服务：
```
WORKDIR /hello-algo/site
EXPOSE 8000
CMD ["python", "-m", "http.server", "8000"]
```
也就是说，容器并不依赖 Nginx 等独立 Web 服务器，而是用 Python 标准库的 http.server 直接服务静态构建产物，监听 8000 端口，与 docker-compose.yml 的端口映射衔接。

从源码结构看，这意味着 docker-compose up -d 首次运行时会先完成五个语言版本的完整构建（耗时取决于机器性能），之后只要访问 http://localhost:8000 就能在本地浏览包括俄文版在内的全部内容；而 docker-compose down 会停止并移除该容器，释放 8000 端口。

4.3 部署方式与贡献流程的关系

Docker 部署对贡献者的价值在于"所见即所得"的验证：对 Markdown 的排版修改（admonition、代码块、链接路径）、对插图引用的调整，都可以在本地构建后的站点上预览，再提交 PR。这正好呼应原文档"修改后检查内容的正确性，保持排版格式统一"的要求。

五、小结

本文覆盖的完整链路为：通过 mkdocs.yml 与 ru/mkdocs.yml 中的 edit_uri / content.action.edit 配置理解"编辑图标"的跳转机制；按三步完成网页端内容微调（图片问题走 Issue 通道）；按五步 Fork + PR 流程完成本地内容创作（利用 codes/ 下各语言工程配置做代码验证）；最后通过根目录的 docker-compose.yml 与 Dockerfile 在本地起一套五语言文档站点，于 http://localhost:8000 验证修改效果。所有命令均可在当前仓库内直接查证，适用前提是本地已安装 Docker 并可用 docker-compose 命令（Compose v2 环境下等价于 docker compose）。