bottom 项目扩展文档体系构建指南：基于 MkDocs、Material for MkDocs 与 mike 的版本化文档工作流

bottom 项目扩展文档体系构建指南：基于 MkDocs、Material for MkDocs 与 mike 的版本化文档工作流

【免费下载链接】bottomYet another cross-platform graphical process/system monitor.项目地址: https://gitcode.com/GitHub_Trending/bo/bottom

docs/README.md是 bottom（btm）项目扩展文档体系的入口说明，它不描述终端监控工具本身的功能，而是完整定义了该项目在线文档的构建、本地预览与版本化发布流程。本文以该文档为骨架，结合仓库中的mkdocs.yml、serve.sh、mike.sh、构建钩子（hooks）与部署脚本，系统讲解如何在本仓库中把文档跑起来、如何用 mike 同时维护 nightly 与 stable 两个文档版本，以及文档内容如何与 CI 发布流程衔接。读完本文，你将掌握一套可直接复用的「MkDocs + Material + mike 版本化文档」工程实践。

一、文档体系总览：扩展文档放在哪里、由什么驱动

bottom 的文档分为两层：项目根目录的README.md承担「入口 + 安装方式」的职责；而更完整的使用指南（widget 用法、配置项、主题样式、排障、贡献指南等）则存放在 docs/content/ 目录下，即本仓库的「扩展文档」（extended documentation），最终托管在 GitHub Pages 上。

根据 docs/README.md 的说明，这套文档站点基于三件套构建：

• MkDocs：Python 生态的静态文档站生成器；
• Material for MkDocs（mkdocs-material）：提供 Material Design 风格的主题、导航与插件生态；
• mike：专门用于给 MkDocs 站点做多版本发布与版本切换的工具，是 nightly/stable 双版本机制的核心。

文档构建环境目前使用Python 3.11（docs/README.md 注明旧版本一般也能正常工作）。具体依赖版本由 docs/requirements.txt 锁定：

mkdocs == 1.6.1 mkdocs-material == 9.7.6 mdx_truly_sane_lists == 1.3 mike == 2.1.4 mkdocs-git-revision-date-localized-plugin == 1.4.5 mkdocs-redirects == 1.2.2

其中mkdocs-git-revision-date-localized-plugin用于在页面底部展示基于 git 提交的本地化修订日期，mkdocs-redirects用于维护文档内重定向（详见下文 hooks 部分）。

二、本地运行文档：一条命令与手动步骤

docs/README.md 给出了两种本地预览方式。

方式一：直接运行 serve.sh

仓库提供了开箱即用的脚本 docs/serve.sh，它会自动完成 venv 创建、依赖安装与启动：

./docs/serve.sh

该脚本的逻辑很直白：如果./.venv/不存在，就先用$PYTHON_CMD（默认python，也支持作为第一个参数传入，如./serve.sh python3）创建虚拟环境，随后执行pip install --upgrade pip与pip install -r requirements.txt，最后调用.venv/bin/mkdocs serve；若 venv 已存在则跳过创建步骤直接安装依赖并启动。

方式二：手动执行完整步骤

假设当前工作目录是 bottom 仓库根目录，docs/README.md 给出的手动流程为：

# Change directories to the documentation. cd docs/ # Create and activate venv. python -m venv venv source venv/bin/activate # Install requirements pip install -r requirements.txt # Run mkdocs venv/bin/mkdocs serve

mkdocs serve启动后会在本地起一个开发服务器（默认http://127.0.0.1:8000），并对文档内容做热重载——修改 docs/content/ 下的 Markdown 文件后，浏览器中会自动刷新，非常适合边改边验证。

补充：用 mike 预览版本化效果

如果希望本地预览「带版本选择器」的站点（即模拟线上 nightly/stable 并存的效果），仓库还提供了 docs/mike.sh。它与serve.sh的依赖安装逻辑几乎一致，唯一区别是最后调用的是mike serve而不是mkdocs serve。脚本注释特别提醒：mike serve 展示的是已经用 mike 部署过的历史版本，不会反映尚未部署的本地改动。

三、站点配置逐项拆解：mkdocs.yml

文档站的所有行为都由 docs/mkdocs.yml 控制，它是理解整个文档工程的关键文件。下面按配置块拆解。

3.1 站点基本信息

site_name: bottom site_author: Clement Tsang site_url: https://bottom.pages.dev site_description: >- A customizable cross-platform graphical process/system monitor for the terminal. Supports Linux, macOS, and Windows. docs_dir: "content/"

注意docs_dir被显式指定为content/，也就是说 Markdown 源文件全部位于 docs/content/，而 docs/README.md、mkdocs.yml、serve.sh这些文档工程自身的文件不会被纳入站点构建。site_url指向最终托管的 Pages 域名，是搜索引擎收录与 sitemap 生成的基础。

3.2 主题与外观

主题采用 Material，并做了较为细致的定制：

