publish-to-pages

publish-to-pages

将任意演示文稿或网页内容一键发布到 GitHub Pages。

1. 前置条件检查

静默运行以下命令。仅在出错时提示：

command -v gh >/dev/null || echo "MISSING: gh CLI — install from https://cli.github.com"
gh auth status &>/dev/null || echo "MISSING: gh not authenticated — run 'gh auth login'"
command -v python3 >/dev/null || echo "MISSING: python3 (needed for PPTX conversion)"

poppler-utils 是可选的（通过 pdftoppm 进行 PDF 转换）。不要因此阻塞流程。

2. 输入检测

根据用户提供的内容确定输入类型：

输入	检测方式
HTML 文件	扩展名为 .html 或 .htm
PPTX 文件	扩展名为 .pptx
PDF 文件	扩展名为 .pdf
Google Slides URL	URL 包含 docs.google.com/presentation

如果用户未提供 repo 名称，请询问。默认值：不带扩展名的文件名。

3. 转换

大文件处理

两个转换脚本都会自动检测大文件并切换到 外部资源模式：

• PPTX： 文件大于 20MB 或包含超过 50 张图片 → 图片保存为 assets/ 中的独立文件
• PDF： 文件大于 20MB 或超过 50 页 → 页面 PNG 保存到 assets/ 中
• 文件大于 150MB 会打印警告（PPTX 会建议改用 PDF 方式）

这样可确保单个文件远低于 GitHub 的 100MB 限制。小文件仍会生成单个自包含的 HTML。

你可以使用 --external-assets 或 --no-external-assets 强制指定该行为。

HTML

无需转换。直接将该文件用作 index.html。

PPTX

运行转换脚本：

python3 SKILL_DIR/scripts/convert-pptx.py INPUT_FILE /tmp/output.html
# For large files, force external assets:
python3 SKILL_DIR/scripts/convert-pptx.py INPUT_FILE /tmp/output.html --external-assets

如果缺少 python-pptx，请告知用户：pip install python-pptx

PDF

使用附带的脚本进行转换（需要 poppler-utils 以使用 pdftoppm）：

python3 SKILL_DIR/scripts/convert-pdf.py INPUT_FILE /tmp/output.html
# For large files, force external assets:
python3 SKILL_DIR/scripts/convert-pdf.py INPUT_FILE /tmp/output.html --external-assets

每一页都会渲染为 PNG，并嵌入到带幻灯片导航的 HTML 中。 如果缺少 pdftoppm，请告知用户：apt install poppler-utils（macOS 上则为 brew install poppler）。

Google Slides

1. 从 URL 中提取演示文稿 ID（/d/ 与 / 之间的长字符串）
2. 下载为 PPTX：

curl -L "https://docs.google.com/presentation/d/PRESENTATION_ID/export/pptx" -o /tmp/slides.pptx

3. 然后使用上面的转换脚本转换该 PPTX。

4. 发布

可见性

默认情况下，仓库创建为 公开。如果用户指定 private（或希望使用私有仓库），请使用 --private — 但请注意，私有仓库上的 GitHub Pages 需要 Pro、Team 或 Enterprise 套餐。

发布

bash SKILL_DIR/scripts/publish.sh /path/to/index.html REPO_NAME public "Description"

如果用户要求，请传入 private 而不是 public。

该脚本会创建仓库、推送 index.html（如果存在 assets/ 也一并推送），并启用 GitHub Pages。

注意： 使用外部资源模式时，输出的 HTML 会引用 assets/ 中的文件。发布脚本会自动检测并复制 HTML 文件同级的 assets/ 目录。请确保 HTML 文件及其 assets/ 目录位于同一父目录中。

5. 输出

告知用户：

• 仓库： https://github.com/USERNAME/REPO_NAME
• 在线 URL： https://USERNAME.github.io/REPO_NAME/
• 注意： Pages 需要 1-2 分钟才能生效。

错误处理

• 仓库已存在： 建议追加数字（my-slides-2）或日期（my-slides-2026）。
• Pages 启用失败： 仍然返回仓库 URL。用户可以在仓库 Settings 中手动启用 Pages。
• PPTX 转换失败： 告知用户运行 pip install python-pptx。
• PDF 转换失败： 建议安装 poppler-utils（apt install poppler-utils 或 brew install poppler）。
• Google Slides 下载失败： 该演示文稿可能无法公开访问。请用户将其设为可查看，或手动下载 PPTX。