mkdocs-site-bootstrap

mkdocs-site-bootstrap

为代码仓库引导搭建 MkDocs Material 文档站点（并可选择部署），之后持续协助用户添加页面。

此技能需要征得同意。它会将用户偏好记录在 .skills/preferences.yaml 中，且不会在未经明确请求的情况下迁移现有内容或配置。默认情况下，迁移命令只执行审查，只有使用 --apply 才会写入。如果用户改变主意， scripts/check-preferences.sh --reset mkdocs_site_bootstrap 会清除已记录的决定，让下次调用从头开始。

触发时机

• 用户要求“设置文档”“创建文档站点”“添加文档 站点”或“将文档发布到 GitHub Pages”
• 用户有零散的 Markdown 笔记或 docs/ 目录，并希望能浏览其中的内容
• 用户希望将 daviddwlee84/agent-skills 代码仓库使用的同一套文档技术栈 应用到新项目
• 用户想要适合大模型使用的文档站点（llms.txt、复制到大模型）
• 用户要求“中英双语文档”“雙語 docs”“i18n”“多语言文档”、 “添加繁体中文”“添加 zh-TW”“翻译文档”，或要求为现有站点添加 任意非英语语言 → 跳转到步骤 7
• 用户报告 llms.txt / llms-full.txt 变为空、只包含一种语言，或添加 i18n 导致严格构建失败 → 跳转到步骤 8

不要触发的情况

• 用户只想编写单个文档文件 → 不要搭建整个站点
• 用户明确选择退出（preferences.yaml 中为 enabled: false）→ 暂缓， 除非用户现在要撤销该决定
• 用户想评估或基准测试技能 → 使用 skill-creator
• 用户想编写新的 Agent 技能 → 使用 skill-author

工作流

1. 首先读取偏好设置

执行任何操作前，检查此代码仓库是否已记录决定：

bash skills/local/mkdocs-site-bootstrap/scripts/check-preferences.sh \
  --get mkdocs_site_bootstrap

可能的状态：

状态	含义	操作
文件不存在或缺少键	从未询问	继续步骤 2（访谈）
enabled: true, pages_deployed: true	站点已上线	跳至步骤 6（后续协助）
enabled: true, pages_deployed: false	已搭建但尚未部署	跳至步骤 5（部署）
enabled: false	用户选择退出	确认用户是否要撤销该决定，然后执行 --reset 并重新运行

2. 访谈（仅当尚无记录的决定时）

明确询问用户：

1. “您希望为此项目创建 MkDocs Material 文档站点吗？ （是 / 否 / 我再考虑一下）”
2. 如果回答是：“需要在推送到 main 时自动部署到 GitHub Pages 吗？ （是 / 否 — 我会手动部署）”

立即记录两个回答，避免会话中断导致回答丢失：

bash skills/local/mkdocs-site-bootstrap/scripts/check-preferences.sh \
  --set mkdocs_site_bootstrap.enabled=true \
  --set mkdocs_site_bootstrap.stack=mkdocs-material \
  --set mkdocs_site_bootstrap.auto_deploy=true

如果用户回答否，则记录 enabled: false 并停止。今后调用时不要再打扰用户。

3. 检测现有文档（征得同意）

搭建前，扫描目标代码仓库。请阅读 references/existing-docs-handling.md，了解完整决策流程；简要说明如下：

• 如果已存在 mkdocs.yml → 报告“看起来 处已存在 mkdocs 站点；不覆盖”，然后停止。
• 如果 docs/ 存在且非空 → 列出文件，并让用户选择以下其中一项： (a) 跳过 — 保留我的文档，只创建 mkdocs.yml 指向这些文档， 省略 nav，使用文件系统自动导航； (b) 包装 — 创建 mkdocs.yml，在显式的字母顺序导航中按原样包含我的 Markdown 路径； (c) 手动 — 让我先重新整理，然后重新运行。
• 如果两者都不存在 → 可以安全地从头搭建。

将此决定记录在 mkdocs_site_bootstrap.existing_docs_decision 下。

4. 搭建脚手架

