Community编程与开发github.com

static-site-publish

编码技能。从数据生成纯HTML/CSS/JS静态小站点(无构建工具或框架),在无头浏览器中验证,然后发布到GitHub Pages,并可配置自定义域名与Cloudflare CNAME重定向。

static-site-publish 是什么?

该技能(static-site-publish)提供一个完整的工作流:将数据(如列表、表格、仪表盘、作品集)转换为独立的HTML/CSS/JS页面,在无头浏览器中进行视觉和功能验证,最后发布到GitHub Pages。它特别适合1到数百个条目的静态页面,无需后端、身份验证或数据库。支持在Claude Code、Cursor、Codex等AI代理环境中触发,可通过“生成站点”、“发布到GitHub”、“gh-pages”等短语激活。工作流包括:框架确认、数据获取、模板生成、浏览器截图验证、GitHub Pages发布,以及可选的Cloudflare DNS配置(CNAME记录,proxy关闭)以支持自定义域名。强制规则包括:原始设计(不复制第三方CSS/HTML)、尊重数据伦理(不绕过robots.txt或Cloudflare挑战)、始终在真实浏览器中验证、以及自定义域名需用户显式确认。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/JamesDAdams/my-skills/tree/HEAD/.apm/skills/static-site-publish

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

静态站点 → GitHub Pages

完整工作流:数据 → 独立HTML/CSS/JS页面 → 浏览器验证 → GitHub Pages发布。

目标:1到数百个条目的页面,单个作者,零运行时依赖。

何时使用

是否
“用这个列表/表格给我做个页面”、图库、数据仪表盘带后端、认证、数据库的应用 → 请先询问
“把它发布到GitHub/GitHub Pages”由框架(Next、Astro、Hugo)生成的站点 → 遵循框架流程
基于数据(标题、日期、价格……)复现现有页面复制第三方站点的设计/CSS/HTML → 拒绝,重新设计干净版本

不可妥协的规则

  1. 自主设计。 绝不复制第三方站点的CSS、HTML或资源。可以借鉴信息结构,但不得抄袭其视觉规范。
  2. 事实可复用,作品不可抄袭。 标题、日期、价格、评分、链接 = 事实数据,可复用。文字内容、描述、视觉元素 = 受保护:不得复制。对于图片,使用原始CDN热链接而非提交到仓库(参见 reference/data-and-ethics.md)。
  3. 遵守访问保护。 若robots.txt禁止爬取,或有Cloudflare/bot挑战 → 不得绕过。应寻找官方API、密钥,或降级为简单外部链接。
  4. 始终在真实浏览器中验证 在说“完成了”之前(截图 + 点击测试)。
  5. 在仓库名/账户不明确时,未经确认不得发布。
  6. 未经确认不得创建自定义域名。 若用户未提及,询问是否需要Cloudflare重定向以及哪个域名(步骤6)。绝不自作主张创建子域名:DNS是外部可见的副作用。

工作流

1. 框定(30秒)

  • 什么数据?多少条目?一次性更新还是定期更新?

  • 期望输出:单个页面?排序/搜索?有哪些业务显示规则?

  • 发布位置:GitHub账户、仓库名、公开/私有(免费账户的Pages要求公开仓库)。

  • 自定义域名——若未明确说明,需显式询问。 一次性提问,并提供默认建议:

    是否需要将Cloudflare重定向到 <owner>.github.io(CNAME,proxy关闭)?如果是,使用哪个子域名/路径?

    名称在技能侧是自由的,但域名创建后立即公开:在没有明确回复前不要创建任何内容。如果用户回答“否”,则停止于 https://<owner>.github.io/<repo>/ 的URL,不创建DNS条目。

2. 获取数据

一次性脚本 → 一个 data.json = 真实数据源,与渲染分离。

python3 fetch_data.py     # → data.json

礼貌要求:请求间隔0.3–0.7秒,显式User-Agent,遇到429/5xx时重试。 详情及易错情况(PoW Anubis、Cloudflare、模糊匹配、无密钥API):参见 reference/data-and-ethics.md。

3. 生成页面

基于模板,而非从空白开始:

cp .dsh/skills/static-site-publish/templates/{index.html,styles.css,script.js} ./site/
cp .dsh/skills/static-site-publish/templates/build.py ./site/   # data.json → index.html
python3 ./site/build.py
  • build.py:小型Python生成器(f-string + html.escape),将数据注入卡片网格。数据无需运行时JS。
  • styles.css:默认暗色主题,auto-fill minmax() 网格,CSS变量。
  • script.js:即时搜索 + 排序 + 打开时计算的显示规则(使页面无需重建即可保持正确)。
  • 一切可在显示时计算的内容(状态、相对日期)都应使用JS实现:避免每天重建站点。
  • HTML应在无JS时保持可读,JS应为渐进增强。

4. 验证

.dsh/skills/static-site-publish/scripts/verify-site.sh ./site/index.html

在Chrome无头模式下打开页面,写入 /tmp/site-shot.png,并运行点击重叠测试。查看截图(read_image 工具)后再做结论。 检查清单:桌面端和移动端渲染、数据完整(计数条目)、链接正确、无重叠。

5. 发布

.dsh/skills/static-site-publish/scripts/publish-gh-pages.sh ./site my-repo-name

