Document re-entrant deck updates, slideId bootstrapping, and template/update semantics

[Copilot]

New Feature

What does this feature do?

This updates the docs surface for the re-entrant update capability so users can safely run iterative Markdown → PPTX workflows with templates, preserved unmanaged slides, and identity-based managed slide reconciliation.

Why is this feature needed?

The update flow was discoverable only through code/tests and easy to misuse—especially around the distinction between previous managed deck (--update-existing) and rendering template (--template), plus how slideId and --write-slide-ids stabilize mapping.

Implementation details

• README: re-entrant update quickstart

  • Added a concise section introducing update mode.
  • Documented --update-existing vs --template as separate semantic inputs.
  • Added --write-slide-ids behavior: rewrites the input Markdown file in place, adding only missing directives and preserving existing ones.
  • Included command sequence for initial render, slideId bootstrap, and update render with consistent filenames throughout.
  • Linked new walkthrough doc from the Documentation index.

• Template docs: update-mode semantics

  • Expanded doc/using-templates.md with explicit update-mode guidance.
  • Added a fresh render vs update render comparison with aligned filenames so the output of the fresh render maps directly to the --update-existing reconciliation input.
  • Clarified Template[n] behavior when both --update-existing and --template are supplied.
  • Documented extLst-backed identity reconciliation conceptually and the V1 limitation: changed managed slides are replaced wholesale.
  • Noted that --write-slide-ids rewrites the input Markdown file in place before rendering.

• New walkthrough: end-to-end iterative authoring

  • Added doc/updating-existing-decks.md with a practical start-to-finish scenario:
    • author deck
    • render with template
    • add manual PowerPoint-only slide(s)
    • optionally bootstrap slide IDs
    • edit Markdown
    • regenerate with --update-existing + --template
    • verify preserved vs replaced outcomes
  • Explicitly warns that --write-slide-ids rewrites the input Markdown file in place.
  • Added troubleshooting for common operator mistakes.

marp2pptx deck.md --template conference-template.pptx -o deck.pptx
marp2pptx deck.md --write-slide-ids -o deck.pptx
marp2pptx deck.md --update-existing deck.pptx --template conference-template.pptx -o deck-updated.pptx

[Copilot]

Pull request overview

This PR expands the user-facing documentation for MarpToPptx’s re-entrant update workflow, clarifying how iterative Markdown → PPTX authoring works when preserving unmanaged slides and reconciling managed slides by identity.

Changes:

• Added a README quickstart section for update mode, including --update-existing, --template, and --write-slide-ids.
• Expanded template documentation to distinguish template rendering inputs from update reconciliation inputs.
• Added a new end-to-end walkthrough doc for safely updating an existing deck while preserving unmanaged slides.

Show a summary per file

File	Description
README.md	Documents re-entrant update workflow and links to the new walkthrough doc.
doc/using-templates.md	Clarifies update-mode semantics vs template rendering and adds guidance around Template[n] in update workflows.
doc/updating-existing-decks.md	Adds an end-to-end iterative workflow walkthrough with troubleshooting.

Copilot's findings

• Files reviewed: 3/3 changed files
• Comments generated: 5

[jongalloway]

@copilot address comments

[Copilot]

@copilot address comments

All five review comments addressed in the latest commit:

• Filename alignment (README.md & using-templates.md): Changed previous-deck.pptx → deck.pptx for --update-existing and updated-deck.pptx → deck-updated.pptx for output, so the file produced in step 1 maps directly to the reconciliation input in the update render.
• --write-slide-ids in-place rewrite (all three files): All descriptions now explicitly state that the command rewrites the input Markdown file in place, adding only missing directives and preserving existing ones.