工作流 15：从 Markdown 文档到 GitHub Pages 电子书站点的 AI 发布工作流¶

适用岗位：技术写作者、课程作者、开源作者、比赛项目作者

真实场景：你有一批 Markdown 文档（教程、笔记、电子书章节），想用 MkDocs + Material 主题做成漂亮的在线文档站点，通过 GitHub Pages 发布，但常卡在配置错误、构建失败、Pages 不显示等问题上。

最终目标：一个可访问的 GitHub Pages 文档站点，包含：规划好的文档结构、正确的 mkdocs.yml 配置、Material 主题、清晰的导航、通过 mkdocs build --strict 的文档、自动部署的 GitHub Actions，以及发布验收确认。

输入材料清单¶

Markdown 文档（一批 .md 文件）
站点基本信息（站点名、描述、作者、GitHub 用户名/仓库名）
文档主题/领域（教程 / 电子书 / API 文档 / 笔记）
是否需要特殊功能（搜索、代码高亮、多语言等）
GitHub 仓库情况（是否已创建、是否已启用 Pages）

工作流总览¶

节点 1：文档结构规划专家
  ↓ 输出：文档目录结构 + 章节组织
节点 2：MkDocs 配置专家
  ↓ 输出：mkdocs.yml 基础配置
节点 3：Material 主题专家
  ↓ 输出：主题配置（外观 + 功能）
节点 4：导航结构专家
  ↓ 输出：nav 导航配置
节点 5：Markdown 质量检查专家
  ↓ 输出：Markdown 问题清单 + 修正
节点 6：GitHub Actions 部署专家
  ↓ 输出：deploy.yml 部署配置
节点 7：GitHub Pages 配置专家
  ↓ 输出：Pages 设置步骤
节点 8：构建错误修复专家（招牌节点）
  ↓ 输出：构建错误诊断 + 修复
节点 9：发布验收专家
  ↓ 输出：发布验收清单结果
最终交付：可访问的 GitHub Pages 文档站点

专家节点详解¶

每个节点包含六部分：节点定位、输入与输出、使用顺序、提示词包（A 快速 / B 专家 / C 自查 / D 返修）、交付给下游节点、人工验收清单。

C 自查审稿版和 D 返修优化版是当前节点内部的工作模式，不是新的专家角色。

命令使用提示

本工作流包含 pip、mkdocs、git 命令。命令中的仓库名、用户名、路径需替换为你自己的实际值。

节点 1：文档结构规划专家¶

1.1 节点定位¶

将零散的 Markdown 文档规划为有逻辑的文档结构，确定章节组织和文件命名。良好的文档结构是站点可读性和可维护性的基础。

1.2 输入与输出¶

输入：Markdown 文档清单 + 文档主题/领域

输出：文档目录结构（docs/ 下的组织）+ 文件命名建议 + 章节顺序

1.3 使用顺序¶

先用「快速生成版」得到结构规划初稿。
文档数量多或逻辑复杂时，改用「专家增强版」。
用「自查审稿版」检查结构是否清晰、命名是否规范。
有问题则用「返修优化版」调整。
对照 1.6 验收清单确认，通过后交给节点 2 和节点 4。

1.4 提示词包¶

A. 快速生成版¶

你是一位文档架构师。请为以下 Markdown 文档规划站点结构。

文档清单：【粘贴文件列表或文档主题列表】
文档领域：【填入教程/电子书/API文档】

输出：
1. docs/ 目录结构（如何分组组织）
2. 文件命名建议（小写、连字符、有序前缀如 01-）
3. 章节阅读顺序

B. 专家增强版¶

你是一位资深文档架构师，熟悉 MkDocs 项目组织。

任务：为以下文档规划清晰的站点结构。

输入：
- 文档清单：【粘贴文件列表/主题列表】
- 文档领域：【填入】
- 目标读者：【填入】

处理步骤：
1. 按逻辑分组文档（如：入门/进阶/参考/附录）
2. 设计 docs/ 目录结构（分组用子目录）
3. 规范文件命名（小写连字符，必要时用数字前缀控制顺序）
4. 确定章节阅读顺序（从入门到深入）
5. 识别需补充的文档（如缺少首页 index.md）

输出格式：
- docs/ 目录树
- 文件命名对照表（原文件 → 建议文件名）
- 章节顺序说明
- 需补充的文档清单

约束：文件名用小写+连字符，避免空格和中文文件名；每个分组逻辑清晰；必须有 index.md 作为首页。

质量标准：读者能顺着结构从入门到精通，维护者能快速定位文档。

常见失败情况：文件名含空格或中文导致部署问题；缺少 index.md 导致首页空白；结构混乱无逻辑分组。

C. 自查审稿版¶

此为当前节点的自查模式，不是新的专家角色。

请检查以下文档结构规划是否存在以下问题：
1. 文件名是否都是小写+连字符（无空格、无中文）？
2. 是否有 index.md 作为站点首页？
3. 分组是否有清晰逻辑？
4. 章节顺序是否从入门到深入？

