Markdown Universal Slides Generator

Convert Markdown source files to presentation slides in multiple formats.

First Step: Always read and apply a visual template from templates/visual/ before generating slides. This ensures consistent visual output.

Core Concept

One source, multiple outputs:

slides.md → Marp/Pandoc/python-pptx → PDF / PPTX / HTML

Slide Flavors

When creating slides, ask or infer these parameters to customize output:

Audience Types

Visual Styles

Language Options

Content Density

Flavor Examples

Manager presentation (Chinese):

audience: manager
style: professional
language: zh
length: standard

→ Use Gaia theme, executive summary, key findings, recommendations

Technical tutorial (English):

audience: developer
style: minimal
language: en
length: detailed

→ Use default theme, code examples, step-by-step

Research showcase:

audience: general
style: visual
language: mixed
length: standard

→ Use Gaia with custom CSS, screenshots, comparisons

Prerequisites Check

Before generating output, verify required tools are installed:

Workflow:

1. Check if required tool exists before running
2. If missing, detect OS (uname -s) and show install command
3. After install, verify with version check

Available Tools & Best Use Cases

Quick Commands

Generate with Marp (Recommended)

# PDF output
marp slides.md -o slides.pdf

# PPTX output
marp slides.md -o slides.pptx

# HTML output
marp slides.md -o slides.html

# With custom theme
marp slides.md --theme gaia -o slides.pdf

# Allow local images
marp slides.md -o slides.pdf --allow-local-files

Generate with Pandoc Beamer

# Basic PDF
pandoc slides.md -t beamer -o slides.pdf

# With XeLaTeX (better font support, required for CJK)
pandoc slides.md -t beamer --pdf-engine=xelatex -o slides.pdf

# With theme
pandoc slides.md -t beamer -V theme:metropolis -o slides.pdf

# CJK support
pandoc slides.md -t beamer --pdf-engine=xelatex \
  -V mainfont="Noto Sans CJK SC" -o slides.pdf

Generate with reveal.js

pandoc slides.md -t revealjs -s -o slides.html
pandoc slides.md -t revealjs -s -V theme=moon -o slides.html

Visual Templates (Visual Consistency)

IMPORTANT: Before generating slides, always use a visual template for consistent rendering.

Visual templates are in templates/visual/:

• default-zh.md — Chinese slides
• default-en.md — English slides

How to Use

1. Read the appropriate template: templates/visual/default-{lang}.md
2. Copy its frontmatter exactly (don’t modify)
3. Follow the gotchas listed in the template

Quick Reference (Chinese)

---
marp: true
theme: default
paginate: true
size: 16:9
style: |
  section {
    font-family: 'Noto Sans CJK SC', 'Microsoft YaHei', sans-serif;
  }
  section.small-table table { font-size: 0.85em; }
---

Rules for Consistent Output

Custom Looks

Users can add custom visual templates to templates/visual/. See templates/visual/README.md.

Markdown Slide Format

Marp Format

---
marp: true
theme: default  # or gaia, uncover
paginate: true
---

# Slide Title

Content here

---

# Next Slide

- Bullet points
- More content

Pandoc/Beamer Format

---
title: Presentation Title
author: Author Name
date: 2026
---

# Section Title

## Slide Title

- Content
- More content

---

## Another Slide

Content continues

Generating Visual Showcases

When user wants to compare tools visually:

1. Create sample slides with representative content:

   • Title slide with Chinese/English
   • Code highlighting example
   • Math formulas
   • Tables

2. Generate outputs from all tools:

   # Marp outputs
   marp sample.md -o output/marp.pdf
   marp sample.md -o output/marp.pptx
   
   # Beamer outputs
   pandoc sample.md -t beamer --pdf-engine=xelatex -o output/beamer.pdf
   
   # Pandoc PPTX
   pandoc sample.md -o output/pandoc.pptx
   

3. Create screenshots for comparison:

   pdftoppm -png -f 1 -l 1 -r 150 output/marp.pdf screenshots/marp
   pdftoppm -png -f 1 -l 1 -r 150 output/beamer.pdf screenshots/beamer
   

4. Build comparison presentation with embedded screenshots

Tool Selection Guide

LLM Integration Pattern

import subprocess

def generate_slides(content: str, output_path: str):
    """Generate slides from LLM-produced content."""
    md_content = f"""---
marp: true
theme: gaia
paginate: true
---

{content}
"""
    with open("/tmp/slides.md", "w") as f:
        f.write(md_content)

    subprocess.run(["marp", "/tmp/slides.md", "-o", output_path], check=True)
    return output_path

Troubleshooting

Reference Files

• Sample Markdown: docs/sample-universal.md
• Marp-specific sample: docs/sample-marp-format.md
• Research report: docs/report-research-zh.md
• Showcase presentation: docs/presentation-showcase-zh.md