Skip to content

refactor: move PPT/share guidance into references/ #98

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lukesw55 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

refactor: move PPT/share guidance into references/ #98

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 20 additions & 92 deletions SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -249,12 +249,17 @@ If the user selected a self-generated custom wildcard, treat that preview's CSS

## Phase 4: PPT Conversion

When converting PowerPoint files:
When converting PowerPoint files, read [references/ppt-conversion.md](references/ppt-conversion.md) and follow that workflow.

1. **Extract content** — Run `python scripts/extract-pptx.py <input.pptx> <output_dir>` (install python-pptx if needed: `pip install python-pptx`)
2. **Confirm with user** — Present extracted slide titles, content summaries, and image counts
3. **Style selection** — Proceed to Phase 2 for style discovery
4. **Generate HTML** — Convert to chosen style, preserving all text, images (from assets/), slide order, and speaker notes (as HTML comments)
Core loop:

1. Run `python scripts/extract-pptx.py <input.pptx> <output_dir>`.
2. Inspect `extracted-slides.json` plus extracted assets.
3. Summarize slide titles, content, image counts, tables/charts, and any extraction uncertainty for the user.
4. Proceed to Phase 2 for visual style discovery.
5. Generate a fixed-stage HTML deck that preserves text, images, slide order, and speaker notes as HTML comments.

If a source slide is too dense for a 1920×1080 stage, split it into multiple HTML slides instead of shrinking content until it becomes cramped.

---

Expand All @@ -273,94 +278,15 @@ When converting PowerPoint files:

## Phase 6: Share & Export (Optional)

After delivery, **ask the user:** _"Would you like to share this presentation? I can deploy it to a live URL (works on any device including phones) or export it as a PDF."_

Options:

- **Deploy to URL** — Shareable link that works on any device
- **Export to PDF** — Universal file for email, Slack, print
- **Both**
- **No thanks**

If the user declines, stop here. If they choose one or both, proceed below.

### 6A: Deploy to a Live URL (Vercel)

This deploys the presentation to Vercel — a free hosting platform. The link works on any device (phones, tablets, laptops) and stays live until the user takes it down.

**If the user has never deployed before, guide them step by step:**

