Marp Slides

Marp slide builder with auto-layout

Convert content-only markdown into a Marp deck where each slide's layout matches its content shape. Don't bullet-ify everything — that's the failure mode this skill exists to prevent.

Related skills

Part of the marpsmith bundle — composes with:

• theme-generator — generate a new theme CSS from brand colors, then set it as the deck's theme:.
• deck-a11y-audit — check a finished deck or theme for WCAG contrast and colorblind safety.

> Script paths below use `` — the skills directory configured by the active agent harness; the marpsmith skills live there together.

Workflow

1. Read the source document fully before writing any slides. Layout decisions need the whole document's structure, not just one section at a time.
2. Read the active theme — check .marprc.yml (or the deck frontmatter) for the theme name, then skim the theme CSS. Note: (a) heading prefix style — does it emit ## / # before headings? If yes, those ~3 chars count against per-line length budget and increase overflow risk for long headings; (b) list marker style — numbered lists with the theme's marker color and spacing; (c) any custom layout classes beyond the standard 12; (d) light vs. dark background — affects legibility of code blocks and image-heavy slides. These observations should inform phrasing choices and layout selection throughout the conversion.
3. Set up the project (only if not already configured). 5 supported starter themes live under themes/ — single CSS files with palette + layout structure merged in. All share the var-based theming contract: layouts and structure live in a common block driven by CSS custom properties; each theme's palette section sets those vars. A deck written for one theme renders correctly under any other — only the frontmatter theme: line changes. Some themes also append a small layout variant override (uppercase section dividers, neon glow on hero stats, bordered big-stat, etc.) — the variant changes how a layout renders but never breaks the markdown contract. See themes/README.md for the full catalog (dark, light, high-contrast, newspaper, synthwave). Copy what you need to .marp/ and register them in .marprc.yml (see "File setup" below). Don't replace the user's existing theme. To create a new color variant, copy dark.css (for dark-bg) or light.css (for light-bg) and adapt the palette section, including the CSS-var declarations.
4. Segment the source into "content blocks" — typically each heading with its body. Split further if a block is too dense for one slide, but do not over-split short adjacent prose blocks; merge related short blocks when they would produce sparse standalone slides.
5. For each block, run the decision rubric (below) to pick a layout. First match wins.
6. Emit the slides with appropriate ` directives and the markdown patterns documented per-layout below. **Do not** add heading scale modifiers (h-XX) — headings are never scaled down (see "Heading size rule" below). **Do not** add body scale modifiers (b-XX) by hand — auto-fit.mjs assigns them. **Preserve the original heading level** — if the source has ### Subsection, render the slide heading as ###, not ##`. The hierarchy carries meaning (part > section > subsection) that flattening destroys.
7. Pre-flight lint — run node /marp-slides/scripts/lint-deck.mjs (see "Pre-flight linter" section). Fast, render-free markdown analysis that mechanizes the cheap checks: layout repetition, sparse prose, asymmetric comparisons, missing pull-quote attribution, heading wrap risk, process-flow verb cues, over-dense bullet lists, over-long tables, frontmatter sanity, duplicate _class directives. Fix HIGH and MED findings in source before moving on; LOW findings are advisory.
8. Auto-fit pass — run node /marp-slides/scripts/auto-fit.mjs --apply --theme (see "Auto-fit" section). When --theme points to a CSS file, the script registers it with Marp's themeSet so the deck frontmatter remains authoritative. The script measures each slide's rendered geometry, picks the smallest discrete body scale that fits, and writes b-XX classes back to the markdown. Headings are never scaled. Slides that can't fit at the body floor (b-90) are flagged for splitting via stderr.
9. Apply split recommendations. For each split-* action surfaced by auto-fit, read the slide content and split it:

