企业官网建设流程全解析

• 数据库
• 缓存
• 后端

导读

本指南围绕 Jedis 项目文档目录下的 docs/README.md 展开，完整讲解如何使用 MkDocs 与 Docker 在本地构建、预览并发布 Jedis 官方文档站点。读完本文后，你将掌握：文档站点的整体架构（MkDocs + Material 主题）、mkdocs.yml 中主题、插件、Markdown 扩展与导航结构的配置含义、通过 Docker 一键启动本地预览环境的完整命令、文档依赖清单，以及仓库 CI 流水线（.github/workflows/docs.yml）如何自动构建并发布到 GitHub Pages 的幕后机制。这对于希望为 Jedis 贡献文档、定制文档站点或复刻同类文档工程的同学，都是一份可直接落地的实战参考。

一、文档站点架构总览

Jedis 的官方文档位于仓库的docs/目录，站点由 MkDocs 驱动生成静态 HTML。整体技术栈分为四层：

从目录结构看，docs/ 下既有面向读者的用户文档（如 failover.md、hash-import.md、redisearch.md、redisjson.md），也有面向维护者的开发文档（如 integration-testing.md、redis-client-components-overview.md），以及版本迁移指南（docs/migration-guides）和发布说明（docs/release-notes）。

其中入口页面 docs/index.md 的完整内容只有一行宏指令：

{% include 'README.md' %}

这行代码正是 mkdocs-macros-plugin 发挥作用的地方：它将仓库根目录的README.md在构建时直接嵌入首页，实现"一处编写、多处展示"，避免维护两份重复内容。这是理解整个文档工程"内容复用"设计的关键线索。

二、核心配置文件 mkdocs.yml 逐项解析

文档的站点元信息、主题、插件与导航全部由仓库根目录的 mkdocs.yml 控制。逐段拆解如下。

2.1 站点元信息

site_name: Jedis repo_name: Jedis site_author: Redis, Inc. site_description: Jedis is a Redis client for the JVM. repo_url: https://github.com/redis/jedis remote_branch: gh-pages

• site_name：浏览器标签页与页面标题中展示的站点名；
• site_description：站点描述，会被搜索引擎收录，是 SEO 的重要输入；
• repo_url+remote_branch: gh-pages：MkDocs 内置"部署到 GitHub Pages"功能时的目标仓库与分支（本项目实际发布走的是 GitHub Actions，见第五节，gh-pages仅作为历史/兜底配置保留）。

2.2 主题与资源

theme: name: material logo: assets/images/logo.png favicon: assets/images/favicon-16x16.png extra_css: - css/extra.css

• name: material：启用 Material for MkDocs 主题；
• logo/favicon：站点 Logo 与站点图标，对应文件为 docs/assets/images/logo.png 与 docs/assets/images/favicon-16x16.png；
• extra_css：加载自定义样式 docs/css/extra.css，用于在 Material 主题基础上做定制化外观调整。

2.3 插件

plugins: - search - macros: include_dir: .

• search：MkDocs 内置全文搜索插件，为站点提供客户端搜索能力；
• macros：启用 mkdocs-macros-plugin，include_dir: .指定宏文件的查找目录为当前目录。第一节提到的{% include 'README.md' %}正是依赖此插件工作。

2.4 Markdown 扩展

markdown_extensions: - pymdownx.highlight: anchor_linenums: true line_spans: __span pygments_lang_class: true - pymdownx.inlinehilite - pymdownx.snippets - pymdownx.superfences: custom_fences: - name: mermaid class: mermaid format: !!python/name:pymdownx.superfences.fence_code_format - admonition - pymdownx.details

这些扩展决定了文档作者可以使用的语法能力：

• pymdownx.highlight：基于 Pygments 的代码块高亮，anchor_linenums: true为行号添加可跳转锚点，pygments_lang_class: true在代码块上输出语言类名；
• pymdownx.inlinehilite：支持行内代码高亮，例如`#!python print("hi")`；
• pymdownx.snippets：允许把外部文件内容片段嵌入 Markdown；
• pymdownx.superfences：扩展代码围栏，其中custom_fences注册了mermaid语言，意味着文档内可直接书写 Mermaid 图表（如架构图、时序图），构建时会被渲染为图形；
• admonition：提供!!! note、!!! warning等提示框语法；
• pymdownx.details：提供可折叠的提示框（??? note形式）。

