构建和部署系统

相关源文件

• .flake8
• .github/codespell-ignore
• .github/dependabot.yml
• .github/workflows/ci.yml
• .github/workflows/codespell.yml
• .github/workflows/copy-release-assets.yml
• .github/workflows/labeler.yml
• .github/workflows/monthly-check.yml
• .gitignore
• .husky/pre-commit
• contributing-guides/translation-templates/alias-pages.md
• contributing-guides/translation-templates/common-arguments.md
• contributing-guides/translation-templates/subcommand-mention.md
• package-lock.json
• package.json
• pages.cs/common/cd.md
• pages.cs/windows/cd.md
• pages.fi/linux/adduser.md
• pages.fr/common/adb.md
• pages.ml/common/git.md
• pages.tr/common/gitk.md
• pages.zh/common/kitex.md
• pages/common/,.md
• pages/common/comma.md
• pages/linux/pacman-q.md
• pages/linux/pacman-query.md
• pages/linux/pacman-r.md
• pages/linux/pacman-remove.md
• pages/linux/parted-interactive.md
• pages/linux/parted.md
• requirements.txt
• scripts/README.md
• scripts/_common.py
• scripts/build-index.js
• scripts/build.sh
• scripts/check-pr.sh
• scripts/deploy.sh
• scripts/pdf/NotoSans-Regular.ttf
• scripts/pdf/README.md
• scripts/pdf/basic.css
• scripts/pdf/build-pdf.sh
• scripts/pdf/render.py
• scripts/pdf/solarized-dark.css
• scripts/pdf/solarized-light.css
• scripts/send-to-bot.py
• scripts/set-alias-page.py
• scripts/set-more-info-link.py
• scripts/set-page-title.py
• scripts/test-requirements.txt
• scripts/test.sh
• scripts/update-command.py
• scripts/wrong-filename.sh

tldr-pages 的构建和部署系统负责将命令文档页面打包成各种格式并分发到多个渠道。该系统处理索引、ZIP 压缩包、PDF 文档的创建，并管理部署到项目的静态网站和 GitHub Releases。

有关验证过程的信息，请参阅 验证和质量保证。有关客户端集成详情，请参阅 客户端规范和集成。

系统概览

构建和部署管道由几个相互关联的组件组成，这些组件将 markdown 源代码文件转换为可分发的资产。

源文件： .github/workflows/ci.yml scripts/build.sh scripts/deploy.sh

关键组件

构建组件

构建系统由几个关键脚本和组件组成

组件	文件	目的
主构建脚本	scripts/build.sh	协调构建索引、压缩包和语言包
索引生成器	scripts/build-index.js	创建所有可用页面的 JSON 索引
PDF 生成器	scripts/pdf/render.py	从 markdown 文件生成 PDF 文档
PDF 构建脚本	scripts/pdf/build-pdf.sh	协调不同语言的 PDF 生成

源文件： scripts/build.sh scripts/build-index.js scripts/pdf/render.py scripts/pdf/build-pdf.sh

部署组件

组件	文件	目的
部署脚本	scripts/deploy.sh	处理将资产上传到静态网站和 GitHub Releases
CI 工作流	.github/workflows/ci.yml	定义 GitHub Actions 工作流程
Release Assets Copier	.github/workflows/copy-release-assets.yml	将资产复制到新的 releases

源文件： scripts/deploy.sh .github/workflows/ci.yml .github/workflows/copy-release-assets.yml

生成产物

构建过程会生成几种类型的工件，然后将这些工件分发到不同的渠道

源文件： scripts/build.sh scripts/deploy.sh

构建过程详解

索引生成

索引生成过程会创建一个 JSON 文件，该文件编目了仓库中的所有页面，包括它们的语言和平台。

索引使用 Node.js 构建，包含每个命令的名称、支持的平台和可用翻译的信息。

源文件： scripts/build-index.js package.json20-21

存档创建

构建脚本会创建几个 ZIP 压缩包

1. tldr.zip - 主要压缩包，包含所有英文页面、LICENSE 和 index.json
2. 特定语言的压缩包（例如 tldr-fr.zip）- 包含特定语言的翻译页面

构建脚本仅处理自上次提交以来发生更改的目录，从而优化了构建过程。

源文件： scripts/build.sh19-80

PDF生成

PDF 文档使用 Python 脚本生成，该脚本将 markdown 文件转换为 HTML，然后再转换为 PDF。

PDF 生成过程是选择性的，仅在主分支上运行，或者在检测到页面内容发生特定更改时运行。

源文件： scripts/pdf/render.py scripts/pdf/build-pdf.sh

部署过程

部署过程负责将生成的工件分发到两个主要渠道：项目的静态网站和 GitHub Releases。

静态网站部署

静态网站部署通过项目网站使最新的文档可用。

源文件： scripts/deploy.sh34-51

GitHub Releases 部署

GitHub Releases 部署使资产可以直接从 GitHub 下载。

源文件： scripts/deploy.sh52-62 .github/workflows/copy-release-assets.yml

CI 集成

持续集成系统构建在 GitHub Actions 之上，并自动化构建和部署过程。

CI 工作流程确保只部署经过验证的更改，并且部署过程仅在合并到主分支的更改时运行。

源文件： .github/workflows/ci.yml1-63

构建证明

出于安全目的，所有生成的工件都使用 GitHub Actions 的构建来源（build provenance）功能进行证明。

此证明过程提供了构建工件的加密验证，确保它们是由官方构建过程生成的。

源文件： .github/workflows/ci.yml64-105

结论

tldr-pages 构建和部署系统提供了一个简化的工作流程，用于将 markdown 文档转换为各种格式并分发给用户。该系统设计得非常高效，仅重建已更改的部分，并且安全可靠，所有工件都经过适当的证明。

Node.js 用于索引生成，Python 用于 PDF 创建，shell 脚本用于协调，这些技术的结合创建了一个灵活且可维护的系统，可以随着项目页面和翻译数量的增长而扩展。