Skip to content

updating-existing-decks.md

Latest commit

 

History

History
96 lines (67 loc) · 2.82 KB

updating-existing-decks.md

File metadata and controls

96 lines (67 loc) · 2.82 KB

Updating Existing Decks (Re-entrant Workflow)

This walkthrough shows a practical iterative workflow where you:

  1. author in Markdown,
  2. render with a template,
  3. make manual PowerPoint edits,
  4. revise Markdown,
  5. regenerate safely with --update-existing.

Conceptual model

  • Managed slides are slides generated by MarpToPptx and tagged with slide metadata in p:extLst.
  • Unmanaged slides are slides added manually in PowerPoint (no MarpToPptx slide metadata).
  • --update-existing reconciles against a previous managed deck.
  • --template supplies rendering artifacts (masters, layouts, and Template[n] behavior).

During update mode:

  • managed slides are matched by slide identity (not raw ordinal position),
  • unmanaged slides are preserved,
  • changed managed slides are replaced wholesale (not merged shape-by-shape).

End-to-end scenario

1) Author an initial deck

---
marp: true
layout: Title and Content
---

<!-- _layout: Template[1] -->
# Product Kickoff

---
## Goals
- Launch plan
- Messaging

2) Render with a template

marp2pptx deck.md --template conference-template.pptx -o deck.pptx

3) Add manual PowerPoint-only content

Open deck.pptx in PowerPoint and add a slide that does not come from Markdown (for example, a marketing slide provided by another team). Save it as deck-with-manual-edits.pptx.

4) (Optional) Bootstrap explicit slideId directives

marp2pptx deck.md --write-slide-ids -o deck.pptx

It adds only missing <!-- slideId: ... --> directives, preserves any existing explicit directives, and rewrites deck.md in place as part of the run.

5) Update your Markdown content

Edit deck.md (change text, add/remove Markdown slides, or adjust directives).

6) Regenerate in update mode

marp2pptx deck.md \
  --update-existing deck-with-manual-edits.pptx \
  --template conference-template.pptx \
  -o deck-updated.pptx

7) Verify expected results

  • Manual PowerPoint-only slide(s) remain in the deck (unmanaged slide preservation).
  • Managed slides are reconciled by identity.
  • Any changed managed slide is regenerated and replaced as a whole.

Common mistakes and troubleshooting

  • Mistake: Passing only --template and expecting update reconciliation.
    Fix: Pass the previous generated deck to --update-existing.

  • Mistake: Treating the template as the previous deck.
    Fix: Keep them separate: previous deck for reconciliation, template for rendering.

  • Mistake: Expecting manual edits inside a changed managed slide to survive.
    Fix: Re-apply those edits in Markdown or move them to unmanaged slides.

  • Mistake: Assuming explicit slideId directives are auto-added forever.
    Fix: Run --write-slide-ids when bootstrapping or when adding slides that still lack directives.