deuxksy PPTX to Markdown
One-shot converter: <file>.pptx → <file>.md (same directory, same basename). Produces a faithful structural dump — titles, tables, bullets, notes, images — not a summary. Use it as the grounding source for downstream curation (spec docs, summaries, diffing deck versions).
1. Preflight
- Resolve the input path argument (expand
~, accept absolute or CWD-relative). - Verify the file exists and has a
.pptxextension. - For a legacy
.ppt(OLE2 binary): python-pptx cannot read it. Convert first with LibreOffice if available (soffice --headless --convert-to pptx --outdir <dir> <file.ppt>), then convert the.pptxand report that fidelity depends on that conversion step. If LibreOffice is not installed, ask the user to re-save as.pptxin PowerPoint/Keynote. - If
<stem>.mdalready exists in the same directory, show both timestamps and ask whether to overwrite (--force) or pick another output path.
2. Convert
uv run --with python-pptx --no-project python "<this-skill-dir>/scripts/pptx_to_md.py" <input.pptx> [--force]
Options:
-o <path>— explicit output path (default:<inputdir>/<stem>.md)--no-images— skip image extraction (text/tables only)--force— overwrite existing output
The script prints OK: <path> plus slides= tables= images= notes= counts on success.
3. Verify
- Exit code 0 and
OK:line present. - The output file exists and the
**Slides**header count matches the script'sslides=count. - Spot-check one known table slide: pipe-table rows aligned,
:---separator row present. - On failure, report the exact stderr line — do not retry the same command more than twice (3-Strike).
4. Report
Reply concisely with:
- Output path and stats line (slides / tables / images / notes)
- Assets directory (
<stem>_assets/) if images were extracted - Known limitations that apply to this deck (see below)
Conversion Contract
| PPTX element | Markdown output |
|---|---|
| Title placeholder | ## Slide N — <title> |
| Text shape (buChar/buAutoNum paragraphs) | - item with indent by lvl |
| Table shape | GFM table, :--- separator, cell | escaped, cell newlines → <br> |
| Picture (incl. inside groups) |  |
| SmartArt / diagram | **[Diagram]** bulleted node text (best-effort) |
| Speaker notes | > blockquote under the slide |
| Wingdings/PUA chars (→ ← • ✓ …) | normalized to Unicode |
Slides are separated by ---; shapes are ordered by (top, left) to approximate reading order.
Limitations
- Faithful dump, not a summary — deck annotation callouts and mockup labels interleave. Offer a curated summary (like a spec doc) as a follow-up when the user needs one.
.pptlegacy format is not read directly — see Preflight step 3.- Merged table cells flatten to empty cells — Markdown tables cannot merge.
- SmartArt structure (arrows, layout) is lost; only node texts survive. Decks whose flowcharts are plain shapes are unaffected.
- Visual mockups are extracted as images — a text-only read cannot verify them. When the spec depends on layout, open the extracted images.
- Chart (embedded xlsx) data labels come through as text only if authored as shapes.