How the PPT Master Post-Processing Pipeline Works: From SVG Slides to PowerPoint

The PPT Master post-processing pipeline is a three-stage automation that splits consolidated speaker notes into per-slide Markdown files, cleans and optimizes SVG graphics for PowerPoint compatibility, and converts the final assets into a native .pptx presentation with matching notes.

The PPT Master post-processing pipeline bridges the gap between raw SVG generation and production-ready PowerPoint decks. Located in the hugohe3/ppt-master repository, this chain of three Python scripts—total_md_split.py, finalize_svg.py, and svg_to_pptx.py—ensures every slide maintains a strict 1:1 relationship with its speaker notes while resolving SVG features incompatible with Microsoft PowerPoint's native DrawingML engine.

Stage 1: Splitting Consolidated Speaker Notes with total_md_split.py

The total_md_split.py script parses the project's consolidated speaker notes and creates individual files that map directly to each SVG slide.

First, find_svg_files() scans the <project>/svg_output directory and returns a sorted list of Path objects representing all slide SVGs. The script then builds three lookup tables via build_match_maps()—exact name, normalized title, and leading-number mappings—to tolerate minor naming differences between slide titles and SVG filenames.

Next, parse_total_md() walks the Markdown file line-by-line, extracting level-1 headings and using match_title() to associate each heading with an SVG stem. The check_svg_note_mapping() function validates that every SVG has a corresponding note entry, aborting with a clear error if the 1:1 relationship breaks. Finally, split_notes() writes each note block to <project>/notes/<stem>.md, ensuring the output filenames exactly match the SVG filenames (e.g., 03_Intro.md pairs with 03_Intro.svg).

Source: [skills/ppt-master/scripts/total_md_split.py](https://github.com/hugohe3/ppt-master/blob/main/skills/ppt-master/scripts/total_md_split.py)

Stage 2: SVG Cleaning and Finalization with finalize_svg.py

The finalize_svg.py script serves as the single entry point for all SVG post-processing, working on copies in svg_final/ to preserve the raw strategist output.

The finalize_project() function first verifies that svg_output/ exists and copies its contents to svg_final/. It then executes six ordered transformation steps to ensure PowerPoint compatibility:

1. Embed icons (svg_finalize/embed_icons.py): Replaces <use data-icon="…"/> placeholders with full SVG markup from templates/icons/.
2. Smart crop images (svg_finalize/crop_images.py): Detects <image preserveAspectRatio="slice"> and crops images to visible regions, removing unnecessary whitespace.
3. Fix image aspect (svg_finalize/fix_image_aspect.py): Adjusts width/height attributes to prevent stretching during PowerPoint shape conversion.
4. Embed images (svg_finalize/embed_images.py): Reads external raster files, optionally compresses them (--compress), and stores data as Base64 data-URIs inside the SVG.
5. Flatten text (svg_finalize/flatten_tspan.py): Converts nested <tspan> elements into independent <text> elements required by some PPT converters.
6. Fix rounded rectangles (svg_finalize/svg_rect_to_path.py): Transforms <rect rx="…"> elements into equivalent <path> elements because PowerPoint's shape engine cannot render the rx attribute directly.

The script displays a concise progress bar ([1/6] …) unless --quiet is used, and upon completion prints the next recommended command:

python scripts/svg_to_pptx.py "<project_dir>" -s final

Source: [skills/ppt-master/scripts/finalize_svg.py](https://github.com/hugohe3/ppt-master/blob/main/skills/ppt-master/scripts/finalize_svg.py)

Stage 3: Converting Finalized SVGs to PowerPoint with svg_to_pptx.py

The svg_to_pptx.py script is a thin wrapper that forwards execution to the external svg_to_pptx package installed as a PPT Master dependency.

from svg_to_pptx import main
if __name__ == '__main__':
    main()

This wrapper adds the scripts directory to sys.path and passes all arguments to the underlying package. The converter walks svg_final/, translates each SVG into native DrawingML shapes, and writes the final presentation to exports/<project>_<timestamp>.pptx. The -s final flag instructs the package to read from svg_final/ rather than the raw svg_output/ directory.

Source: [skills/ppt-master/scripts/svg_to_pptx.py](https://github.com/hugohe3/ppt-master/blob/main/skills/ppt-master/scripts/svg_to_pptx.py)

Complete Pipeline Execution Workflow

The three scripts execute sequentially to transform raw strategist output into a finished deck:

project/
├─ notes/
│   └─ total.md                # Combined speaker notes

├─ svg_output/                 # Raw SVGs from Strategist

├─ notes/<slide>.md             # Split by total_md_split.py

├─ svg_final/<slide>.svg        # Cleaned by finalize_svg.py

└─ exports/<project>_<ts>.pptx  # Final output from svg_to_pptx.py

Execute the full pipeline with these commands:

# 1. Split speaker notes

python3 skills/ppt-master/scripts/total_md_split.py projects/my_demo

# 2. Clean SVGs with all steps

python3 skills/ppt-master/scripts/finalize_svg.py projects/my_demo

# 3. Convert to PowerPoint

python3 skills/ppt-master/scripts/svg_to_pptx.py projects/my_demo -s final

Run selective cleanup steps using the --only flag:

python3 skills/ppt-master/scripts/finalize_svg.py projects/my_demo \
    --only embed-icons fix-rounded

For production builds with image compression and suppressed output:

python3 skills/ppt-master/scripts/finalize_svg.py projects/my_demo \
    --quiet --compress --max-dimension 2560

Summary

• total_md_split.py validates and splits notes/total.md into per-slide Markdown files that exactly match SVG filenames, ensuring perfect note-to-slide alignment.
• finalize_svg.py executes six ordered transformations—embed icons, crop images, fix aspect ratios, embed raster images, flatten text elements, and convert rounded rectangles—to produce PowerPoint-compatible SVGs in the svg_final/ directory.
• svg_to_pptx.py wraps the external conversion library to render finalized SVGs into native PowerPoint DrawingML and output the completed .pptx file to the exports/ folder.

Frequently Asked Questions

What happens if a speaker note doesn't match any SVG file in total_md_split.py?

The check_svg_note_mapping() function detects unmatched headings and aborts the process with a clear error message. This validation ensures that every slide has corresponding speaker notes before proceeding to conversion, preventing orphaned slides or missing documentation in the final PowerPoint.

Can I run individual SVG cleanup steps without executing the entire finalize_svg.py pipeline?

Yes. Use the --only flag followed by the specific step names: embed-icons, crop-images, fix-aspect, embed-images, flatten-text, or fix-rounded. This is useful for debugging specific compatibility issues without reprocessing unchanged elements.

Why does finalize_spg.py copy files to svg_final/ instead of modifying them in place?

The script preserves the original strategist output in svg_output/ as an immutable source of truth. By writing all transformations to svg_final/, you can re-run the pipeline with different parameters or debug intermediate stages without regenerating the initial SVGs from the strategist.

Does svg_to_pptx.py require Microsoft PowerPoint to be installed?

No. The script relies entirely on the svg_to_pptx Python package, which generates native Office Open XML (OOXML) markup directly. The conversion happens programmatically without COM automation or a local PowerPoint installation, making it suitable for CI/CD environments and headless servers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}