@heylemon/lemonade 0.1.6 → 0.1.7

package/skills/pptx/editing.md

@@ -0,0 +1,270 @@
+# Template-Based Editing Workflow
+
+When you have an existing presentation and need to adapt it for new content, use this structured workflow instead of rebuilding from scratch.
+
+## Overview
+
+1. **Analyze template** — Understand existing structure, design, and theme
+2. **Plan slide mapping** — How does new content fit existing layouts?
+3. **Unpack** — Extract PPTX into XML files for editing
+4. **Build presentation** — Duplicate, delete, and reorder slides as needed
+5. **Edit content** — Update text, numbers, and labels
+6. **Clean** — Remove extra files from unpacked directory
+7. **Pack** — Rebuild PPTX from XML files
+
+## Step 1: Analyze Template
+
+### Extract Content
+
+```bash
+python -m markitdown template.pptx > template_content.txt
+```
+
+Review the output to understand:
+- Total slide count
+- Slide types and layouts (title, content, stats, etc.)
+- Color and typography used
+- Structure and narrative flow
+
+### Generate Thumbnails
+
+```bash
+soffice --headless --convert-to pdf template.pptx
+pdftoppm -jpeg -r 100 template.pdf slide
+```
+
+Open the slide images to visually assess:
+- Design style and color palette
+- Typography and spacing
+- Visual elements (icons, cards, shadows)
+- Layout patterns used
+
+## Step 2: Plan Slide Mapping
+
+Create a mapping between new content and existing slide layouts.
+
+**Example:**
+```
+New Content          →  Template Slide  →  Layout
+─────────────────────────────────────────────────
+Title slide          →  Slide 1         →  Title
+"Where we are"       →  Slide 2         →  Section
+Q4 metrics           →  Slide 3         →  Stats (3 cards)
+Market opportunity   →  Slide 4-5       →  Content + image
+Our solution         →  Slide 6         →  Two-column
+Comparison           →  Slide 7         →  Comparison
+Call to action       →  Slide 8         →  Closing
+```
+
+### Important: Use Varied Layouts
+
+Don't force all content into one slide type. If the template has multiple layout styles, use them. Variety prevents fatigue.
+
+- Title slides → Section dividers → Content → Stats → Closing
+- Content → Two-column → Content → Comparison → Content → Closing
+- Never 5 content slides in a row
+
+## Step 3: Unpack the Presentation
+
+Extract the PPTX (which is a ZIP file) into XML:
+
+```bash
+unzip template.pptx -d template_unpacked
+```
+
+This creates a folder structure:
+```
+template_unpacked/
+├── ppt/
+│   ├── slides/
+│   │   ├── slide1.xml
+│   │   ├── slide2.xml
+│   │   └── ...
+│   ├── presentation.xml
+│   └── ...
+├── _rels/
+├── docProps/
+└── [Content_Types].xml
+```
+
+## Step 4: Build the Presentation Structure
+
+Modify the slides folder to match your new slide plan:
+
+### Delete Unused Slides
+
+```bash
+rm template_unpacked/ppt/slides/slide7.xml
+rm template_unpacked/ppt/slides/slide8.xml
+```
+
+Update the slide relationships in `_rels/presentation.xml.rels` to remove references.
+
+### Duplicate Slides for Content
+
+If you need multiple copies of the same layout:
+
+```bash
+cp template_unpacked/ppt/slides/slide3.xml template_unpacked/ppt/slides/slide3_copy1.xml
+```
+
+Then reference the copy in the relationships file.
+
+### Reorder Slides
+
+Rename slides by their intended order. PptxGenJS will read them sequentially.
+
+## Step 5: Edit Content
+
+Use the Read and Edit tools to modify slide XML directly. **Do not use scripts** — editing XML by hand is safer and more controllable.
+
+### Finding Text in XML
+
+Slide content is in XML. Text appears in `<a:t>` tags:
+
+```xml
+<a:t>Old Slide Title</a:t>
+```
+
+Use Read to find the exact text, then Edit to replace it.
+
+### Pattern: Updating Title Text
+
+```xml
+<!-- Before -->
+<a:t>Q3 Results Overview</a:t>
+
+<!-- After -->
+<a:t>Q4 Revenue Beat Target by 15%</a:t>
+```
+
+### Pattern: Updating Bullet Points
+
+Bullets are separate `<a:p>` (paragraph) elements:
+
+```xml
+<a:p>
+  <a:pPr lvl="0"/>
+  <a:r>
+    <a:t>Old bullet point</a:t>
+  </a:r>
+</a:p>
+```
+
+Update the `<a:t>` content.
+
+### Pattern: Updating Stats Numbers
+
+In stat cards, the large number and label are separate text elements:
+
+```xml
+<!-- Number -->
+<a:t>3x</a:t>
+
+<!-- Label -->
+<a:t>User Growth</a:t>
+```
+
+Find and replace each separately.
+
+### Common Edits
+
+| Task | Approach |
+|---|---|
+| Change slide title | Find `<a:t>Old Title</a:t>`, replace with new title |
+| Update a bullet | Find paragraph with old text, replace `<a:t>` content |
+| Change a number | Find the stat value text, replace |
+| Update labels | Find caption text, replace |
+
+## Step 6: Clean
+
+Remove relationship references to deleted slides. This prevents broken links when repacking.
+
+For each deleted slide, find its reference in:
+- `ppt/_rels/presentation.xml.rels`
+- `[Content_Types].xml`
+
+And remove the corresponding `<Relationship>` entries.
+
+## Step 7: Pack Back into PPTX
+
+After editing XML, repack the folder:
+
+```bash
+cd template_unpacked
+zip -r ../new_presentation.pptx *
+cd ..
+```
+
+The result is a valid PPTX file with your edits.
+
+## Formatting Rules
+
+### Text Content
+
+- **Always use straight quotes** — PPTX XML sometimes converts smart quotes (`"` to `"`) which breaks content. Use straight quotes only: `"text"`.
+- **No Unicode bullets** — Don't manually add `•` or `◦` symbols. PPTX bullets are generated from the XML structure, not characters.
+- **Bullet consistency** — If bullets exist in the template, keep them. If not, don't add them unless the layout expects them.
+
+### Slide Numbers
+
+If slides are numbered, update them:
+
+```xml
+<a:t>1 / 8</a:t>  <!-- Change if slide count changes -->
+<a:t>2 / 8</a:t>
+<a:t>3 / 8</a:t>
+```
+
+## Common Pitfalls
+
+### Template Adaptation
+
+- **Don't assume all slides are the same** — Templates often have subtle variations (different fonts for different sections, different margins). Check the actual XML before assuming.
+- **Don't delete slides with complex layouts** — Duplicate and reuse. Deleting and recreating complex slides (tables, charts) is error-prone.
+- **Preserve the theme** — Don't change color hex values or fonts unless necessary. Templates are designed as a unit.
+
+### Multi-Item Content
+
+- **Multi-line bullets** — If a bullet has multiple lines, wrap in a single `<a:p>` with line breaks.
+- **Table cells with bullets** — If a table cell contains bullets, structure must be nested correctly.
+
+### Smart Quotes
+
+- **Replace smart quotes** — If the template has "curly" quotes (`"text"`), replace with straight quotes (`"text"`).
+- **Check apostrophes** — Same issue with apostrophes (`'text'` vs `'text'`).
+
+## When to Unpack vs. Rebuild
+
+| Situation | Approach |
+|---|---|
+| Minor text updates (titles, bullets, stats) | Unpack and edit |
+| Completely different layout | Rebuild from scratch with PptxGenJS |
+| Reusing color scheme and design | Unpack and adapt |
+| Adding new features (charts, complex shapes) | PptxGenJS code |
+| Changing theme colors across all slides | PptxGenJS with custom theme |
+
+## QA After Editing
+
+After packing, always verify:
+
+1. **Extract and check text**
+   ```bash
+   python -m markitdown new_presentation.pptx > qa_check.txt
+   ```
+   Look for garbled text, missing content, or encoding issues.
+
+2. **Convert to images**
+   ```bash
+   soffice --headless --convert-to pdf new_presentation.pptx
+   pdftoppm -jpeg -r 150 new_presentation.pdf slide
+   ```
+
+3. **Visually inspect** — Open slide images and check for:
+   - Text overflow or cut-off
+   - Misaligned elements
+   - Incorrect formatting
+
+4. **Fix and re-verify** — If issues found, fix the XML and repack. Then re-run extraction and image conversion.
+
+Do not declare success until you've completed at least one fix-and-verify cycle.