1. **Check if Vercel CLI is installed** — Run `npx vercel --version`. If not found, install Node.js first (`brew install node` on macOS, or download from https://nodejs.org).

2. **Check if user is logged in** — Run `npx vercel whoami`.
- If NOT logged in, explain: _"Vercel is a free hosting service. You need an account to deploy. Let me walk you through it:"_
- Step 1: Ask user to go to https://vercel.com/signup in their browser
- Step 2: They can sign up with GitHub, Google, email — whatever is easiest
- Step 3: Once signed up, run `vercel login` and follow the prompts (it opens a browser window to authorize)
- Step 4: Confirm login with `vercel whoami`
- Wait for the user to confirm they're logged in before proceeding.

3. **Deploy** — Run the deploy script:

```bash
bash scripts/deploy.sh <path-to-presentation>
```

The script accepts either a folder (with index.html) or a single HTML file.

4. **Share the URL** — Tell the user:
- The live URL (from the script output)
- That it works on any device — they can text it, Slack it, email it
- To take it down later: visit https://vercel.com/dashboard and delete the project
- The Vercel free tier is generous — they won't be charged

**⚠ Deployment gotchas:**

- **Local images/videos must travel with the HTML.** The deploy script auto-detects files referenced via `src="..."` in the HTML and bundles them. But if the presentation references files via CSS `background-image` or unusual paths, those may be missed. **Before deploying, verify:** open the deployed URL and check that all images load. If any are broken, the safest fix is to put the HTML and all its assets into a single folder and deploy the folder instead of a standalone HTML file.
- **Prefer folder deployments when the presentation has many assets.** If the presentation lives in a folder with images alongside it (e.g., `my-deck/index.html` + `my-deck/logo.png`), deploy the folder directly: `bash scripts/deploy.sh ./my-deck/`. This is more reliable than deploying a single HTML file because the entire folder contents are uploaded as-is.
- **Filenames with spaces work but can cause issues.** The script handles spaces in filenames, but Vercel URLs encode spaces as `%20`. If possible, avoid spaces in image filenames. If the user's images have spaces, the script handles it — but if images still break, renaming files to use hyphens instead of spaces is the fix.
- **Redeploying updates the same URL.** Running the deploy script again on the same presentation overwrites the previous deployment. The URL stays the same — no need to share a new link.

### 6B: Export to PDF

This captures each slide as a screenshot and combines them into a PDF. Perfect for email attachments, embedding in documents, or printing.

**Note:** Animations and interactivity are not preserved — the PDF is a static snapshot. This is normal and expected; mention it to the user so they're not surprised.

1. **Run the export script:**

```bash
bash scripts/export-pdf.sh <path-to-html> [output.pdf]
```

If no output path is given, the PDF is saved next to the HTML file.

2. **What happens behind the scenes** (explain briefly to the user):
- A headless browser opens the presentation at 1920×1080 (standard widescreen)
- It screenshots each slide one by one
- All screenshots are combined into a single PDF
- The script needs Playwright (a browser automation tool) — it will install automatically if missing

3. **If Playwright installation fails:**
- The most common issue is Chromium not downloading. Run: `npx playwright install chromium`
- If that fails too, it may be a network/firewall issue. Ask the user to try on a different network.
After delivery, ask the user: _"Would you like to share this presentation? I can deploy it to a live URL, export it as a PDF, do both, or leave it as HTML."_

4. **Deliver the PDF** — The script auto-opens it. Tell the user:
- The file location and size
- That it works everywhere — email, Slack, Notion, Google Docs, print
- Animations are replaced by their final visual state (still looks great, just static)
If the user declines, stop. If they choose deployment or PDF export, read [references/share-export.md](references/share-export.md) and use the bundled scripts:

**⚠ PDF export gotchas:**
- **Deploy to URL:** `bash scripts/deploy.sh <path-to-slide-folder-or-html>`
- **Export to PDF:** `bash scripts/export-pdf.sh <path-to-html> [output.pdf]`
- **Compact PDF:** `bash scripts/export-pdf.sh <path-to-html> [output.pdf] --compact`

- **First run is slow.** The script installs Playwright and downloads a Chromium browser (~150MB) into a temp directory. This happens once per run. Warn the user it may take 30-60 seconds the first time — subsequent exports within the same session are faster.
- **Slides must use `class="slide"`.** The export script finds slides by querying `.slide` elements. If the presentation uses a different class name, the script will report "0 slides found" and fail. All presentations generated by this skill use `.slide`, so this only matters for externally-created HTML.
- **Local images must be loadable via HTTP.** The script starts a local server and loads the HTML through it (so Google Fonts and relative image paths work). If images use absolute filesystem paths (e.g., `src="/Users/name/photo.png"`) instead of relative paths (e.g., `src="photo.png"`), they won't load. Generated presentations always use relative paths, but converted or user-provided decks might not — check and fix if needed.
- **Local images appear in the PDF** as long as they are in the same directory as (or relative to) the HTML file. The export script serves the HTML's parent directory over HTTP, so relative paths like `src="photo.png"` resolve correctly — including filenames with spaces. If images still don't appear, check: (1) the image files actually exist at the referenced path, (2) the paths are relative, not absolute filesystem paths like `/Users/name/photo.png`.
- **Large presentations produce large PDFs.** Each slide is captured as a full 1920×1080 PNG screenshot. An 18-slide deck can produce a ~20MB PDF. If the PDF exceeds 10MB, ask the user: _"The PDF is [size]. Would you like me to compress it? It'll look slightly less sharp but the file will be much smaller."_ If yes, re-run the export with the `--compact` flag:
```bash
bash scripts/export-pdf.sh <path-to-html> [output.pdf] --compact
```
This renders at 1280×720 instead of 1920×1080, typically cutting file size by 50-70% with minimal visual difference.
Do not deploy a deck publicly without explicit user approval. Set expectations that PDFs are static snapshots: animations, inline editing, keyboard navigation, and browser interactivity are not preserved.

---

Expand All @@ -375,6 +301,8 @@ This captures each slide as a screenshot and combines them into a PDF. Perfect f
| [viewport-base.css](viewport-base.css) | Mandatory fixed-stage CSS — copy into every presentation | Phase 3 (generation) |
| [html-template.md](html-template.md) | HTML structure, JS features, code quality standards | Phase 3 (generation) |
| [animation-patterns.md](animation-patterns.md) | CSS/JS animation snippets and effect-to-feeling guide | Phase 3 (generation) |
| [scripts/extract-pptx.py](scripts/extract-pptx.py) | Python script for PPT content extraction | Phase 4 (conversion) |
| [references/ppt-conversion.md](references/ppt-conversion.md) | Detailed PPT conversion workflow and JSON interpretation guidance | Phase 4 (conversion) |
| [references/share-export.md](references/share-export.md) | Deployment and PDF export guidance, gotchas, and delivery messaging | Phase 6 (sharing/export) |
| [scripts/extract-pptx.py](scripts/extract-pptx.py) | Python script for PPT content/layout extraction | Phase 4 (conversion) |
| [scripts/deploy.sh](scripts/deploy.sh) | Deploy slides to Vercel for instant sharing | Phase 6 (sharing) |
| [scripts/export-pdf.sh](scripts/export-pdf.sh) | Export slides to PDF | Phase 6 (sharing) |
| [scripts/export-pdf.sh](scripts/export-pdf.sh) | Export slides to static PDF | Phase 6 (export) |
Loading