从仓库文档的实际使用看，docs/failover.md 中大量使用 admonition 提示框与 Mermaid 图来展示故障转移架构，docs/index.md 使用 macros 嵌入 README，均验证了上述配置在真实内容中的落地。

2.5 导航结构 nav

nav: - Home: index.md - Jedis Maven: jedis-maven.md - User Guide: - Transactions/Multi: transactions-multi.md - Hash Import (HIMPORT): hash-import.md - Smart Client Handoffs: smart-client-handoffs.md - Release Notes: - 8.1.0: release-notes/8.1.0.md - Migrating to newer versions: - Jedis 8: migration-guides/v7-to-v8.md ... - Using Jedis with ...: - Search: redisearch.md - JSON: redisjson.md - Failover: failover.md - Verifying artifacts: verifying-artifacts.md - FAQ: faq.md - API Reference: https://www.javadoc.io/doc/redis.clients/jedis/latest/index.html - Tutorials and Examples: tutorials_examples.md - Jedis Guide: https://redis.io/docs/latest/develop/connect/clients/java/jedis/ - Redis Command Reference: https://redis.io/docs/latest/commands/ - Advanced Usage: advanced-usage.md - Development guide: - Contributing: .github/CONTRIBUTING.md - Integration Testing: integration-testing.md - Redis Client Components Overview: redis-client-components-overview.md - Benchmark results: https://redis.github.io/jedis/benchmarks/

从中可以看出导航的完整信息架构：

• 对用户：Maven 接入、用户指南（事务、Hash Import、智能客户端交接）、故障转移、FAQ、高级用法、Search/JSON 模块使用、发布说明、版本迁移指南；
• 对开发者：贡献指南、集成测试、客户端组件架构、Benchmark 结果；
• 对外部资源：API Reference（javadoc.io）、Jedis 官方指南（redis.io）、Redis 命令参考（redis.io）与 Benchmark 页面均以站外链接形式挂载在导航中。

值得注意：nav中引用的.github/CONTRIBUTING.md与docs/外的README.md都位于站点根目录之外，MkDocs 在构建时会自动将它们包含进站点（docs_dir默认是docs/，但nav显式引用的外部文件也会被构建）。这也是为什么index.md可以通过 macros 嵌入根目录 README 而不破坏构建。

三、本地开发环境：Docker 一键预览

这是 docs/README.md 的核心实操内容。文档目录下提供了 docs/Dockerfile，它基于 Material 官方镜像squidfunk/mkdocs-material构建，并额外安装文档所需的 Python 依赖：

FROM squidfunk/mkdocs-material COPY requirements.txt . RUN pip install -r requirements.txt

3.1 构建镜像并启动预览

在docs/目录下执行以下命令即可构建镜像并启动本地预览服务：

# in docs/ docker build -t squidfunk/mkdocs-material . # cd .. docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material

逐步解释每个参数：

• docker build -t squidfunk/mkdocs-material .：基于当前目录（即docs/）的 Dockerfile 构建镜像，标签为squidfunk/mkdocs-material，后续 run 时使用同一镜像名；
• docker run --rm -it -p 8000:8000：前台交互式运行容器，--rm退出即自动清理容器，-p 8000:8000将容器内 MkDocs 开发服务器（默认 8000 端口）映射到宿主机；
• -v ${PWD}:/docs：把当前工作目录挂载进容器的/docs目录。由于docker run是在仓库根目录（cd ..之后）执行的，${PWD}即仓库根目录，因此容器内看到的就是整个仓库，MkDocs 能读取到根目录下的 mkdocs.yml；
• 启动后访问http://localhost:8000即可实时预览文档站点，MkDocs 开发服务器支持文件变更自动重载，改完 Markdown 刷新页面即可看到效果。

3.2 不使用 Docker 的替代方案

如果不依赖 Docker，也可以在 Python 环境（建议 3.12+）中直接安装依赖并启动：

pip install -r docs/requirements.txt mkdocs serve