【粘贴文档结构规划】

逐条说明问题。

D. 返修优化版¶

根据自查意见修改文档结构。规范文件命名，补充 index.md，理顺分组逻辑和章节顺序。

原始规划：【粘贴原始规划】
自查意见：【粘贴自查结果】

1.5 交付给下游节点¶

将文档目录结构复制，交给节点 2（MkDocs 配置专家）和节点 4（导航结构专家）。nav 配置需对应此结构。

1.6 人工验收清单¶

[ ] 文件名是否都规范（小写+连字符，无空格无中文）？
[ ] 是否有 index.md 首页？
[ ] 分组逻辑是否清晰？

节点 2：MkDocs 配置专家¶

2.1 节点定位¶

生成正确的 mkdocs.yml 基础配置，包含站点信息、仓库信息和必要的插件扩展。配置是 MkDocs 项目的核心，配置错误会直接导致构建失败。

2.2 输入与输出¶

输入：节点 1 文档结构 + 站点基本信息

输出：mkdocs.yml 基础配置（site 信息 + repo 信息 + markdown_extensions）+ requirements.txt

2.3 使用顺序¶

先用「快速生成版」生成基础配置。
需要特殊扩展或插件时，改用「专家增强版」。
用「自查审稿版」检查 YAML 语法、必填项、依赖完整性。
有问题则用「返修优化版」修正。
对照 2.6 验收清单确认，通过后交给节点 3。

2.4 提示词包¶

A. 快速生成版¶

你是一位 MkDocs 配置助手。请生成 mkdocs.yml 基础配置。

站点信息：【填入 site_name、描述、作者】
GitHub：【填入用户名/仓库名】

输出：
1. mkdocs.yml（含 site_name/site_description/site_author/site_url/repo_name/repo_url/markdown_extensions）
2. requirements.txt（mkdocs + 用到的插件，每行一个）

注意：YAML 缩进用空格，不用 Tab。

B. 专家增强版¶

你是一位 MkDocs 配置专家。

任务：生成完整正确的 mkdocs.yml 基础配置和依赖文件。

输入：
- 站点信息：【填入 site_name/描述/作者】
- GitHub 信息：【填入用户名/仓库名】
- 文档结构：【粘贴节点1结构】
- 特殊功能需求：【填入搜索/代码高亮/数学公式等】

处理步骤：
1. 配置站点元信息（site_name、site_description、site_author、site_url）
2. 配置仓库信息（repo_name、repo_url）—— site_url 和 repo_url 必须用实际的用户名/仓库名
3. 配置 markdown_extensions（代码高亮、admonition、目录等常用扩展）
4. 配置必要插件（search 等）
5. 生成对应的 requirements.txt（每个依赖一行，含版本下限）

site_url 格式说明：GitHub Pages 项目站点为 https://<用户名>.github.io/<仓库名>/

输出格式：
- 完整 mkdocs.yml（代码块，正确缩进）
- requirements.txt（代码块，每行一个依赖）
- 占位符替换说明（哪些需要用户改成自己的值）

约束：
- YAML 缩进统一用空格（2 空格），绝不用 Tab
- site_url 必须是正确的 GitHub Pages 格式
- requirements.txt 必须包含 mkdocs.yml 中用到的所有插件
- 不配置未安装的插件（否则构建失败）

质量标准：配置可直接用于 mkdocs build，不缺依赖、不报语法错。

常见失败情况：site_url 用了占位符没替换；配置了插件但 requirements.txt 没加导致构建失败；YAML 用了 Tab 缩进。

C. 自查审稿版¶

此为当前节点的自查模式，不是新的专家角色。

请检查以下 mkdocs.yml 配置是否存在以下问题：
1. YAML 缩进是否统一用空格（无 Tab）？
2. site_url 是否是正确的 GitHub Pages 格式（https://用户名.github.io/仓库名/）？
3. mkdocs.yml 中配置的每个插件是否都在 requirements.txt 中？
4. 是否配置了未安装的插件（会导致构建失败）？
5. 必填项（site_name 等）是否齐全？

【粘贴 mkdocs.yml 和 requirements.txt】

逐条说明问题。

D. 返修优化版¶

根据自查意见修正配置。统一缩进为空格，修正 site_url 格式，补齐 requirements.txt 中缺失的插件依赖，移除未安装的插件配置。

原始配置：【粘贴原始 mkdocs.yml 和 requirements.txt】
自查意见：【粘贴自查结果】

2.5 交付给下游节点¶

将 mkdocs.yml 和 requirements.txt 复制，交给节点 3（Material 主题专家）。主题配置将加入 mkdocs.yml。

2.6 人工验收清单¶

[ ] YAML 缩进是否统一用空格（无 Tab）？
[ ] site_url 是否是正确的 Pages 格式？
[ ] requirements.txt 是否包含所有配置的插件？
[ ] 必填项是否齐全？

节点 3：Material 主题专家¶

3.1 节点定位¶

