bottom 项目扩展文档体系构建指南基于 MkDocs、Material for MkDocs 与 mike 的版本化文档工作流【免费下载链接】bottomYet another cross-platform graphical process/system monitor.项目地址: https://gitcode.com/GitHub_Trending/bo/bottomdocs/README.md是 bottombtm项目扩展文档体系的入口说明它不描述终端监控工具本身的功能而是完整定义了该项目在线文档的构建、本地预览与版本化发布流程。本文以该文档为骨架结合仓库中的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 的说明这套文档站点基于三件套构建MkDocsPython 生态的静态文档站生成器Material for MkDocsmkdocs-material提供 Material Design 风格的主题、导航与插件生态mike专门用于给 MkDocs 站点做多版本发布与版本切换的工具是 nightly/stable 双版本机制的核心。文档构建环境目前使用Python 3.11docs/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 servemkdocs 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.instantInstant 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区分大小写、代码块高亮来自highlightsuperfences、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/releasesmike插件的canonical_version: stable意味着搜索引擎收录的 canonical 版本指向 stable 文档redirects插件配合 hooks 会把nightly-release.md动态重定向到最新 nightly 发布页。extra.version块声明了版本提供者为 mike、默认展示 stable、并允许别名alias。从源码结构看tags插件用于按标签组织文档privacy插件用于将外部资源本地化缓存均属 Material 生态的常规配套。3.5 导航结构与 hooksnav块完整定义了站点信息架构从上到下依次是Home、SupportOfficial/Unofficial、UsageGeneral Usage、Basic Mode、九个 widget 页面、Auto-Complete、Configuration命令行选项与各 widget 的配置文件页面、Flags、Layout、Styling、ContributionIssues/PR、Documentation、Packaging、Development 子页、Troubleshooting。这一导航树与实际文件目录一一对应如 docs/content/usage/widgets/、docs/content/configuration/config-file/。文件末尾还配置了两个构建期钩子hookshooks: - ./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 的 marginbase 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优先读取环境变量MKDOCS_NIGHTLY_RELEASE_OVERRIDE便于 CI 或本地覆盖否则请求 GitHub Releases API找到第一个 tag 名包含nightly-的 release将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 的配置 schemaschema/nightly/bottom.json它与文档一样遵循「nightly 先行」的节奏scripts/schema/validator.py 与 scripts/schema/generate.sh用于校验/生成各版本的 TOML 配置 schemaschema/v0.9 至 schema/v0.14.7这些 schema 与文档站的版本化发布相互呼应。在 CI 中nightly 文档通常随每日构建任务一起执行mike deploy nightly --pushstable 文档则在发布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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考