两种方式原理一致：都是先满足 docs/requirements.txt 中的依赖，再让 MkDocs 读取根目录 mkdocs.yml 并启动开发服务器。Docker 的优势在于环境完全隔离、开箱即用。

四、依赖清单 requirements.txt 说明

docs/requirements.txt 列出了构建文档站点所需的全部 Python 包及其版本约束：

mkdocs~=1.6 mkdocs-material~=9.5 pymdown-extensions~=10.8 mkdocs-macros-plugin~=1.0 mkdocs-glightbox

• mkdocs~=1.6：静态站点生成器核心；
• mkdocs-material~=9.5：Material 主题（对应 Dockerfile 基础镜像squidfunk/mkdocs-material中自带的主题版本）；
• pymdown-extensions~=10.8：提供 mkdocs.yml 中引用的pymdownx.*系列扩展；
• mkdocs-macros-plugin~=1.0：支撑 docs/index.md 的{% include %}宏语法；
• mkdocs-glightbox：为文档中的图片提供点击放大（lightbox）效果。

~=表示兼容指定版本范围的波浪号约束，可接受同一主版本内的更新，兼顾稳定性与安全补丁。

五、CI 流水线：文档的自动构建与发布

仓库通过 GitHub Actions 工作流 .github/workflows/docs.yml 实现了文档站点的自动化构建与发布，触发条件与docs/README.md描述的本地开发流程形成完整闭环。

关键步骤解读：

1. 触发条件：推送到master分支、Benchmark 工作流完成，或手动触发（workflow_dispatch，可选择是否实际部署）；
2. 安装依赖：pip install -r docs/requirements.txt，与本地开发使用同一份依赖清单；
3. 构建站点：mkdocs build -d docsbuild，将 Markdown 编译为静态 HTML 到docsbuild/目录；
4. 嵌入 Benchmark 面板：从benchmark-data分支检出基准数据，复制到docsbuild/benchmarks/下——这与 mkdocs.yml 导航中挂载的Benchmark results站外链接（https://redis.github.io/jedis/benchmarks/）指向的是同一份产物；
5. 发布：通过actions/configure-pages、actions/upload-pages-artifact、actions/deploy-pages三步发布到 GitHub Pages；若为手动触发且未勾选deploy输入，则只构建不部署，用于验证文档可正常构建。

该流水线与本地docker run的差异在于：本地开发使用 Material 官方镜像（内含 MkDocs 与主题），而 CI 使用pip install从 docs/requirements.txt 安装依赖后直接mkdocs build，两种途径最终生成同一套静态站点。

六、实践建议：本地修改文档的完整工作流

综合以上内容，为 Jedis 贡献或修改文档的推荐流程是：

1. 克隆仓库（如尚未克隆）：

   git clone https://gitcode.com/gh_mirrors/je/jedis

2. 本地预览：进入docs/目录执行docker build -t squidfunk/mkdocs-material .，随后回到仓库根目录执行docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material，打开http://localhost:8000；

3. 定位文档：根据 mkdocs.yml 的nav结构找到对应 Markdown 文件（如用户指南在 docs/ 根目录、迁移指南在 docs/migration-guides、发布说明在 docs/release-notes）；

4. 编辑验证：修改 Markdown 后浏览器自动刷新；新增页面时记得同步更新nav配置；

5. 语法检查：如需使用提示框、折叠块、Mermaid 图或行内代码高亮，参照第二节的扩展清单确认语法可用；验证依赖与扩展是否齐全可对照 docs/requirements.txt；

6. 提交推送：推送master分支后由 .github/workflows/docs.yml 自动构建并发布站点，无需手工操作。

七、小结

Jedis 的文档工程是一个轻量但完整的 MkDocs 实践样例：通过 mkdocs.yml 一处配置驱动主题、插件、扩展与导航；通过 docs/Dockerfile 与 docs/requirements.txt 保证本地与 CI 环境依赖一致；通过 mkdocs-macros-plugin 实现 README 复用；再借助 GitHub Actions 完成构建发布。开发者只需掌握docker build+docker run两条命令即可获得与线上完全一致的本地预览体验，从而高效地参与文档编写与审阅。

• 数据库
• 缓存
• 后端