Build System Demo

Build System Demo

Marp Presentation Harness with Sectioned Authoring

Build System Demo

Table of Contents

Topics

  • Sectioned Authoring 4
  • Section File Anatomy 5
  • Theme System 7
  • Build Pipeline 9
  • Build Commands 10
  • Claude Code Skills 12
Build System Demo

Sectioned Authoring

Build System Demo

How Sectioned Authoring Works

The Problem

  • Monolithic slides.md files grow unwieldy past 20 slides
  • Hard to reorganize, reorder, or collaborate on
  • Merge conflicts on every edit

The Solution

  • Each topic gets its own file under sections/
  • Files are numbered: 01-title.md, 02-background.md, ...
  • assemble-sections.sh concatenates them in sort order into slides.md
Build System Demo

Section File Anatomy

00-frontmatter.md

YAML frontmatter only: marp: true, theme, paginate, html, header. No slide content here.

01-title.md, 02-*.md, ...

One or more slides per file. Slides separated by --- within the file. No leading --- needed.

Speaker Notes

HTML comments (<!-- ... -->) after all slide content. One note block per slide.

slides.md

Build artifact assembled from sections. Never edit directly. Removed by make clean.

Build System Demo

Theme System

Build System Demo

Self-Contained Themes

Structure

  • Each theme is a folder under themes/
  • Contains theme.css, assets/, and image-style.md
  • Assets organized by type: logo/, partner/, customer/, common/
  • CSS references assets with relative paths

Portability

  • No shared assets between themes
  • Switching themes changes one parameter: THEME=bai-flat
  • Per-presentation theme.css override for local tweaks
  • merge-theme.js combines base + local CSS at build time
Build System Demo

Build Pipeline

Build System Demo

Pipeline Steps

  • 1. Assemble
    assemble-sections.sh concatenates sections/*.md into slides.md at the presentation root
  • 2. Merge Theme
    merge-theme.js combines base theme CSS with optional per-presentation overrides, resolving all url() paths
  • 3. Marp Build
    npx marp converts the assembled markdown to HTML or PDF with the merged theme and engine config
  • 4. Post-process
    marp-postprocess.js inlines all local images and CSS assets as data URIs for a self-contained output file
Build System Demo

Build Commands

  • Setup make setup installs marp-cli and plugins via npm
  • HTML make html DIR=/path/to/talk THEME=bai-flat builds self-contained HTML
  • PDF make pdf DIR=/path/to/talk THEME=bai-flat builds PDF via headless Chrome
  • Clean make clean DIR=/path/to/talk removes output/ and assembled slides.md
Build System Demo

Claude Code Integration

Build System Demo

Skills Overview

/new-presentation

Scaffolds the directory structure, creates 00-frontmatter.md and synopsis.md. One command to go from topic to working directory.

/generate-slides

Reads the synopsis and guide.md, plans section structure, generates all section files with varied layouts and speaker notes.

/build

Runs the full pipeline: assemble, merge theme, marp, post-process. Detects the presentation directory automatically.

/inspect

Captures per-slide screenshots and analyzes them for overflow, alignment, and readability issues.

Build System Demo

Thank You

Questions?

Welcome to the build system demo. This deck walks through the template-gen harness: how presentations are authored in sections, how themes work, what the build pipeline does, and how Claude Code skills tie it all together.

Four main sections today. We start with how slide content is organized, then cover themes, the build pipeline, and finally Claude Code integration.

Let's start with the core authoring model.

A single slides.md works fine for short decks, but anything past 20 slides becomes painful. Splitting by topic means you can reorder sections by renaming files, and multiple people can edit different sections without conflicts.

The frontmatter file is special: it contains only YAML configuration and must use the 00- prefix so the assembler knows not to insert an extra separator after it. Everything else is content files with standard Marp slide separators.

Next, how themes are structured and how they stay portable.

Each theme is fully self-contained. If two themes need the same logo, we copy it into both rather than sharing. This keeps themes portable and independent. The merge script handles combining the base theme with any per-presentation overrides.

Now let's look at what happens when you run make html.

Four stages, all orchestrated by the Makefile. The assemble step is why slides.md lives at the presentation root, next to the images folder: Marp resolves image paths relative to the source file. The post-process step makes the output fully portable, no external file dependencies.

DIR must be an absolute path or relative to your current working directory. THEME defaults to bai-flat if omitted. The clean target removes both the output directory and the assembled slides.md build artifact.

Finally, how Claude Code skills accelerate the workflow.

Each skill maps to a step in the workflow. Scaffold with /new-presentation, write a synopsis, generate with /generate-slides, build with /build, and verify with /inspect. The skills read the same guide.md and writing rules that a human author would reference.

That wraps up the build system demo. Happy to take questions about the harness, the build pipeline, or how to set up your own presentations.