运行 init-docs-site.sh。该脚本会写入（或拒绝覆盖）mkdocs.yml、 pyproject.toml（包含 [project.optional-dependencies] docs = […]）、docs/ 骨架、.github/workflows/docs.yml、由脚本管理的 scripts/build-docs-site.py 辅助脚本，以及用于 copy-to-llm 的占位资源。它还会将 /site/（构建输出目录）追加到 .gitignore，确保生成的网站不会被提交；启用 --social 时，还会追加 /.cache/。

bash skills/local/mkdocs-site-bootstrap/scripts/init-docs-site.sh \
  --site-name "My Project" \
  --repo-slug owner/repo \
  --site-url https://owner.github.io/repo/

先使用 --dry-run 预览。除非传入 --force，否则脚本始终会保留已有文件；如果现有 docs/ 目录树中的任何位置存在符号链接，脚本都会拒绝执行，以免在仓库外写入文件。在 skip 和 wrap 模式下，脚本会省略 copy-to-llm，因为它的构建钩子会在 docs/ 下写入生成的资源；用户可在确定这些生成文件的存放位置后，自行选择启用该插件。

添加 --social 可启用 OG/Twitter 预览卡片（参见 Gotchas →“社交卡片默认不启用”）。除非用户需要丰富的链接展开效果，且能接受 Cairo/Pango 系统依赖，否则请勿启用；普通脚手架无需依赖即可构建。

搭建脚手架后，构建完整的严格模式产物：

uv sync --extra docs
uv run python scripts/build-docs-site.py

对于保留 llmstxt 的多语言网站，这会运行两次相互隔离的严格模式构建：先生成默认语言的 LLM 输出，再构建完整的多语言 HTML 网站。直接运行 uv run mkdocs build --strict 仍可安全地预览纯 HTML，因为 mkdocs.yml 默认禁用了 llmstxt；如果 /llms.txt 是网站约定的一部分，请勿部署该预览。

5. 启用 Pages 并触发首次部署（需征得同意）

此操作会调用 GitHub API（gh api -X POST .../pages -f build_type=workflow），然后触发工作流。务必先向用户确认——准确说明你即将执行的 API 调用及其影响的仓库。只有得到明确同意后才能继续。

bash skills/local/mkdocs-site-bootstrap/scripts/enable-pages.sh \
  --repo owner/repo

标志：

• --dry-run — 输出 gh 调用，但不实际运行
• --no-trigger — 启用 Pages，但暂不运行工作流

成功后，在偏好设置中设置 pages_deployed=true 和 pages_enabled_at=$(date +%F)。

6. 持续维护：添加文档页面

对于用户需要的每个新文档，请使用辅助脚本，而不要手动编辑 mkdocs.yml：

bash skills/local/mkdocs-site-bootstrap/scripts/add-docs-page.sh \
  --section workflows \
  --title "My new workflow" \
  --slug my-new-workflow

该脚本会根据页面模板创建 docs/<section>/<slug>.md，并在 mkdocs.yml 中对应的章节标题下插入导航条目。操作具有幂等性——使用相同的 slug 再次运行时不会产生任何更改。

如果项目在 .skills/preferences.yaml（mkdocs_site_bootstrap.languages）中配置了其他语言，add-docs-page.sh 还会为每种非默认语言生成 *.<LANG>.md 占位文件，并预先插入术语规则提示。使用 --lang LANG 可仅为一种指定语言添加译文，而不重新创建默认语言页面。

7. 可选：添加非英语语言

此技能通过 mkdocs-static-i18n 插件支持双语／多语言网站（后缀布局：index.md + index.zh-TW.md）。 此步骤为可选项，与初始引导过程相互独立。

触发条件：用户提出“bilingual docs”“雙語 docs”“add zh-TW”“i18n”“add Traditional Chinese”“translate the docs”或类似请求。

先阅读 references/i18n-guide.md — 其中介绍了术语保留规则（首次提及时使用“中文 (English original)”格式；不得自行创造译法），作者必须在非英语页面中遵循此规则。

然后运行：

bash skills/local/mkdocs-site-bootstrap/scripts/add-language.sh \
  --lang zh-TW