配置 Material for MkDocs 主题，包括外观（配色、字体）和功能特性（导航、搜索、代码复制等）。Material 是 MkDocs 最流行的主题，合理配置能大幅提升文档站点的体验。

3.2 输入与输出¶

输入：节点 2 mkdocs.yml + 外观偏好

输出：theme 配置块（含 features 和 palette）+ requirements.txt 更新

3.3 使用顺序¶

先用「快速生成版」得到主题配置。
需要精细外观定制时，改用「专家增强版」。
用「自查审稿版」检查主题配置是否正确、依赖是否补充。
有问题则用「返修优化版」修正。
对照 3.6 验收清单确认，通过后交给节点 4。

3.4 提示词包¶

A. 快速生成版¶

你是一位 Material for MkDocs 配置助手。请生成主题配置。

当前 mkdocs.yml：【粘贴节点2配置】
外观偏好：【填入配色/明暗模式偏好】

输出：
1. theme 配置块（name: material + 常用 features + palette 明暗切换）
2. requirements.txt 需补充 mkdocs-material

注意：features 用列表格式，缩进正确。

B. 专家增强版¶

你是一位 Material for MkDocs 主题专家。

任务：配置 Material 主题，优化文档站点的外观和功能。

输入：
- 当前 mkdocs.yml：【粘贴节点2】
- 外观偏好：【填入配色/字体/明暗模式】
- 文档类型：【填入教程/电子书等，影响功能选择】

配置内容：
1. 主题基础（name: material，language 中文站设 zh）
2. 配色方案（palette，建议配置明暗模式切换）
3. 功能特性（features）：
   - navigation.tabs / navigation.sections（导航组织）
   - navigation.top（返回顶部）
   - search.highlight / search.suggest（搜索增强）
   - content.code.copy（代码块复制按钮）
   - toc.integrate / toc.follow（目录）
4. 更新 requirements.txt（添加 mkdocs-material）

输出格式：
- theme 配置块（完整 YAML，正确缩进）
- requirements.txt 更新说明
- 各 feature 作用说明

约束：features 必须是 Material 实际支持的（不编造）；中文站点 language 设为 zh；缩进规范。

质量标准：主题配置可直接合入 mkdocs.yml 并正常渲染，功能符合文档类型需求。

常见失败情况：配置了不存在的 feature 导致警告；忘记把 mkdocs-material 加入 requirements.txt；palette 配置缩进错误。

C. 自查审稿版¶

此为当前节点的自查模式，不是新的专家角色。

请检查以下 Material 主题配置是否存在以下问题：
1. features 是否都是 Material 实际支持的（无编造项）？
2. mkdocs-material 是否已加入 requirements.txt？
3. theme 配置块的 YAML 缩进是否正确？
4. 中文站点的 language 是否设为 zh？

【粘贴主题配置】

逐条说明问题。

D. 返修优化版¶

根据自查意见修正主题配置。移除不存在的 feature，补充 mkdocs-material 依赖，修正缩进，设置正确的 language。

原始配置：【粘贴原始配置】
自查意见：【粘贴自查结果】

3.5 交付给下游节点¶

将 theme 配置和更新的 requirements.txt 复制，交给节点 4（导航结构专家）。

3.6 人工验收清单¶

[ ] features 是否都是 Material 支持的项？
[ ] mkdocs-material 是否在 requirements.txt 中？
[ ] theme 配置缩进是否正确？

节点 4：导航结构专家¶

4.1 节点定位¶

配置 mkdocs.yml 的 nav 导航，将文档结构映射为站点导航菜单。nav 配置错误（引用不存在的文件）是 --strict 模式构建失败的最常见原因。

4.2 输入与输出¶

输入：节点 1 文档结构 + docs/ 实际文件清单

输出：nav 配置块（导航层级 + 文件路径映射）

4.3 使用顺序¶

先用「快速生成版」生成 nav 配置。
文档层级深或分组多时，改用「专家增强版」。
用「自查审稿版」检查 nav 引用的文件是否都存在。
有问题则用「返修优化版」修正。
对照 4.6 验收清单确认，通过后交给节点 5。

4.4 提示词包¶

A. 快速生成版¶

你是一位 MkDocs 导航配置助手。请生成 nav 配置。

文档结构：【粘贴节点1结构】
docs/ 实际文件清单：【粘贴 docs 下的文件列表】

输出：nav 配置块（YAML），导航标题对应文件路径。
注意：每个引用的文件路径必须是 docs/ 下真实存在的文件，路径相对 docs/。

B. 专家增强版¶

你是一位 MkDocs 导航配置专家。

任务：生成 nav 导航配置，确保所有引用的文件真实存在。

输入：
- 文档结构规划：【粘贴节点1】
- docs/ 实际文件清单：【粘贴 docs 目录下所有 .md 文件的真实路径】

处理步骤：
1. 将文档结构映射为 nav 层级
2. 每个导航项使用 "标题: 路径" 格式，路径相对 docs/ 目录
3. 用嵌套实现分组（一级菜单下嵌套二级）
4. 确保首页（index.md）在 nav 第一项
5. 逐一核对：nav 中每个路径都在实际文件清单中存在

