markdown-pptx

markdown-pptx turns constrained Markdown into editable PowerPoint .pptx presentations built from real PowerPoint layouts and placeholders. It is a strict, predictable CLI designed for both people and coding agents.

Quick start with an agent

Install the managed agent skill:

uvx markdown-pptx skill install

Then use $markdown-pptx in Codex, Claude Code, or another agent harness that supports skills:

Use $markdown-pptx to create a seven-slide presentation about our product launch. Use a clear narrative, include speaker notes, and save both the Markdown source and editable PowerPoint deck.

The skill teaches the agent how to inspect the format and templates, write valid slide Markdown, render the deck, and handle the result.

What it creates

Markdown stays readable, while the generated presentation remains easy to edit in PowerPoint.

Use the CLI directly

Render a deck without installing the package globally:

uvx markdown-pptx deck.md deck.pptx

Inspect the supported format or the layouts in the default template:

uvx markdown-pptx --syntax
uvx markdown-pptx --list-layouts

To install the command as a persistent tool instead:

uv tool install markdown-pptx

The examples below continue to use uvx markdown-pptx so they work without a global installation.

How the format works

The document model has four core rules:

1. Optional document front matter may appear only at the beginning of the file.
2. Each # H1 starts exactly one slide.
3. Optional slide front matter may appear only immediately after its H1.
4. Everything until the next H1 belongs to that slide.

A minimal two-slide deck looks like this:

# Quarterly review
---
layout: Title Slide
---

Acme Corporation

# Highlights
---
layout: Title and Content
---

- Revenue grew 18%
- Customer retention reached 94%
- Two new products launched

Render it with:

uvx markdown-pptx deck.md deck.pptx

If no --template is provided, the packaged default template is used.

Use a PowerPoint template

Inspect a template before writing the deck, then use only the layouts it provides:

uvx markdown-pptx --list-masters --template theme.pptx
uvx markdown-pptx --list-layouts --template theme.pptx --master 2
uvx markdown-pptx deck.md deck.pptx --template theme.pptx --master 2

All embedded slide masters are retained in the output. This keeps every layout group available in PowerPoint after the deck is generated.

The effective master is selected in this order:

1. The slide-level master value
2. The CLI --master option
3. The first embedded master

Master selectors may be 1-based indices or exact unique master or theme names. Indices are the most reliable choice because template names can be blank or duplicated. Layout names are resolved only within the effective master.

The renderer uses real placeholders for slide titles and bodies. Missing placeholders, duplicate layout names, and ambiguous placeholder mappings are errors. It does not invent free-positioned text boxes to compensate for an incompatible template.

Customize a deck

Document front matter sets deck-wide defaults:

Slide front matter controls an individual slide:

Run uvx markdown-pptx --syntax for the complete schema, accepted values, and examples.

Theme colors

Use color_scheme to recolor theme-aware template content throughout the presentation:

---
color_scheme:
  preset: Office
  dark_1: "#10263F"
  light_1: "#F9F9F9"
  accent_1: "#1D6FA8"
  accent_2: "#5AA9E6"
title_color: "var(--dark-1)"
body_color: "var(--dark-2)"
---

Colors accept hex, RGB, HSL, and PowerPoint theme references such as var(--accent-1). Set preset: null and provide all 12 theme slots for a fully custom palette. Theme-aware template objects follow the resulting palette, while hard-coded RGB colors and images do not.

When a template should provide the colors, use --ignore-document-colors, --ignore-slide-colors, or both. These options do not change images, layouts, or content.

Tables

Write standard Markdown pipe tables and put PowerPoint styling options in slide front matter:

# Quarterly summary
---
layout: Title and Content
table:
  header_row: true
  total_row: true
  first_column: true
  banded_rows: true
---

| Region | Revenue |
| --- | ---: |
| North | $50,000 |
| Total | $50,000 |

Table flags control native PowerPoint styling. They do not calculate totals or change the Markdown table structure. A slide may use table metadata only when its body contains exactly one table.

Images and paths

Local image paths are resolved relative to the Markdown file. Remote HTTP and HTTPS images are enabled by default. Use --no-remote-images for offline builds or untrusted Markdown. Download assets ahead of time and use local paths when reproducible builds matter.

When reading Markdown from stdin, provide an output path and a base directory for relative assets:

uvx markdown-pptx --input - --output deck.pptx --base-dir ./assets

Layouts and supported content

The built-in template provides these common layouts. Supplied templates may use different names and placeholders.

Supported Markdown includes:

• Paragraphs
• Bullet and ordered lists, nested up to three levels
• ## through ###### headings within a slide
• Emphasis, strong text, inline code, and links
• Fenced code blocks
• Blockquotes
• Pipe tables
• Local and remote images

The intentionally unsupported set includes:

• Setext headings
• Indented code blocks
• Horizontal rules
• Raw HTML
• Task lists
• Footnotes
• Arbitrary positioning
• Layered backgrounds
• Animations

Automation and image export

Structured results and overwrite safety

Use --json for agent and automation workflows:

uvx markdown-pptx deck.md deck.pptx --json

Successful JSON includes the output path, slide count, and template master details. Failures include a stable error code and relevant input, line, slide, or partial-output context.

The CLI refuses to overwrite an existing presentation or colliding generated image. Add --force only when replacing generated output is intended:

uvx markdown-pptx deck.md deck.pptx --force --json

Export slide images on Windows

On Windows, the CLI can use an installed desktop copy of Microsoft PowerPoint to export PNG or JPEG previews after generating the editable presentation:

uvx markdown-pptx deck.md deck.pptx --export-images png --slides 1,3-5 --image-width 1600 --json

Image export requires Windows, an interactive desktop session, and an installed, licensed, initialized PowerPoint application. The default output directory is <pptx-name>-images. PNG is recommended for text and diagrams.

The editable .pptx is retained if image export fails. With --json, the partial output path is reported in error.details.pptx_output.

Reference

Useful discovery and metadata commands:

uvx markdown-pptx --help
uvx markdown-pptx --syntax
uvx markdown-pptx --list-color-schemes
uvx markdown-pptx --list-masters --template theme.pptx
uvx markdown-pptx --list-layouts --template theme.pptx --master 2
uvx markdown-pptx --about
uvx markdown-pptx --version

Exit codes:

Examples

• Sample source deck
• Sample rendered deck
• Sample multi-master template
• Sample local image

Regenerate the showcase from the repository checkout:

uvx --refresh --from . markdown-pptx sample/showcase.md sample/showcase.pptx --template sample/showcase-template.pptx --force

Development

Install the development environment and run the checks:

uv sync --locked --all-groups
uv run pytest
uv run ruff check .
uv run ruff format --check .

The real PowerPoint export smoke test is optional and requires desktop PowerPoint:

$env:MARKDOWN_PPTX_TEST_POWERPOINT="1"
uv run pytest tests/test_powerpoint_integration.py

Build and validate distributable packages:

uv build
uv run twine check dist/*