此操作会将 i18n 插件插入 mkdocs.yml，为每个现有页面创建 *.zh-TW.md 同名占位文件（预先加入术语提示），安装／配置托管的严格构建辅助工具，启用两阶段构建所需的插件保护，在 pyproject.toml 中取消注释 mkdocs-static-i18n，并在 .skills/preferences.yaml 中记录此选择。具备幂等性 — 使用相同的 --lang 重新运行时不会执行任何操作。

--remove-llmstxt 仍是显式选择退出的选项。旧版 --drop-strict 标记已弃用且无操作，因为移除严格模式从未能修复损坏的输出；--keep-llmstxt 则作为今日默认行为的弃用别名接受。

运行完成后，重新同步依赖并重新构建：

uv sync --extra docs
uv run python scripts/build-docs-site.py

脚本运行完成后 — 翻译是单独的步骤

add-language.sh 只会生成结构性占位内容：每个 *.<LANG>.md 占位文件都包含术语提示和“Translation pending”警告。脚本绝不会自动翻译正文，因为 LLM 翻译经常违反“不得自行创造译法”的术语规则（例如，在没有规范译法时，为 embedding 创造「嵌入」／「向量」／「内嵌」等译法）。

占位文件创建后，明确询问用户是否现在翻译这些文件 — 不要自行假定。可采用如下话术：

“占位文件已创建。要我现在逐页翻译正文吗？我会每批处理 4–6 个页面，在每批之间运行 mkdocs build 进行验证，并遵循术语规则（首次提及时保留英文原文，绝不自行创造译法）。”

只有在用户明确同意后才继续。如果用户决定稍后再做，请保留占位文件 — 它们已经是有效页面，且构建能够通过。

翻译时，还应询问用户是否要为顶级章节标题在 mkdocs.yml 中填写 nav_translations（参见 references/i18n-guide.md 中的 §nav_translations）。这与页面正文翻译相互独立，用户可能只需要其中一项。

8. 修复旧版 i18n + llmstxt 脚手架

更新已安装的技能只会下载新工具，不会重写下游项目。迁移现有网站前，请先阅读 references/i18n-llmstxt-migration.md，然后先进行审查：

npx skills@latest update mkdocs-site-bootstrap --project --yes
bash .agents/skills/mkdocs-site-bootstrap/scripts/migrate-i18n-llmstxt.sh \
  --target-dir . --json

退出码 10 表示检测到了受影响的旧版结构（包括试运行预览）。使用 --apply --dry-run 预览保守补丁，然后运行 --apply --verify。迁移过程只会修补可识别、由脚手架管理的结构；自定义的 docs_dir、插件保护规则、CI、Makefile 或外部构建辅助工具会被明确列为手动操作，而不会遭到覆盖。系统也会逐一报告本地化源文件中不安全的相对 llms／sidecar 链接，要求手动替换为基于 site_url 的 URL。

可用脚本

• scripts/check-preferences.sh — 读取、设置或重置 .skills/preferences.yaml。始终可以安全运行。
  • 标志：--get KEY、--set KEY=VALUE（可重复使用）、--reset NAMESPACE、 --list、--dry-run、--json。
• scripts/init-docs-site.sh — 搭建站点文件。
  • 标志：--site-name、--repo-slug、--site-url、--existing skip|wrap、 --no-workflow、--no-skeleton、--social、--dry-run、--force。
  • 始终会将 /site/（mkdocs build 的输出目录）追加到 .gitignore， 且此操作具有幂等性。
  • --social 可选择启用 OG/Twitter 卡片：使用 assets/social/ 中的区块 展开模板里的 __SOCIAL_*__ 标记，并将 /.cache/ 添加到 .gitignore。默认关闭（确保搭建过程无需 Cairo/Pango）。
