用途:为仓库引导(bootstrap)或持续维护 MkDocs Material 文档站,并可部署到 GitHub Pages;也支持为已有站点增加非英语语言、修复旧的 i18n + llmstxt 配置。触发场景包括“搭建文档站”“发布文档到 GitHub Pages”“双语/多语言文档”“llms.txt 为空或只含一种语言”等;若只想写单个文档文件或用户已明确拒绝,则不应触发。
主要能力:通过脚本完成偏好记录、脚手架初始化、严格两遍构建、GitHub Pages 启用、页面添加与语言添加。i18n 采用 mkdocs-static-i18n 后缀布局(index.md + index.zh-TW.md);多语言加 llmstxt 时,先单独生成默认语言 LLM 输出,再构建完整 HTML,校验合并产物后才替换 site/。
使用方式:先运行 scripts/check-preferences.sh --get mkdocs_site_bootstrap 读取记录;无记录时询问并 --set 保存。脚手架: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 预览。构建:uv sync --extra docs 后 uv run python scripts/build-docs-site.py。部署:scripts/enable-pages.sh --repo OWNER/REPO,需先确认并确保 gh auth status 通过。加页用 add-docs-page.sh --section --title --slug;加语言用 add-language.sh --lang zh-TW。
限制:全程需用户同意,不擅自迁移已有内容或配置;已存在 mkdocs.yml 或非空 docs/ 时需用户选择 skip/wrap/manual。add-language.sh 只生成含术语警告的占位页,不自动翻译,翻译需另行确认,且须遵守“中文 (English original)”术语规则。迁移命令默认审计,写操作需 --apply。栈固定 mkdocs<2、mkdocs-material<10;社交卡片(--social)需 Cairo/Pango 依赖,默认关闭。实现语言若未配置,则不能生成对应语言占位页。