脚本:gh auth status → git init/commit → gh repo create --source --push → gh api POST /pages → 轮询URL直到返回200 → 显示最终URL。

Pages的延迟为 20到90秒:在循环确认返回200之前,不要断定“它不工作”。还应验证 gh api repos/{owner}/{repo}/pages/builds/latest --jq .status = built。

6. 自定义域名 + Cloudflare

仅在用户要求时(参见步骤1)。DNS是公开的:不要将模糊的“是”重新解释为由AI选择的域名。

强制顺序:DNS优先,证书其次,Enforce HTTPS最后。 站点应已在 *.github.io 上返回200后再开始。

a. 在Cloudflare配置DNS重定向(MCP Cloudflare)

前提令牌:作用域 zone.read + dns.write(Zone Read / DNS Edit)。若缺少,停止并请求扩展——不要绕过。

  1. GET /zones?name=<根域名> → zone.id。若零个zone:域名不在该账户中,请询问。
  2. GET /zones/{zone_id}/dns_records?name=<完全限定域名> → 若已有相同的CNAME,则不重新创建(幂等性)。
  3. POST /zones/{zone_id}/dns_records:
{ "type": "CNAME", "name": "<子域名>", "content": "<owner>.github.io",
  "proxied": false, "ttl": 1 }
  • proxied: false = 仅DNS,不可协商:Cloudflare代理会阻止GitHub颁发证书。
  • 目标为 <owner>.github.io,末尾无斜杠,不含仓库名(如 jamesdadams.github.io,而非 .../my-repo)。
  • ttl: 1 = 自动。
  1. 通过公共解析而不是仅通过API验证:
dig +short <完全限定域名> CNAME @1.1.1.1   # → <owner>.github.io.
dig +short <完全限定域名> A @1.1.1.1       # → 185.199.108-111 .153

b. GitHub Pages端的域名 + Enforce HTTPS

.dsh/skills/static-site-publish/scripts/set-pages-domain.sh <owner>/<repo> <域名> ./site

脚本:在站点中写入 CNAME 文件(它在重新部署后仍然存在,避免丢失域名)→ PUT /repos/{owner}/{repo}/pages,带 cname 参数 → 等待 https_certificate.state = approved → 激活 https_enforced: true。

⚠️ https_enforced: true 在证书不存在之前返回 400。实际延迟:CNAME创建后5到20分钟。这就是脚本循环而不是失败的原因。在证书颁发之前不要手动勾选“Enforce HTTPS”,在此期间不要断定失败。

c. 最终验证

curl -sI https://<域名>/ | head -5      # 200 + server: GitHub.com 头部

然后在浏览器中重新打开页面(步骤4)使用自定义URL:返回200并不能证明相对路径(styles.css、script.js)能够解析——这是在域名根目录提供project pages时的经典陷阱。

7. 使更新成为可能

  • 将git目录放在用户的项目目录中(而非 /tmp,重启后会被清除)。
  • 在 README.md 中记录:数据来源、如何重新运行提取、哪些是固定的(数据)vs 动态的(JS中计算的规则)。
  • 明确告知用户哪些内容不会自动更新。

已遇到的陷阱

症状原因修正
403 “Just a moment…”Cloudflare挑战记录限制、官方API或外部链接;不要试图绕过
页面截断 “Making sure you're not a bot”PoW Anubis解决挑战(参见reference)或要求用户导出
选择器返回0结果错误模式(如 /games/lib/genre: 而非 /games/lib/popular/genre:)打印HTML样本并在循环前对1页测试正则表达式
点击卡片未打开正确链接<a> 层被定位的子元素覆盖在装饰元素上使用 pointer-events: none;使用 elementFromPoint 测试
GitHub Pages前几分钟404构建进行中轮询至多90秒
某列数据为空源端标签可变(“Released” vs “Early Access”)宽容的模式 + 每项日志,绝不使用无声的 except: pass
https_enforced 返回400 “certificate does not exist”证书尚未颁发等待 https_certificate.state = approved(5-20分钟),脚本循环
自定义域名30分钟后404CNAME缺失/所有权错误/仓库中缺少 CNAME 文件使用 dig 确认CNAME,重新运行 set-pages-domain.sh
启用代理后HTTPS损坏记录变为代理状态改回 DNS only(proxied: false),GitHub证书无法通过代理验证
“Domain is already in use”域名已在同一账户的另一个仓库上声明每个仓库一个自定义域名;先释放旧域名再重新分配
自定义域名下CSS/JS返回404,但在 *.github.io/repo/ 下正常在根目录提供project page时使用了绝对路径(/styles.css)使用相对路径(styles.css)

参考

  • reference/data-and-ethics.md — 数据提取、PoW Anubis、Cloudflare、许可证、图片热链接
  • reference/design-and-verify.md — 最小设计系统、浏览器测试、可访问性
  • reference/publish-gh-pages.md — gh 命令、命名、域名、故障排除
  • scripts/publish-gh-pages.sh — 发布 + 激活Pages
  • scripts/set-pages-domain.sh — 自定义域名 + Enforce HTTPS(在Cloudflare CNAME之后)
  • scripts/verify-site.sh
  • templates/{index.html,styles.css,script.js,build.py}

相关技能