• 项目本地的 scripts/build-docs-site.py — 规范的严格生产构建辅助脚本， 从 assets/build-docs-site.py 复制到每个搭建好的站点中。单语站点使用一次 构建；带有 llmstxt 的多语言站点会隔离默认语言的 LLM 输出与完整 HTML 构建， 验证合并后的产物，然后仅在所有检查通过后替换 site/。JSON 输出到 stdout；构建诊断信息输出到 stderr。
  • 标志：--target-dir DIR、--config-file FILE、--site-dir DIR、 --dry-run、--keep-temp。
  • 退出码：0 成功；2 输入无效或缺失；3 MkDocs 构建失败； 4 生成的输出未通过验证。
• scripts/enable-pages.sh — 通过 gh api 启用 Pages 并触发首次部署。 需要先通过 gh auth status 检查。
  • 标志：--repo OWNER/REPO、--no-trigger、--dry-run。
• scripts/add-docs-page.sh — 创建新页面，在存在显式导航时更新导航， 并保持 llmstxt.sections 同步。使用自动导航（省略 nav）时，_root 页面仍通过文件系统发现，而不会创建不完整的显式导航。命名的 --section 必须已存在，并且会在写入任何页面前进行验证。如果配置了多种语言，还会为 每种非默认语言创建 *.<LANG>.md 桩文件。
  • 标志：--section、--title、--slug、--template PATH、--lang LANG （仅限单语言桩文件）、--dry-run、--force。
• scripts/add-language.sh — 为现有站点补充一种非默认语言。插入 plugins.i18n，创建带有术语提示的 *.<LANG>.md 桩文件，更新偏好设置， 取消注释 static-i18n 依赖项，并配置受管理的严格构建路径。默认保留默认语言 的 mkdocs-llmstxt 输出。具有幂等性。
  • 标志：--lang LANG（必需）、--name NAME、--default-lang LANG、 --target-dir DIR、--no-stubs、--remove-llmstxt、已弃用的 --drop-strict / --keep-llmstxt、--dry-run、--force。
  • 退出码 11 表示已添加该语言，但自定义的下游结构仍需按照迁移指南手动处理。
• scripts/migrate-i18n-llmstxt.sh — 审查或谨慎迁移由此技能旧版本创建的 下游站点。默认执行审查；写入需要指定 --apply。JSON 输出到 stdout；诊断信息 输出到 stderr。脚本会先暂存并验证候选内容，再进行替换；具有幂等性，且绝不会 覆盖其他构建辅助脚本。
  • 标志：--target-dir DIR、--apply、--dry-run、--verify、--json。
  • 退出码：0 安全／已迁移；10 在审查／试运行期间发现受影响的旧配置； 11 仍需手动处理；12 严格验证失败。

参考文件

• references/preferences-schema.md — .skills/preferences.yaml 的架构，以及跨技能使用约定。首次修改某个 preferences 键时，请阅读此文件。
• references/existing-docs-handling.md — 处理用户现有 docs/ 内容的完整决策树，避免意外情况。每次全新初始化前，请在步骤 3 之前阅读此文件。
• references/docs-stack-recipe.md — 完整的技术栈配方（mkdocs.yml、pyproject.toml、工作流、链接规则）。用户询问“这个技术栈具体是什么？”或想手动应用部分内容时，可参考此文件。
• references/i18n-guide.md — 使用 mkdocs-static-i18n 设置双语／多语言文档。在运行 add-language.sh 之前阅读此文件。其中包含 zh-TW 页面“保留英文原文”的术语规则原文。
• references/i18n-llmstxt-migration.md — 审计／应用／验证迁移指南、退出码约定、自动补丁范围和手动回退方案。修复或升级现有的 i18n + llmstxt 网站之前，请阅读此文件。
• references/mkdocs-2-and-zensical.md — 说明技术栈为何固定使用 mkdocs<2 和 mkdocs-material<10。介绍 MkDocs 2.0 移除插件的情况、Material 团队推出的 Zensical 替代方案，以及解除版本上限的条件。用户询问升级 MkDocs 或文档构建为何使用 1.x 时，请阅读此文件。

捆绑资源

脚本会从这些模板复制内容。请在此处编辑，而不是在用户的仓库中编辑。

