Rust Forge：面向 Rust 贡献者的补充文档站点

技术定位

Rust Forge 是面向 Rust 贡献者的补充文档库，使用 mdBook 构建，涵盖团队、基础设施与发布相关信息，并提供本地预览、链接检查和可选的发布历史生成工具。

核心功能

• 项目通过 mdBook 将 Markdown 文档构建为可浏览的 Rust Forge 站点。
• Blacksmith 可在构建前获取 Rust 发布信息并生成历史发布页面，但默认处于禁用状态。
• CI 会检查 Forge Markdown 文件中的文档内部链接是否有效。
• JavaScript 用于展示发布日期和“no tools breakage week”等页面内容。
• Rust 团队、工作组或项目组可以按项目约定向 Forge 添加独立内容。

架构与工作机制

Rust Forge 是基于 Markdown 与 mdBook 构建的补充文档站点，内容通过 SUMMARY.md 组织并生成可浏览的书籍页面。构建前可选运行 Blacksmith 获取 Rust 发布信息，JavaScript 负责部分日期和专题展示，CI 会检查文档内部链接。

生态与集成

项目位于 Rust 语言生态中，使用 mdBook、Rust Cargo 工具、mdbook-linkcheck2、JavaScript Standard 风格工具，并通过 rust-forge.toml 与 triagebot.toml 配置团队和内容协作。

适合人群

适合需要了解 Rust 项目团队、基础设施、发布流程及其他协作信息的 Rust 贡献者、团队成员和文档维护者。

使用场景

适用于维护 Rust 团队、工作组和项目组的介绍页面，整理 Rust 基础设施与发布相关资料，提供贡献者可访问的协作信息，并在本地预览或构建文档站点。Blacksmith 还可用于生成 Rust 历史发布信息页面。

主要优势

• 项目定位清晰，内容面向 Rust 贡献者及相关团队协作。
• 基于 Markdown 和 mdBook，提供本地构建与实时预览流程。
• 内置内部链接检查，并支持可选的 Rust 发布历史信息生成。
• 团队内容、权限和自动分配流程在贡献说明中有明确入口。

限制与注意点

• Blacksmith 会增加编译和运行时间，因此默认不会执行，启用时需要设置 RUN_BLACKSMITH=1。
• 项目主要服务于 Rust 贡献者的补充文档场景，并非通用知识库或独立业务应用。
• 公开摘要未说明完整发布流程、托管环境和生产配置，正式部署前需查看 README 或源码确认。
• 团队内容需要配合团队仓库权限配置、SUMMARY.md 和 triagebot.toml，不能仅通过新增 Markdown 文件完成全部协作配置。

部署建议

本地开发需要安装 mdBook，并使用 mdbook serve 启动可实时查看的本地站点，或使用 mdbook build 生成构建结果。链接检查可通过 cargo install mdbook-linkcheck2 –locked 安装工具后执行；Blacksmith 需要设置 RUN_BLACKSMITH=1 才会运行。

维护建议

维护时应保持 mdBook、链接检查工具和 Blacksmith 的构建流程可用，并在修改文档后运行 mdbook build 或 mdbook serve 验证结果。团队内容由对应团队负责合并，Rust infra team 负责 Forge 的构建发布系统及技术协调；长期使用前需结合源码确认工具版本和托管流程。

选型建议

优先选择 Rust Forge 作为 Rust 项目内部团队与基础设施文档的构建基础，尤其适合已经采用 Markdown 和 mdBook 的维护者。选型前应确认是否接受 mdBook 构建方式、可选 Blacksmith 的额外构建开销，以及团队权限、SUMMARY.md 和 triagebot.toml 的协作要求。