输出格式：
- nav 配置块（完整 YAML，正确缩进）
- nav 路径与实际文件的对照核对表（路径 | 文件是否存在）

约束（关键）：
- nav 引用的每个文件必须在 docs/ 下真实存在（否则 --strict 构建失败）
- 路径相对于 docs/ 目录，不带 docs/ 前缀
- 缩进规范，嵌套层级清晰

质量标准：nav 配置不引用任何不存在的文件，mkdocs build --strict 不因 nav 报错。

常见失败情况：nav 引用了还没创建的文件导致 --strict 失败；路径写错（多了或少了 docs/ 前缀）；缩进错误导致层级混乱。

C. 自查审稿版¶

此为当前节点的自查模式，不是新的专家角色。

请检查以下 nav 配置是否存在以下问题：
1. nav 引用的每个文件路径是否都在 docs/ 实际文件清单中存在？
2. 路径是否正确（相对 docs/，不带 docs/ 前缀）？
3. index.md 是否在 nav 第一项？
4. 嵌套缩进是否正确？

【粘贴 nav 配置】
【粘贴 docs/ 实际文件清单】

逐条说明问题。

D. 返修优化版¶

根据自查意见修正 nav 配置。移除或修正引用不存在文件的路径，校正路径格式，调整缩进层级。

原始 nav：【粘贴原始 nav】
docs/ 实际文件清单：【粘贴文件清单】
自查意见：【粘贴自查结果】

4.5 交付给下游节点¶

将完整的 mkdocs.yml（含 site/theme/nav）复制，交给节点 5（Markdown 质量检查专家）。

4.6 人工验收清单¶

[ ] nav 引用的每个文件是否都真实存在？
[ ] 路径格式是否正确（相对 docs/）？
[ ] index.md 是否在第一项？
[ ] 嵌套缩进是否正确？

节点 5：Markdown 质量检查专家¶

5.1 节点定位¶

检查 Markdown 文档的格式问题，重点是会导致渲染异常或构建失败的问题。常见如代码块未闭合、链接失效、图片路径错误。

5.2 输入与输出¶

输入：docs/ 下的 Markdown 文档

输出：Markdown 问题清单 + 修正建议

5.3 使用顺序¶

先用「快速生成版」检查常见格式问题。
文档多或问题复杂时，改用「专家增强版」。
用「自查审稿版」确认检查无遗漏。
有问题则用「返修优化版」修正。
对照 5.6 验收清单确认，通过后交给节点 6。

5.4 提示词包¶

A. 快速生成版¶

你是一位 Markdown 质量检查员。请检查以下文档。

文档内容：【粘贴 Markdown】

检查：
1. 代码块是否成对闭合（```）
2. 链接和图片路径是否有效
3. 标题层级是否合理（不跳级）
4. 表格语法是否正确

输出：问题清单（位置 + 问题 + 修正）

B. 专家增强版¶

你是一位技术文档质量专家。

任务：检查 Markdown 文档中会导致渲染异常或构建问题的格式错误。

输入：
- 文档内容：【粘贴 Markdown，或逐个文件检查】

检查项：
1. 代码块闭合（每个 ``` 是否成对，语言标注是否正确）
2. 嵌套代码块（文档中展示代码块时的转义/缩进是否正确）
3. 链接有效性（内部链接指向的文件/锚点是否存在，外部链接格式是否正确）
4. 图片路径（相对路径是否正确，图片文件是否存在）
5. 标题层级（是否从 h1 开始，是否跳级）
6. 表格语法（分隔行、对齐语法是否正确）
7. 列表缩进（有序/无序列表嵌套缩进是否一致）
8. 特殊字符转义（需要转义的字符是否处理）

输出格式：
| 文件/位置 | 问题类型 | 问题描述 | 修正建议 |

约束：重点关注会导致 --strict 构建失败或渲染错乱的问题；区分"必须修复"和"建议优化"。

质量标准：修正后文档可通过 mkdocs build --strict，渲染正常。

常见失败情况：代码块未闭合导致后续内容全部被吞；内部链接指向不存在的文件导致 --strict 失败；图片路径错误导致图裂。

C. 自查审稿版¶

此为当前节点的自查模式，不是新的专家角色。

请检查以下 Markdown 检查结果是否存在以下问题：
1. 是否检查了代码块闭合（最易导致渲染错乱）？
2. 是否检查了内部链接指向的文件是否存在（--strict 会因此失败）？
3. 是否区分了"必须修复"和"建议优化"？
4. 修正建议是否具体到位置？

【粘贴 Markdown 检查结果】

逐条说明问题。

D. 返修优化版¶

根据自查意见完善 Markdown 检查。补充代码块闭合和内部链接检查，区分问题严重度，明确修正位置。

原始检查结果：【粘贴原始结果】
自查意见：【粘贴自查结果】

5.5 交付给下游节点¶

将 Markdown 问题清单（修正后）复制，交给节点 6（GitHub Actions 部署专家）。文档质量达标后再配置自动部署。