• 字体：代码字体使用 IBM Plex Mono；
• 导航特性：启用了navigation.tabs（顶部标签）、navigation.sections（分区）、navigation.instant（Instant Loading 无刷新跳转）以及navigation.top（回到顶部）等；
• 搜索增强：search.highlight与search.suggest让搜索命中高亮并给出建议词；
• 目录集成：toc.integrate与toc.follow将右侧目录合并进左侧导航并随滚动联动；
• 明暗主题切换：通过palette定义三档切换——跟随系统（prefers-color-scheme）、浅色（primary indigo）、深色（scheme slate），并提供对应的切换图标；
• 自定义模板目录：custom_dir: "overrides"，指向 docs/overrides/；
• 额外样式表：extra_css: stylesheets/extra.css，即 docs/stylesheets/extra.css。

3.3 Markdown 扩展

markdown_extensions: - admonition # 提示框（!!! Note 等） - attr_list # 属性列表 - toc: { anchorlink: true } - pymdownx.inlinehilite - pymdownx.keys # 按键渲染，并覆盖 key_map 使其大小写敏感 - pymdownx.details - pymdownx.highlight - pymdownx.superfences - mdx_truly_sane_lists - pymdownx.tabbed: { alternate_style: true }

这些扩展直接解释了你在 docs/content/ 各页面中看到的语法：!!! Warning/!!! Tip提示框来自admonition、可折叠块来自pymdownx.details、键盘按键高亮来自pymdownx.keys（配置文件还专门重写了 key_map 让a与A区分大小写）、代码块高亮来自highlight+superfences、Tab 分组来自tabbed，而mdx_truly_sane_lists是为了修复 MkDocs 列表缩进换行问题。

3.4 插件与版本化

plugins: - tags - search - mike: canonical_version: stable - git-revision-date-localized: type: date - privacy - redirects: redirect_maps: nightly-release.md: "https://github.com/ClementTsang/bottom/releases"

mike插件的canonical_version: stable意味着搜索引擎收录的 canonical 版本指向 stable 文档；redirects插件配合 hooks 会把nightly-release.md动态重定向到最新 nightly 发布页。extra.version块声明了版本提供者为 mike、默认展示 stable、并允许别名（alias）。从源码结构看，tags插件用于按标签组织文档，privacy插件用于将外部资源本地化缓存，均属 Material 生态的常规配套。

3.5 导航结构与 hooks

nav块完整定义了站点信息架构，从上到下依次是：Home、Support（Official/Unofficial）、Usage（General Usage、Basic Mode、九个 widget 页面、Auto-Complete）、Configuration（命令行选项与各 widget 的配置文件页面、Flags、Layout、Styling）、Contribution（Issues/PR、Documentation、Packaging、Development 子页）、Troubleshooting。这一导航树与实际文件目录一一对应（如 docs/content/usage/widgets/、docs/content/configuration/config-file/）。

文件末尾还配置了两个构建期钩子（hooks）：

hooks: - ./hooks/nightly_redirect.py - ./hooks/nightly_banner.py

以及exclude_docs: nightly-release.md——该文件只是占位（docs/content/nightly-release.md 内容仅一行注释「Intentionally empty file, used for redirects」），不会真正参与渲染。

四、版本化发布：mike 的 nightly 与 stable 双轨流程

docs/README.md 明确指出：部署通过 mike 完成以获得版本化能力，通常由 CI 触发，必要时也可手动执行。这与 docs/content/contribution/development/deploy_process.md 中描述的部署架构一致——bottom 有两套部署流水线：

• Nightly：每天 00:00 UTC 的 GitHub Actions 定时任务，构建二进制/安装包并上传到 nightly release，也可手动触发（支持 mock 模式只验证构建不真正发版）；
• Stable：手动触发或在打x.y.z格式 tag（如git tag 0.6.9 && git push origin 0.6.9）时自动触发，构建产物上传到正式 GitHub Release。

而文档站的 nightly/stable 双版本正是由 mike 维护的，其版本元数据由MIKE_DOCS_VERSION环境变量驱动。

4.1 部署 nightly 文档

cd docs mike deploy nightly --push

--push表示将构建结果直接推送到托管分支。执行后，站点上会新增一个名为nightly的文档版本。

4.2 部署 stable 文档

stable 的发布比 nightly 多两步「改名/换别名」操作，docs/README.md 给出的完整流程为：

cd docs # 1. 把上一个 stable 版本改名为具体的版本号（如 0.10.0），从「stable 指针」上卸下来 mike retitle --push stable $OLD_STABLE_VERSION # 2. 将新版本部署为最新 stable（--update-aliases 让 stable 别名指向它） mike deploy --push --update-aliases $RELEASE_VERSION stable # 3. 给新版本标题追加 "(stable)" 标识，方便在版本选择器中辨认 mike retitle --push $RELEASE_VERSION "$RELEASE_VERSION (stable)"