• assets/mkdocs.yml.template — Material 主题 + 受环境变量保护的 llmstxt、copy-to-llm、支持 i18n 的 docs_dir，以及 pymdownx.snippets。使用 {{SITE_NAME}}、{{REPO_SLUG}}、{{SITE_URL}} 作为参数。包含 __SOCIAL_*__ 标记行，init-docs-site.sh 会根据情况展开（传入 --social 时）或删除这些行。
• assets/pyproject.toml.template — 最简 [project] 块 + 文档可选依赖组。包含 __SOCIAL_IMAGING__ 标记。
• assets/build-docs-site.py — 由管理的两阶段辅助脚本，会复制到下游项目的 scripts/build-docs-site.py。请保留其管理标记，以便迁移工具将其与用户自行维护的脚本区分开。
• assets/docs-workflow.yml.template — .github/workflows/docs.yml，包含路径过滤器、uv 设置、受管理的严格构建辅助脚本，以及 Pages 部署。包含 __SOCIAL_CI__ 标记，用于 Cairo/Pango 和卡片缓存步骤。
• assets/social/ — 传入 init-docs-site.sh --social 时，会在 __SOCIAL_*__ 标记处插入这些代码片段：mkdocs-plugin.yml（social 插件块）、pyproject-dep.txt（mkdocs-material[imaging]）和 ci-steps.yml（Cairo/Pango 安装 + .cache/plugin/social 缓存）。 已根据插入位置预设缩进，请保留缩进。
• assets/docs-skeleton/ — 从此仓库复制的 index.md、getting-started.md、_snippets/ 示例和 assets/copy-to-llm/ JS+CSS 文件。
• assets/page.md.template — 由 add-docs-page.sh 使用。
• assets/translation-stub.md.template — add-language.sh 和 add-docs-page.sh 为非默认语言页面使用的占位文件。包含完整的术语规则提示框。
• assets/i18n-plugin.yml.snippet — mkdocs-static-i18n 插件的 YAML 配置块参考（由 references/i18n-guide.md 使用；脚本通过 yq 构建等效配置块）。

注意事项