5.6 人工验收清单¶

[ ] 是否检查了代码块闭合？
[ ] 是否检查了内部链接指向的文件存在性？
[ ] 是否区分了必须修复和建议优化？

节点 6：GitHub Actions 部署专家¶

6.1 节点定位¶

生成 GitHub Actions 自动部署配置，实现推送即自动构建和发布到 GitHub Pages。自动部署免去每次手动构建上传的麻烦。

6.2 输入与输出¶

输入：节点 2 requirements.txt + 部署需求

输出：.github/workflows/deploy.yml + 权限说明

6.3 使用顺序¶

先用「快速生成版」生成部署配置。
需要特定部署方式或缓存优化时，改用「专家增强版」。
用「自查审稿版」检查 YAML 正确性、权限配置。
有问题则用「返修优化版」修正。
对照 6.6 验收清单确认，通过后交给节点 7。

6.4 提示词包¶

A. 快速生成版¶

你是一位 GitHub Actions 配置助手。请生成 MkDocs 部署到 GitHub Pages 的 workflow。

requirements.txt：【粘贴节点2】
触发分支：【填入 main 等】

输出 .github/workflows/deploy.yml：
- 触发：push 到主分支 + 手动触发
- 步骤：checkout → setup-python → 安装依赖 → mkdocs build --strict → 部署到 Pages
- 包含必要权限（pages: write, id-token: write）

注意 YAML 缩进正确。

B. 专家增强版¶

你是一位 GitHub Actions 与 MkDocs 部署专家。

任务：生成可靠的 GitHub Pages 自动部署 workflow。

输入：
- requirements.txt：【粘贴节点2】
- 触发分支：【填入主分支名】
- Python 版本偏好：【填入或用默认】

workflow 内容：
1. 触发条件（push 到主分支 + workflow_dispatch 手动触发）
2. 权限设置（pages: write, id-token: write, contents: read）
3. 构建 job：
   - actions/checkout
   - actions/setup-python（指定版本）
   - pip install -r requirements.txt
   - mkdocs build --strict（strict 模式确保问题暴露）
   - actions/upload-pages-artifact
4. 部署 job：
   - actions/deploy-pages
   - environment: github-pages

输出格式：
- 完整 deploy.yml（代码块，正确缩进）
- 权限说明（每个权限的作用）
- 使用前提（需在 Pages 设置中将 Source 设为 GitHub Actions —— 由节点7处理）

约束：
- YAML 缩进规范（2 空格）
- 使用 mkdocs build --strict（不是普通 build）
- 权限遵循最小必要原则
- 使用稳定版本的 actions

质量标准：配置正确，推送后能自动构建并部署，构建失败时能在 Actions 日志看到原因。

常见失败情况：缺少 pages 写权限导致部署失败；用了普通 build 而非 --strict 导致问题被掩盖；YAML 缩进错误导致 workflow 无效。

C. 自查审稿版¶

此为当前节点的自查模式，不是新的专家角色。

请检查以下部署 workflow 是否存在以下问题：
1. 是否包含 Pages 部署所需权限（pages: write, id-token: write）？
2. 构建是否用了 mkdocs build --strict（而非普通 build）？
3. YAML 缩进是否正确？
4. 是否包含手动触发（workflow_dispatch）？

【粘贴 deploy.yml】

逐条说明问题。

D. 返修优化版¶

根据自查意见修正部署配置。补充 Pages 权限，改用 --strict 构建，修正 YAML 缩进，添加手动触发。

原始配置：【粘贴原始 deploy.yml】
自查意见：【粘贴自查结果】

6.5 交付给下游节点¶

将 deploy.yml 复制，交给节点 7（GitHub Pages 配置专家）。deploy.yml 需配合 Pages 的 Source 设置才能生效。

6.6 人工验收清单¶

[ ] 是否包含 Pages 部署权限？
[ ] 是否用了 mkdocs build --strict？
[ ] YAML 缩进是否正确？
[ ] 是否包含手动触发？

节点 7：GitHub Pages 配置专家¶

7.1 节点定位¶

提供 GitHub Pages 的设置步骤，将 Source 配置为 GitHub Actions。这一步常被遗漏，导致 Actions 构建成功但 Pages 仍是 404。

7.2 输入与输出¶

输入：节点 6 deploy.yml + 仓库 URL

输出：GitHub Pages 设置步骤 + 验证方法

7.3 使用顺序¶

先用「快速生成版」得到 Pages 设置步骤。
涉及自定义域名或特殊配置时，改用「专家增强版」。
用「自查审稿版」检查步骤是否完整。
有问题则用「返修优化版」补充。
对照 7.6 验收清单确认，通过后交给节点 8。

7.4 提示词包¶

A. 快速生成版¶

你是一位 GitHub Pages 配置向导。请说明如何设置 Pages 使用 Actions 部署。

仓库：【填入用户名/仓库名】