三步的含义可以这样理解：mike 用「别名（alias）」机制让stable指向某个具体版本。发布新 stable 时，先让旧版本「转正」为独立版本号，再把stable别名切换到新版本，最后重命名标题。这样站点上会同时存在历史版本（如v0.14.7）、最新 stable（标题带(stable)）以及 nightly，读者可通过 Material 主题的版本选择器自由切换。

五、钩子与模板：nightly 版本标识的实现原理

文档站「如何知道自己当前是 nightly 版本」以及「nightly-release 链接如何保持最新」这两件事，由两个 Python 钩子完成，属于 docs/README.md 提到的 mike 版本化体系中的关键工程细节。

5.1 nightly_banner.py：注入 nightly 标识

docs/hooks/nightly_banner.py 注册了on_config事件（优先级-100），核心逻辑是：

version = os.environ.get("MIKE_DOCS_VERSION") if version == "nightly": extra = config.get("extra", {}) extra["nightly"] = True

即读取 mike 注入的MIKE_DOCS_VERSION环境变量，若等于nightly则将extra.nightly置为True。这一标志随后被模板消费：docs/overrides/main.html 通过 Jinja 判断config.extra.nightly，为真时在页面顶部渲染一条通告横幅：

This isnightlydocumentation, and it may differ from stable. Please seehere for stable documentation.

模板注释还特别提到，横幅需要重新应用基础 CSS 的 margin（base CSS 中被 extra.css 覆盖，以避免空横幅问题），这是 Material 模板继承（{% extends "base.html" %}+{% block announce %}）时的典型坑点。

5.2 nightly_redirect.py：动态更新重定向目标

docs/hooks/nightly_redirect.py 实现了「nightly-release 页面永远指向最新 nightly 发布」的效果。它同样在on_config阶段执行（优先级-50）：

1. 优先读取环境变量MKDOCS_NIGHTLY_RELEASE_OVERRIDE（便于 CI 或本地覆盖）；
2. 否则请求 GitHub Releases API，找到第一个 tag 名包含nightly-的 release；
3. 将redirects插件的redirect_maps中的nightly-release.md动态改写为https://github.com/ClementTsang/bottom/releases/tag/<tag>。

异常时（如网络失败）会回退到通用的 releases 列表页。这解释了为什么 docs/mkdocs.yml 中redirect_maps的初值指向 releases 总页面——它只是一个兜底，真正的目标地址在构建时被钩子替换。

六、文档贡献流程：何时改文档、改哪里

文档工程最终服务于持续维护，docs/content/contribution/documentation.md 给出了贡献规范，可作为 docs/README.md 的延伸阅读：

• 何时需要更新文档：新增功能、修复 bug、破坏性变更，以及新增安装方式时，都应在合适位置（README.md、changelog、扩展文档等）补充说明；
• 四类文档载体：根目录 README.md、应用内帮助菜单（源码位于 src/constants.rs，帮助菜单由该文件中的常量生成）、docs/content/ 扩展文档、CHANGELOG.md（遵循 Keep a Changelog 格式并由维护者统一处理）；
• 本地验证：在docs/下执行./serve.sh即可起本地站点随改随看；
• AI 政策：文档严禁由 AI 生成（参见 AI_POLICY.md），不符合政策的改动可能被关闭或隐藏——这一点说明该项目对文档的「人工可读、人机沟通」定位有明确要求。

七、与 CI 部署的衔接及配套工具

除 mike 外，仓库中还有若干与文档/发布工程相关的脚本：

• docs/mike.sh：本地用mike serve预览版本化站点；
• scripts/schema/nightly.sh：通过cargo run --manifest-path scripts/schema_gen/Cargo.toml生成 nightly 的配置 schema（schema/nightly/bottom.json），它与文档一样遵循「nightly 先行」的节奏；
• scripts/schema/validator.py 与 scripts/schema/generate.sh：用于校验/生成各版本的 TOML 配置 schema（schema/v0.9 至 schema/v0.14.7），这些 schema 与文档站的版本化发布相互呼应。

在 CI 中，nightly 文档通常随每日构建任务一起执行mike deploy nightly --push；stable 文档则在发布x.y.ztag 后按 docs/README.md 的三步流程更新。值得注意的一点是 docs/requirements.txt 开头的 TODO 注释：维护者提示 mkdocs-material 已进入维护模式，未来可能需要考虑迁移到其他方案——这为文档工程留下了演进空间。

结语

bottom 的文档体系是一套「内容（docs/content/）+ 配置（mkdocs.yml）+ 版本化发布（mike）+ 构建期钩子（hooks/）」四层分离的工程化方案：日常写作只需关注 content 下的 Markdown；本地验证交给serve.sh；多版本发布由mike deploy/mike retitle完成；而 nightly 横幅与发布页重定向则通过 Python 钩子在构建期动态注入。如果你正在为自己的开源项目搭建一套「nightly + stable」双版本、支持明暗主题与多版本切换的文档站，bottom 仓库中的这套配置与脚本是值得直接参考的完整实现。

【免费下载链接】bottomYet another cross-platform graphical process/system monitor.项目地址: https://gitcode.com/GitHub_Trending/bo/bottom