• 社交卡片（OG 预览）为可选功能，默认关闭。 向 init-docs-site.sh 传入 --social 即可启用；普通脚手架不包含社交插件、 [imaging] 依赖或 Cairo/Pango CI 步骤，因此构建时无需任何系统依赖 （仅运行 mkdocs build 渲染耗时远低于一秒）。当用户需要丰富的链接预览并接受下文所述成本时再启用。 若要为已搭建的站点启用，请将 social 插件块添加到 mkdocs.yml，将 mkdocs-material[imaging] 添加到文档依赖项，将 Cairo/Pango 和 缓存步骤添加到 docs.yml，并将 /.cache/ 添加到 .gitignore（从 assets/social/* 复制——这些就是 --social 注入的相同片段）。
• social 插件需要系统级 Cairo/Pango 和 [imaging] 附加依赖。 mkdocs-material[imaging] 会安装 cairosvg/pillow，但它们依赖系统 libcairo/libpango——缺少这些库时，构建会因 libcairo 加载错误而中止。使用 --social 时，docs-workflow.yml.template 会通过 apt 安装它们 （libcairo2-dev libpango1.0-dev libfreetype6-dev …），并缓存 .cache/plugin/social。本地安装方式：brew install cairo pango（macOS），或安装相同的 apt 软件包（Linux）。--social 还会将 /.cache/ 添加到 .gitignore—— 插件会在其中为每个页面写入约 1 张卡片 PNG（数十 MB），并下载字体。 冷缓存构建会为每个页面渲染一张卡片（通过网络从 Google Fonts 获取字体）； 命中缓存时只需几秒。
• 如果卡片字体不支持 CJK 字符或箭头，社交卡片上的页面标题就会显示为豆腐框（□□□）。 插件默认字体（Roboto）和普通的「Noto Sans」仅支持拉丁字符，因此中文、日文、韩文标题—— 甚至英文标题中的 →——都会显示为方框。添加 CJK 语言时，add-language.sh 会自动设置支持 CJK 的 social.cards_layout_options.font_family（Noto Sans TC/SC/JP/KR），但前提是已安装 社交插件且尚未设置字体（因此应先使用 --social 搭建脚手架，再添加 zh-TW，或者之后自行 设置字体）。请打开渲染后的 site/assets/images/social/**/<page>.png 验证，而不要只相信构建结果。
• 这些脚本中的 yq 是 mikefarah yq（v4），不支持 if/then/else/end 语法——那是 jq 的语法。请使用 (.plugins[] | select(has("x")) | .x.y) = z 或 += […]，切勿使用 .plugins |= map(if has("x") then … else . end)（会因 lexer: invalid input text "if …" 错误而失败）。过去的 i18n 第二语言追加流程就曾因此出错； 新表达式应继续使用 select() 形式。
• MkDocs 严格模式会拒绝指向 docs/ 目录外部的相对 .md 链接。 在 docs/ 内 → 可以使用相对路径。在 docs/ 外引用 .md 文件（例如链接到仓库中的 TODO.md） → 使用绝对 GitHub URL。在 docs/ 外引用目录或非 .md 文件（backlog/、 pyproject.toml）→ 相对路径会降级为 INFO 级别并被接受。模板已经正确处理这些情况； 不要「修正」绝对 URL。
• pymdownx.snippets 包含的片段应加入递归 exclude_docs。 not_in_nav 只会抑制警告，仍会发布独立 HTML；模板会排除根目录和嵌套的 _snippets/ 目录。
• 对于 build_type=workflow，gh api -X POST .../pages 是幂等的，但如果仓库尚未推送到 GitHub， 则会报错 404 Not Found。运行 enable-pages.sh 前，请确认 gh repo view 执行成功。
• Pages 部署工作流需要在工作流级别设置 permissions: pages: write, id-token: write。模板已包含该设置；如果将部分内容复制到现有工作流中，切勿遗漏。
• copy-to-llm 插件的 repo_url 是站点 URL，不是 GitHub URL。 名称很容易让人误解。
• 不要自动迁移用户现有的文档。 务必先询问。将他人精心整理的 docs/ 迁移到新结构属于高度敏感的操作，应由用户明确决定，而非由 Agent 默认执行。
• .skills/preferences.yaml 是针对单个仓库的，不是全局配置。 不要将它写入 ~/.skills/ 或 ~/.config/。每个仓库都有各自的配置。
• mkdocs-static-i18n 要求将 theme.language 设置为默认语言代码。 如果缺少此设置，插件会发出警告。add-language.sh 会在首次运行时设置它；如果手动复制配置片段， 也别忘了设置。
• 仅支持 docs_structure: suffix。 add-language.sh 会写入后缀式布局 （index.md 和 index.zh-TW.md 并列）；i18n_structure: folder 偏好设置键已预留，但尚未实现。不要将 folder 配置粘贴到 mkdocs.yml，并指望脚本能保持配置一致。
• 单次多语言构建会悄悄破坏 mkdocs-llmstxt 的输出。 mkdocs-static-i18n 会按每种语言完整构建一次，而 llmstxt 会清除页面状态，并在 每轮构建时覆盖同一根目录下的 llms.txt / llms-full.txt。因此，最后一种语言可能会留下几乎 空白或语言错误的输出。移除 --strict 只能隐藏警告，无法修复这些文件。 请始终使用 scripts/build-docs-site.py 生成可部署的构建产物。根目录下的 /llms.txt、/llms-full.txt 和 .md 旁附文件有意仅包含默认语言。
• add-language.sh 会从 theme.features 中移除 navigation.instant， 因为语言切换器的上下文链接与即时导航不兼容。警告由 Material 插件自行发出；脚本只是据此进行处理。
• zh-TW 页面中不要在没有英文原文的情况下翻译技术术语。 术语规则（首次提及时在括号中保留英文，不得自行创造译文）不可妥协；模板会以提示框形式注入这条规则， 以便作者开始写作前就能看到。

更新现有站点（而非从头搭建）

如果 mkdocs.yml 已存在，不要悄悄对其进行“升级”；自定义配置可能与模板不匹配。对于明确要求修复 i18n/llmstxt 的请求，请先使用 migrate-i18n-llmstxt.sh 进行审查。展示计划更改后再应用，并保留其报告为手动操作的所有结构。