输出：
1. Pages 设置步骤（Settings → Pages → Source 选 GitHub Actions）
2. 站点访问地址（https://用户名.github.io/仓库名/）
3. 首次部署后的验证方法

B. 专家增强版¶

你是一位 GitHub Pages 部署专家。

任务：提供完整的 GitHub Pages 设置步骤，确保 Actions 部署生效。

输入：
- deploy.yml：【确认已就位】
- 仓库 URL：【填入】

步骤：
1. 进入仓库 Settings → Pages
2. Build and deployment → Source → 选择 "GitHub Actions"（不是 "Deploy from a branch"）
3. 推送代码触发 Actions，或在 Actions 页面手动运行 workflow
4. 等待 Actions 完成（构建 + 部署两个 job 都成功）
5. 访问站点地址确认：https://<用户名>.github.io/<仓库名>/

验证与排查：
- 若 Actions 成功但 Pages 404：检查 Source 是否设为 GitHub Actions
- 若 Actions 失败：查看日志（多为构建错误，转节点8处理）
- 若页面样式丢失：检查 mkdocs.yml 的 site_url 是否正确

输出格式：
- 设置步骤（带界面路径）
- 站点访问地址
- 常见问题排查表

约束：明确 Source 必须选 "GitHub Actions"；站点地址用实际用户名/仓库名；区分 Actions 失败和 Pages 配置问题。

质量标准：按步骤操作后站点可访问；遇到问题能定位是配置还是构建问题。

常见失败情况：Source 仍是 "Deploy from a branch" 导致 Actions 部署不生效；site_url 错误导致 CSS/JS 加载失败页面无样式。

C. 自查审稿版¶

此为当前节点的自查模式，不是新的专家角色。

请检查以下 Pages 设置步骤是否存在以下问题：
1. 是否明确说明 Source 要选 "GitHub Actions"（而非 Deploy from a branch）？
2. 站点访问地址格式是否正确？
3. 是否包含"Actions 成功但 Pages 404"的排查（最常见问题）？

【粘贴 Pages 设置步骤】

逐条说明问题。

D. 返修优化版¶

根据自查意见完善 Pages 设置步骤。强调 Source 选 GitHub Actions，修正站点地址格式，补充 404 排查。

原始步骤：【粘贴原始步骤】
自查意见：【粘贴自查结果】

7.5 交付给下游节点¶

将 Pages 设置步骤复制，交给节点 8（构建错误修复专家）。若部署遇到构建错误，由节点 8 处理。

7.6 人工验收清单¶

[ ] 是否明确 Source 要选 GitHub Actions？
[ ] 站点地址格式是否正确？
[ ] 是否包含 Pages 404 的排查？

节点 8：构建错误修复专家（招牌节点）¶

8.1 节点定位¶

这是本工作流的招牌节点。 系统性诊断和修复 MkDocs 构建与发布中的各类错误。本节点覆盖以下高频错误，并提供基于真实命令的定位方法：

错误类型	典型表现
nav 引用不存在的文件	`--strict` 报 "is included in nav but not found"
requirements.txt 依赖缺失	构建报 "module not found" / 插件未安装
YAML 缩进错误	配置解析失败 / workflow 不触发
Markdown 代码块未闭合	渲染错乱 / 后续内容被吞
GitHub Pages Source 配置错误	Actions 成功但页面 404
Actions 权限不足	部署 job 报权限错误
site_url / repo_url 配置错误	页面无样式 / 链接错误
mkdocs build --strict 报错	各类警告在 strict 下变为错误

8.2 输入与输出¶

输入：构建错误信息（本地或 Actions 日志）+ 相关配置文件

输出：错误诊断（错误类型 + 根因 + 定位命令）+ 修复方案

8.3 使用顺序¶

先用「快速生成版」诊断常见错误。
错误复杂或多个错误叠加时，使用「专家增强版」。
用「自查审稿版」确认修复是否对症。
有问题则用「返修优化版」修正。
对照 8.6 验收清单确认，通过后交给节点 9。

8.4 提示词包¶

A. 快速生成版¶

你是一位 MkDocs 构建排错助手。请诊断以下构建错误。

错误信息：【粘贴报错（本地或 Actions 日志）】
相关配置：【粘贴 mkdocs.yml / requirements.txt 相关部分】

输出：
1. 错误类型
2. 根因
3. 修复方法
4. 验证命令（如 mkdocs build --strict）

常见错误参考：nav 引用不存在文件、依赖缺失、YAML 缩进、代码块未闭合、Pages Source 配置、权限不足、site_url 错误。

B. 专家增强版¶

你是一位 MkDocs 与 GitHub Pages 部署排错专家。

任务：系统诊断构建/部署错误，给出根因和可执行的修复方案。

输入：
- 错误信息：【粘贴完整报错或 Actions 日志】
- 相关配置：【粘贴 mkdocs.yml / requirements.txt / deploy.yml】
- 错误发生阶段：【本地 build / Actions 构建 / Pages 访问】

诊断流程（按错误类型）：