• split-list-midpoint — pure list slide; split items at midpoint, reuse heading on both halves.
• split-paragraph-midpoint — multi-paragraph prose; split at paragraph midpoint.
• split-table-midpoint — single-table slide; split rows at midpoint, refine sub-headings to label each half (e.g., "Topic — Clinical" / "Topic — Community"). Keep the header row on both halves.
• split-comparison-detail — comparison slide that overflows; condense the original to a concise side-by-side overview, then add two detail slides (compare-detail-a for the left column's expansion, compare-detail-b for the right). The cyan/pink left-edge + tint preserves the visual association.
• split-restructure — mixed content (TL;DR + bullets, etc.); judgment required. Often the right call is to shorten the content or restructure it rather than split mechanically.
• See "Splitting strategy" below for content-aware guidance.

1. Re-run auto-fit + sanity backstop. Run auto-fit again; should be idempotent. Then run check-slides.mjs as a backstop — it should report zero vertical-overflow HIGH issues. Repeat up to 3 iterations if splits introduced new overflow.
2. Quality checklist pass (existing checklist at the end of this file).
3. Escalation — if HIGH-severity issues remain after 3 iterations, surface a summary to the user with specific slide indices and ask for guidance. Don't silently ship broken slides.

Heading hierarchy

Keep the source document's heading tiers intact across the slide deck. A document structured as # → ## → ### should produce slides where:

• # headings appear on title-cover or section-divider slides as #
• ## headings on most content slides remain ##
• ### subsection headings stay ###
• #### and deeper render at their natural level

The theme's CSS styles each level differently (h1 has the largest tag background, h2 medium, h3 smaller, etc.), so preserving the level visually communicates depth without extra effort. Don't promote/demote headings just because you wrapped a slide in a layout class — the layout class controls positioning and decoration, the heading level controls hierarchical meaning.

Exception: if a layout class explicitly normalizes headings (e.g., big-stat-hero styles its label uniformly regardless of level), that's intentional. Otherwise, faithfully reflect the source.

Pre-flight linter

scripts/lint-deck.mjs is a fast, render-free markdown linter that runs before auto-fit. It catches deck-quality issues that don't require a Chrome render — usually in under 100 ms on a 50-slide deck.

# Default: print colorized summary, exit 1 on any finding
node /marp-slides/scripts/lint-deck.mjs path/to/deck.md

# Machine-readable JSON
node /marp-slides/scripts/lint-deck.mjs path/to/deck.md --json

# CI gate: only HIGH findings affect exit code
node /marp-slides/scripts/lint-deck.mjs path/to/deck.md --severity high

Exit codes: 0 = clean at the chosen severity threshold; 1 = at least one finding; 2 = script error.

Checks

| Rule | Severity | What it flags | |---|---|---| | frontmatter-missing / -no-marp / -no-theme | HIGH | YAML frontmatter missing, no marp: true, or no theme: | | duplicate-class-directive | HIGH | Two or more ` comments on a single slide (Marp uses the last — usually a bug) | | layout-repetition | MED | Same _class: directive on 4+ consecutive slides (Cross-deck variety rule) | | asymmetric-comparison | MED | comparison columns with word-count ratio > 3:1 | | heading-wrap-risk | MED | Heading > 60 chars on content layout, or > 40 chars on cover-like layout (title-cover, section-divider, big-stat-hero, pull-quote) | | bullet-list-too-many | MED | Default bullet slide with > 6 items (should be two-col-list) | | two-col-list-too-many | MED | two-col-list with > 10 items (should split) | | table-too-many-rows | MED | Table with > 6 data rows | | sparse-prose | LOW | prose` slide with /marp-slides/scripts npm install

**Invoke:**

```bash
# Dry run: emit JSON report, no writes.
node /marp-slides/scripts/auto-fit.mjs path/to/deck.md --theme path/to/theme.css

# Apply: rewrite markdown with recommended classes; surface splits to stderr.
node /marp-slides/scripts/auto-fit.mjs path/to/deck.md --theme path/to/theme.css --apply

When --theme is an existing CSS path, the helper registers it as a theme file (themeSet) and still lets the deck's frontmatter theme: choose by @theme name. When --theme is a non-path name, it uses Marp's theme override semantics.

The script is idempotent: it strips any existing h-XX / b-XX from the class list before computing fresh ones. Re-running after content edits yields fresh decisions.

Output (per slide that needs a class or a split):

{
  "index": 60,
  "action": "rescale",
  "h_scale": 1.0,
  "b_scale": 0.9,
  "recommended": ["b-90"],
  "evidence": { "overflow_at_1": 12 }
}

{
  "index": 75,
  "action": "split-restructure",
  "h_scale": 1.0,
  "b_scale": null,
  "recommended": [],
  "evidence": { "overflow_at_0_90": 18 }
}

split-list-midpoint and split-paragraph-midpoint are mechanical and obvious; split-restructure requires content judgment (see "Splitting strategy").

Exit code 1 if any split recommendations remain; 0 if everything fit by rescaling alone.

Heading size rule

Applies to all themes (dark, dark-derived color variants, monokai-glow variants, and any custom theme).

Headings on content slides always stay at the theme's default font size. Do not apply h-XX modifier classes. The auto-fit.mjs script skips heading scale entirely — the table in the Auto-fit section above has no h-XX column deliberately.

Covered layouts (headings must not be scaled): prose, prose-with-tldr, comparison, compare-detail-a / b, bullet list (default), two-col-list, process-flow, matrix-2x2, table / wide-table, code-showcase, image-led.

Excluded (intentionally oversized centered text — skip this rule): title-cover, section-divider, big-stat-hero, pull-quote.

What to do when a heading overflows one line:

1. Shorten the heading text first. Cut filler ("The", "Overview of"), tighten phrasing, drop subordinate clauses. Most headings can shed 20–40% of characters without losing meaning.
2. Two-line wrap is acceptable as a last resort. If the heading genuinely cannot be shortened without losing its argument, let it wrap to a second line. When it wraps, check that the break is semantically and visually natural: prefer phrase boundaries, subtitle separators, clause boundaries, or other meaningful units. Avoid breaks that orphan a key noun, split a named concept, or leave a qualifier disconnected from the phrase it modifies. If browser wrapping chooses a poor break, insert an explicit ` in the markdown at the better semantic break, for example ## ADHD, Anger, and Racial Misperception— The Systemic Pattern`.
3. Never shrink the heading font. A heading at 0.8em or 0.65em looks like body text and breaks the visual hierarchy. That outcome is worse than a two-line heading.

Splitting strategy

When auto-fit recommends a split, read the slide content before applying it. Mechanical density application loses information that thoughtful splitting preserves; mechanical splitting loses rhythm that thoughtful condensation preserves.

For split-list-midpoint: straightforward. Split items at (or near) the midpoint, reuse the heading on both halves OR refine each into a sub-heading (## Topic — Foundations / ## Topic — Advanced).

For split-paragraph-midpoint: straightforward. Split at the paragraph break.

For split-table-midpoint: straightforward. Cut data rows at the midpoint, keep the header row on both halves, and refine the heading on each half to label what set of rows it contains (semantic grouping beats (1/2) / (2/2) whenever the rows fall into natural categories).

For split-comparison-detail: turn one overflowing comparison into three slides:

1. The original comparison slide stays as the side-by-side overview, but condense each column's bullets to short labels (1–3 words). The audience sees the contrast frame.
2. A compare-detail-a slide expands the left column. Use whatever inner layout fits the content shape — prose compare-detail-a for short prose, prose-with-tldr compare-detail-a for denser prose, or just compare-detail-a for a regular bullet list. The cyan left edge + side-fade tint signals "this is the left column from the previous slide."
3. A compare-detail-b slide does the same for the right column with the pink accent.

The detail slides aren't side-by-side — they get the full slide width, with one column's worth of content expanded. The visual continuity comes entirely from the color cue. Don't add (detail) or — Expanded suffixes; the color does that work.

For split-restructure: judgment required. Common patterns:

• prose or prose-with-tldr with 2+ paragraphs covering distinct sub-themes → split into two prose slides, each with one paragraph. Keep a TL;DR only where it adds orientation; drop it when the heading carries the claim.
• comparison where one column has 8 bullets and the other has 3 → rebalance content rather than split (auto-fit can't help with column imbalance, but the recommendation flags it).
• Severe overflow (>30% over) on dense single-unit content → consider whether the slide is trying to do too much; often the right move is to shorten, not split.

Avoid splitting:

• pull-quote, big-stat-hero, title-cover, section-divider — these are standalone layouts. If they overflow, restructure or shorten.
• Slides where the rhythm relies on staying together (quote + immediate context, stat + explanation, list with a summary line).

Format for split slides:

• Reuse the same heading, OR refine into sub-headings (## Topic — Mechanism / ## Topic — Treatment Implications).
• Don't add (1/2) / (2/2) suffixes by default — they read as scaffolding. Use them only when explicit pagination helps the audience.
• After splitting, re-run auto-fit — the halves may now fit at 1.00, or fall to 0.95 / 0.90.

When the heading itself is the problem: the heading is too long. Don't shrink it — shorten the heading text. A 60+ character heading on a content slide is almost always over-detailed.

Backstop: check-slides.mjs

scripts/check-slides.mjs is a sanity check that runs after auto-fit. It emits a JSON report of remaining geometric issues — overflow, header collision, asymmetric columns, etc. After auto-fit + splits have been applied, this should report zero vertical-overflow HIGH issues. Use it for CI / automated quality gates.

node /marp-slides/scripts/check-slides.mjs path/to/deck.md --theme path/to/theme.css

As with auto-fit.mjs, a CSS path is registered with themeSet; it does not override the deck's frontmatter theme name.

Exit code 1 if any HIGH-severity issue remains; 0 otherwise.

File setup

Five supported starter themes under themes/. Each is a single CSS file — palette + layout structure merged in. No external CSS dependencies beyond an optional Google Font import (Newspaper). The full catalog with variants is in themes/README.md.

All themes share the var-based theming contract: a common layout block driven by CSS custom properties. Themes that

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: RanaCM
• Source: RanaCM/marpsmith
• License: MIT

Install and usage instructions live in the source repository linked above.