1. nav 引用不存在的文件
   - 表现：`The following pages exist in the docs directory, but are not included in the "nav"` 或 nav 引用的文件 not found
   - 定位：核对 nav 中路径与 docs/ 实际文件
   - 修复：移除或修正错误路径 / 创建缺失文件

2. requirements.txt 依赖缺失
   - 表现：构建报 plugin/module not found
   - 定位：对比 mkdocs.yml 用到的插件与 requirements.txt
   - 修复：补充缺失依赖

3. YAML 缩进错误
   - 表现：config 解析失败 / workflow 不触发
   - 定位：检查缩进是否用了 Tab、层级是否对齐
   - 修复：统一为 2 空格缩进

4. Markdown 代码块未闭合
   - 表现：渲染错乱、后续内容被当作代码
   - 定位：搜索单数个 ``` 的文件
   - 修复：补齐闭合标记

5. Pages Source 配置错误
   - 表现：Actions 成功但访问 404
   - 修复：Settings → Pages → Source 设为 GitHub Actions

6. Actions 权限不足
   - 表现：部署 job 报 permission denied
   - 修复：在 workflow 中补充 pages: write, id-token: write

7. site_url / repo_url 错误
   - 表现：页面无样式、链接 404
   - 修复：site_url 设为 https://<用户名>.github.io/<仓库名>/

定位常用命令（提醒按实际替换）：

pip install -r requirements.txt # 确认依赖可安装 mkdocs serve # 本地预览，实时看错误 mkdocs build --strict # 严格构建，暴露所有问题 git status # 查看改动和未跟踪文件 git add . git commit -m "fix: 修复构建错误" git push

输出格式：
- 错误类型判定
- 根因分析
- 修复步骤（具体到改哪个文件哪一行）
- 验证命令
- 修复后预期结果

约束：每个错误必须给出根因而非只说"配置错了"；修复步骤可执行；提供验证命令确认修复有效。

质量标准：用户按修复方案操作后，mkdocs build --strict 通过、Pages 正常访问。

常见失败情况：只说"检查配置"不定位具体问题；修复一个错误引入另一个；不提供验证手段。

C. 自查审稿版¶

此为当前节点的自查模式，不是新的专家角色。

请检查以下构建错误修复方案是否存在以下问题：
1. 是否定位到了具体根因（而非笼统的"配置有误"）？
2. 修复步骤是否具体到文件和位置？
3. 是否提供了验证命令（mkdocs build --strict 等）确认修复有效？
4. 修复是否可能引入新问题？

【粘贴构建错误修复方案】

逐条说明问题。

D. 返修优化版¶

根据自查意见完善修复方案。明确根因，将修复步骤具体到文件位置，补充验证命令，排查修复引入新问题的可能。

原始方案：【粘贴原始方案】
自查意见：【粘贴自查结果】

8.5 交付给下游节点¶

将错误修复方案应用后，将通过构建的配置交给节点 9（发布验收专家）。

8.6 人工验收清单¶

[ ] 是否定位到了具体错误根因？
[ ] 修复步骤是否具体到文件和位置？
[ ] 是否提供了验证命令？
[ ] 修复后 mkdocs build --strict 是否通过？

节点 9：发布验收专家¶

9.1 节点定位¶

对发布的文档站点进行最终验收，确认站点可访问、内容完整、功能正常。验收是发布闭环的最后一步。

9.2 输入与输出¶

输入：站点 URL + 全部前序产出

输出：发布验收清单结果 + 遗留问题

9.3 使用顺序¶

先用「快速生成版」做发布验收。
正式发布需要全面验收时，改用「专家增强版」。
用「自查审稿版」确认验收无遗漏。
有遗留问题则返回对应节点处理。
对照 9.6 验收清单确认。

9.4 提示词包¶

A. 快速生成版¶

你是一位站点发布验收员。请提供 MkDocs 站点发布验收清单。

站点 URL：【填入】

验收清单：
- [ ] 站点可访问（非 404）
- [ ] 首页正常显示
- [ ] 导航链接都能打开
- [ ] 样式正常（非纯文本）
- [ ] 搜索功能可用
- [ ] 代码块渲染正常

B. 专家增强版¶

你是一位文档站点发布验收专家。

任务：对发布的 MkDocs 站点进行全面验收。

输入：
- 站点 URL：【填入】
- 文档结构：【粘贴节点1】

验收维度：
1. 可访问性（站点能打开，非 404）
2. 首页（index.md 内容正常显示）
3. 导航完整性（nav 所有链接可打开，无死链）
4. 样式渲染（Material 主题样式加载正常，非纯文本 —— 若无样式多为 site_url 错误）
5. 内容渲染（代码块高亮、表格、admonition 等渲染正常）
6. 功能性（搜索可用、明暗切换可用、代码复制按钮可用）
7. 移动端（在窄屏下布局正常）
8. 构建状态（最近一次 Actions 构建成功）

输出格式：
- 验收清单（逐项可勾选 + 状态）
- 遗留问题清单（问题 | 对应处理节点）
- 总体结论（可发布 / 需修复）

约束：验收必须实际访问站点确认，不能仅看配置；样式异常优先怀疑 site_url。

质量标准：通过验收的站点对访问者完全可用，无死链、无样式问题。

常见失败情况：站点能开但无样式（site_url 错）；部分导航链接 404（nav 路径错）；只在桌面端测没测移动端。

C. 自查审稿版¶

此为当前节点的自查模式，不是新的专家角色。

请检查以下发布验收清单是否存在以下问题：
1. 是否包含样式渲染检查（site_url 错误的典型表现）？
2. 是否检查了所有导航链接的有效性？
3. 是否包含移动端检查？
4. 遗留问题是否标注了对应的处理节点？

【粘贴发布验收清单】

逐条说明问题。

D. 返修优化版¶

根据自查意见完善发布验收清单。补充样式和导航链接检查，增加移动端验收，为遗留问题标注处理节点。

原始清单：【粘贴原始清单】
自查意见：【粘贴自查结果】

9.5 交付给下游节点¶

本节点是工作流终点。验收通过后，文档站点正式发布。存在遗留问题时返回对应节点处理（多数构建问题回节点 8）。

9.6 人工验收清单¶

[ ] 站点是否可访问（非 404）？
[ ] 样式是否正常加载（非纯文本）？
[ ] 所有导航链接是否可打开？
[ ] 搜索、代码块等功能是否正常？

节点交接说明¶

上游节点	交接内容	下游节点
节点 1 结构规划	docs/ 目录结构	节点 2、节点 4
节点 2 MkDocs 配置	mkdocs.yml 基础 + requirements.txt	节点 3
节点 3 Material 主题	theme 配置 + 依赖更新	节点 4
节点 4 导航结构	nav 配置（完整 mkdocs.yml）	节点 5
节点 5 Markdown 检查	文档问题清单 + 修正	节点 6
节点 6 Actions 部署	deploy.yml	节点 7
节点 7 Pages 配置	Pages 设置步骤	节点 8
节点 8 构建错误修复	错误诊断 + 修复（通过构建的配置）	节点 9
节点 9 发布验收	验收清单结果	最终输出模板

最终输出模板¶

【站点名】MkDocs 发布包

━━ 站点信息 ━━
站点名：【填入】
站点地址：https://<用户名>.github.io/<仓库名>/
文档数量：【填入】

━━ 配置文件清单 ━━
- mkdocs.yml（site + theme + nav）
- requirements.txt
- .github/workflows/deploy.yml
- docs/（文档目录）

━━ 发布步骤 ━━
1. 确认 mkdocs build --strict 本地通过
2. 推送代码到主分支
3. Settings → Pages → Source 设为 GitHub Actions
4. 等待 Actions 完成（构建 + 部署）
5. 访问站点地址验收

━━ 本地验证命令 ━━
pip install -r requirements.txt
mkdocs serve              # 本地预览
mkdocs build --strict     # 严格构建检查

━━ 发布验收 ━━
- [ ] 站点可访问
- [ ] 样式正常
- [ ] 导航无死链
- [ ] 功能正常
- [ ] Actions 构建成功

常见错误¶

错误 1：nav 引用了不存在的文件

表现：mkdocs build --strict 报错 "nav 中引用的文件未找到"，构建失败。

修复：执行节点 8（招牌节点）的 nav 诊断，逐一核对 nav 路径与 docs/ 实际文件，移除或修正错误引用、或创建缺失文件。

错误 2：Actions 构建成功但 Pages 显示 404

表现：GitHub Actions 全绿，但访问站点地址是 404。

修复：执行节点 7，确认 Settings → Pages → Source 设为 "GitHub Actions"（而非 "Deploy from a branch"）。这是最易遗漏的一步。

错误 3：页面能打开但完全没有样式

表现：站点是纯文本，Material 主题样式全部丢失。

修复：执行节点 8 的 site_url 诊断，确认 mkdocs.yml 的 site_url 是正确的 https://<用户名>.github.io/<仓库名>/ 格式。site_url 错误会导致 CSS/JS 加载路径错误。

人工验收清单¶

[ ] mkdocs.yml 配置是否正确（缩进/site_url/依赖完整）？
[ ] nav 引用的所有文件是否都存在？
[ ] mkdocs build --strict 是否本地通过？
[ ] GitHub Pages Source 是否设为 GitHub Actions？
[ ] 站点是否可访问且样式、导航、功能都正常？

延伸玩法¶

变体 1：本地预览优先版：跳过部署节点（6/7），只走节点 1-5 + 节点 8，用 mkdocs serve 在本地完成文档站点，适合内部文档或尚未公开的项目。
变体 2：已有站点维护版：对已发布的 MkDocs 站点新增文档，重点走节点 4（更新 nav）→ 节点 5（检查新文档）→ 节点 8（修复构建问题），跳过初始配置。
进阶组合：与"工作流 14（GitHub 发布工作流）"结合，代码仓库和文档站点一并发布；本图鉴项目本身即用此工作流发布，是工作流的实际应用范例。