Skip to content

Instantly share code, notes, and snippets.

@jacobh

jacobh/md2pptx_cheat_sheet.md

Created July 16, 2025 17:21
Show Gist options
  • Save jacobh/f6efd2cfbf81d78de6f594b9284e85cf to your computer and use it in GitHub Desktop.
Save jacobh/f6efd2cfbf81d78de6f594b9284e85cf to your computer and use it in GitHub Desktop.
Download ZIP
Raw
md2pptx_cheat_sheet.md

md2pptx Cheat Sheet for LLMs

md2pptx is a tool that converts Markdown files to PowerPoint presentations. This cheat sheet provides comprehensive syntax and features for creating presentations with md2pptx.

Table of Contents

  1. Basic File Structure
  2. Metadata Configuration
  3. Slide Types
  4. Content Types
  5. Text Formatting
  6. Media and Graphics
  7. Tables
  8. Card Slides
  9. Code Slides
  10. Funnels
  11. Dynamic Metadata
  12. Python Integration
  13. Navigation and Links
  14. Advanced Features
  15. Common Patterns

Basic File Structure

File Header

template: Martin Template.pptx
pageTitleSize: 24
sectionTitleSize: 30
baseTextSize: 18
numbers: yes

# Presentation Title
Subtitle text goes here

## Section One Title

### Content Slide Title

Essential Metadata

# Always specify these at the start
template: Martin Template.pptx          # Template file
pageTitleSize: 24                       # Content slide title size
sectionTitleSize: 30                    # Section slide title size
baseTextSize: 18                        # Base text size
numbers: yes                            # Show slide numbers

Metadata Configuration

Title and Text Sizing

# Title sizes
pageTitleSize: 24                       # Content slide titles
pageSubtitleSize: 22                    # Content slide subtitles
sectionTitleSize: 30                    # Section titles
sectionSubtitleSize: 24                 # Section subtitles
presTitleSize: 42                       # Presentation title
presSubtitleSize: 28                    # Presentation subtitle

# Text sizing
baseTextSize: 18                        # Base text size
baseTextDecrement: 2                    # Size decrease per bullet level

Layout and Spacing

marginBase: 0.5                         # Margin around content (inches)
tableMargin: 0.3                        # Table margins
numbersHeight: 0.4                      # Space for slide numbers

Colors and Styling

# Color definitions
BoldColour: ACCENT 1                    # Bold text color
ItalicColour: ACCENT 2                  # Italic text color
style.fgcolor.highlight: FF0000         # Custom foreground color
style.bgcolor.yellow: FFFF00            # Custom background color
style.emphasis.important: bold underline # Custom emphasis

# Color formats
# Theme colors: ACCENT 1, ACCENT 2, BACKGROUND 1, TEXT 1, etc.
# RGB colors: #FF0000, #00FF00, #0000FF (hex format)

Template and Layout

template: MyTemplate.pptx               # Custom template
monoFont: Consolas                      # Monospace font
AdjustTitles: no                        # Don't auto-adjust titles

Slide Types

1. Presentation Title Slide

# Main Presentation Title
Additional subtitle information
Author details
Date information

2. Section Slides

## Section Title
Additional section information

3. Content Slides

### Content Slide Title

4. Slides Without Titles

---
# Or use:
###  

Content Types

Bullet Lists

### Bullet Slide Title

* First level bullet
  * Second level bullet
    * Third level bullet
  * Another second level
* Another first level bullet

Numbered Lists

### Mixed Lists

* Bullet item
  1. Numbered sub-item
  1. Another numbered sub-item
* Another bullet item

Mixed Content (Multiple blocks)

### Multi-Content Slide
<!-- md2pptx: contentSplit: 1 2 -->
<!-- md2pptx: contentSplitDirection: horizontal -->

* Bullet content
  * Sub-bullet

![](image.png)

Text Formatting

Basic Formatting

**Bold text**
*Italic text*
`Monospace text`
<br/>                                   # Line break

Advanced Text Effects

<sup>Superscript</sup>
<sub>Subscript</sub>
<ins>Underlined</ins>
<del>Strikethrough</del>

Span Elements with Classes

<span class="highlight">Highlighted text</span>
<span class="warning">Warning text</span>

# Define classes in metadata:
style.bgcolor.highlight: FFFF00
style.fgcolor.warning: FF0000

Span Elements with Inline Styles

<span style="color: #FF0000; font-weight: bold;">Red bold text</span>
<span style="background-color: #FFFF00;">Yellow background</span>
<span style="font-size: 20px;">Large text</span>

HTML Entity References

&amp;    # &
&lt;     # <
&gt;     # >
&nbsp;   # Non-breaking space
&hellip; # …
&rarr;   # →
&larr;   # ←
&check;  # ✓
&times;  # ×
&divide; # ÷

Media and Graphics

Single Graphics

### Graphic Slide Title

![](image.png)
![Alt text](image.jpg)                  # With tooltip
![Tooltip text](https://example.com/image.png)  # Web image

Clickable Graphics

[![Tooltip](image.png)](#target-slide)  # Links to another slide

Two Graphics Side by Side

### Two Graphics

|![](left.png)|![](right.png)|

Four Graphics Grid

### Four Graphics Grid

|![](top-left.png)|![](top-right.png)|
|![](bottom-left.png)|![](bottom-right.png)|

Three Graphics Layout

### Three Graphics

|![](top-left.png)|![](top-right.png)|
|![](bottom-center.png)|

Video and Audio

### Video Slide

<video width="400" height="300" src="video.mp4"></video>
<video width="400" height="300" src="video.mp4" poster="poster.png"></video>

### Audio Slide

<audio src="audio.mp3"></audio>
<audio src="audio.mp3" poster="album-cover.png"></audio>

Supported Graphics Formats

  • PNG, JPEG (native support)
  • SVG (requires CairoSVG)
  • EPS (requires Pillow and Ghostscript)
  • Data URLs: ![](data:image/png;base64,iVBORw0KGgoAAAA...)

Tables

Basic Table

### Table Slide

|Left Header|Center Header|Right Header|
|:----------|:----------:|----------:|
|Left data  |Center data |Right data |
|More data  |More center |More right |

Column Width Control

# Number of dashes controls relative width
|Narrow|----Wide----|--Medium--|
|:-----|:-----------|:---------|
|A     |B           |C         |

Table Options (Metadata)

compactTables: 14                       # Compact font size
tableHeadingSize: 20                    # Header font size
addTableLines: both                     # Add borders
addTableRowLines: 1                     # Lines after rows
addTableColumnLines: 1 3                # Lines after columns
addTableLineColour: 000000              # Line color
tableShadow: yes                        # Drop shadow

Multi-Column Cells

|A||C|                                  # Empty cell spans columns
|:-:|:-:|:-|
|Spans two||One cell|
|1|2|3|
||A|B|                                  # Empty first cell

Card Slides

Basic Card Layout

### Card Slide Title

#### Card One
* Card content
* More content

#### Card Two
* Different content
* More items

#### Card Three
* Third card
* Content here

Card with Graphics

#### Card Title

![](card-image.png)

* Card content below image
* More content

Card Metadata Configuration

# Card appearance
CardColour: ACCENT 1, ACCENT 2, ACCENT 3  # Background colors
CardBorderColour: TEXT 1                   # Border color
CardBorderWidth: 2                         # Border width
CardTitleSize: 16                          # Title font size
CardTitleColour: DARK 1                    # Title color
CardTitleAlign: center                     # Title alignment
CardTitlePosition: above                   # above or inside
CardShape: rounded                         # rounded, squared, line
CardLayout: horizontal                     # horizontal or vertical
CardPercent: 80                            # Space used by cards
CardShadow: yes                            # Drop shadow
CardHorizontalGap: 0.25                    # Gap between cards
CardVerticalGap: 0.1                       # Vertical gap
CardGraphicSize: 0.75                      # Graphic size (inches)
CardGraphicPosition: before                # before or after

Code Slides

Code Block with Language

### Code Slide

```python
def hello_world():
    print("Hello, World!")
    return True

Triple Backticks

### Code Example

for i in range(10): print(i)


### HTML Code Element
```markdown
### Code Sample

<code>
function example() {
    return "Hello";
}
</code>

Indented Code

### Indented Code

    def example():
        return "Hello World"

Syntax Highlighted Code

### Highlighted Code

<pre>
<span class="keyword">def</span> <span class="function">example</span>():
    <span class="keyword">return</span> <span class="string">"Hello"</span>
</pre>

# Define syntax colors:
style.fgcolor.keyword: 0000FF
style.fgcolor.function: 008000
style.fgcolor.string: 800000

Code Metadata

CodeColumns: 80                         # Code width
CodeForeground: 000000                  # Text color
CodeBackground: FFFFFF                  # Background color
FPRatio: 1.2                           # Height to width ratio

GraphViz Support

### GraphViz Diagram

```dot
digraph G {
    A -> B;
    B -> C;
    C -> A;
}

Funnels

Basic Funnel

### Funnel Slide

``` funnel
1000 Visitors,Website Traffic
100 Leads,Lead Generation
50 Qualified,Sales Qualified
25 Customers,Converted

Funnel Metadata

funnelColours: ACCENT 1, ACCENT 2, ACCENT 3
funnelBorderColour: 000000
funnelTitleColour: FFFFFF
funnelTextColour: 000000
funnelLabelsPercent: 15
funnelLabelsPosition: before           # before or after
funnelWidest: left                     # left, right, top, bottom, pipe

Dynamic Metadata

Slide-Level Overrides

### Special Slide
<!-- md2pptx: baseTextSize: 16 -->
<!-- md2pptx: cardLayout: vertical -->
<!-- md2pptx: compactTables: 12 -->
<!-- md2pptx: backgroundImage: special-bg.png -->
<!-- md2pptx: contentSplit: 1 2 -->
<!-- md2pptx: contentSplitDirection: horizontal -->
<!-- md2pptx: hidden: yes -->

Multiple Content Blocks

### Multi-Block Slide
<!-- md2pptx: contentSplit: 1 3 -->
<!-- md2pptx: contentSplitDirection: horizontal -->

* First block content
  * Sub-bullet

![](second-block-image.png)

Reverting Settings

### Next Slide
<!-- md2pptx: baseTextSize: pres -->     # Back to presentation default
<!-- md2pptx: cardLayout: default -->     # Back to md2pptx default
<!-- md2pptx: compactTables: prev -->     # Previous value

Python Integration

Inline Python

### Python Enhanced Slide

``` run-python
# Create a chart from CSV data
chart_csv = RunPython.readCSV("data.csv")
chart_data = RunPython.makeChartData(chart_csv)
chart = RunPython.makeChart(slide, XL_CHART_TYPE.COLUMN_CLUSTERED, 
                           renderingRectangle, chart_data, 
                           "Chart Title", XL_LEGEND_POSITION.BOTTOM)

Python from File

### Python from File

``` run-python mycode.py

Python Variables Available

  • prs - Presentation object
  • slide - Current slide object
  • renderingRectangle - Available drawing area

Common Python Functions

# CSV and data handling
data = RunPython.readCSV("file.csv")
filtered = RunPython.filterRows(data, filter_func)
transposed = RunPython.transposeArray(data)

# Charts
chart_data = RunPython.makeChartData(data)
chart = RunPython.makeChart(slide, chart_type, rect, data, title, legend)

# Tables
table = RunPython.makeTable(slide, rect, data)
RunPython.applyCellFillRGB(table, row, col, r, g, b)

# Shapes and annotations
shape = RunPython.makeDrawnShape(slide, vertices, filled, text, color)
RunPython.annotationsFromCSV(slide, "annotations.csv")

# Checklists
RunPython.checklistFromCSV(slide, rect, "checklist.csv")

Navigation and Links

Internal Links

### Source Slide

Link to [target slide](#target-reference)

### Target Slide [target-reference]
Content here

Alternative Anchor Method

### Target Slide
<a id="target-reference"></a>

External Links

### External Links

[Website](https://example.com)
[Company Site](https://company.com)

Clickable Images

[![Image tooltip](image.png)](#target-slide)

VBA Macro Links

[Run Macro](ppaction://macro?name=myMacro)

Advanced Features

Task Lists (Taskpaper Format)

- USER: Complete user documentation @due(2024-01-15) @tags(docs,priority)
- DEV: Implement feature @done(2024-01-10)
- MANAGER: Review progress @tags(review)

Glossary Terms

The <abbr title="Application Programming Interface">API</abbr> is important.

Footnotes

This has a footnote[^1].

[^1]: This is the footnote text.

Slide Notes

### Slide Title

Slide content here

This is a slide note. It appears in PowerPoint's notes section.
More note content here.

Background Images

backgroundImage: background.png

# Or per slide:
### Special Slide
<!-- md2pptx: backgroundImage: special-bg.png -->

Slide Transitions

transition: ripple

# Available transitions:
# ripple, reveal, honeycomb, shred, wipe, vortex, fracture, split, push

Table of Contents

### Topics

* [Section One](#section-one)
* [Section Two](#section-two)
* [Section Three](#section-three)

# Configure TOC style:
tocStyle: chevron                       # chevron, circle, plain
tocTitle: Agenda                        # Custom TOC title
tocLinks: yes                          # Enable live links

Hidden Slides

hidden: no                             # Default for all slides

### Hidden Slide
<!-- md2pptx: hidden: yes -->

Footer Text

leftFooterText: Section <section>
middleFooterText: <presTitle>
rightFooterText: Page <pageNumber>
footerFontSize: 10

Common Patterns

Standard Presentation Structure

template: Martin Template.pptx
pageTitleSize: 24
sectionTitleSize: 30
baseTextSize: 18
numbers: yes

# Presentation Title
Subtitle and author information

## Introduction

### Overview
* Key points
* Objectives
* Agenda

## Main Content

### Key Concepts
* Concept 1
* Concept 2
* Concept 3

### Supporting Details
* Detail 1
* Detail 2

## Conclusion

### Summary
* Summary points
* Next steps

Multi-Media Rich Slide

### Rich Content Slide
<!-- md2pptx: contentSplit: 1 1 -->
<!-- md2pptx: contentSplitDirection: horizontal -->

* Key bullet points
* Supporting information
* Context details

![](supporting-image.png)

Technical Presentation Pattern

### Technical Implementation
<!-- md2pptx: contentSplit: 1 2 -->

* Overview points
* Key considerations

``` python
def implementation():
    return "code example"

Data Visualization

chart_data = RunPython.readCSV("metrics.csv")
chart = RunPython.makeChart(slide, XL_CHART_TYPE.LINE, 
                           renderingRectangle, chart_data)

Status Dashboard

RunPython.checklistFromCSV(slide, renderingRectangle, "status.csv", 
                          colourChecks=True)

Best Practices

1. Always Start with Metadata

template: Martin Template.pptx
pageTitleSize: 24
sectionTitleSize: 30
baseTextSize: 18
numbers: yes

2. Use Consistent Heading Levels

  • # for presentation title
  • ## for section slides
  • ### for content slides
  • #### for card titles

3. Optimize for Readability

  • Use appropriate font sizes
  • Maintain consistent spacing
  • Use bullet points effectively
  • Keep slides uncluttered

4. Leverage Dynamic Metadata

  • Override settings per slide as needed
  • Use contentSplit for complex layouts
  • Hide slides during development

5. Test Graphics and Media

  • Verify image paths and formats
  • Test video/audio compatibility
  • Use appropriate resolutions

Troubleshooting

Common Issues

  1. Images not loading: Check file paths and formats
  2. Table formatting: Verify column alignment syntax
  3. Code not highlighting: Check span class definitions
  4. Cards not displaying: Verify card metadata settings
  5. Links not working: Check anchor references

Debugging Tips

  • Check the processing summary slide for metadata
  • Verify file paths are correct
  • Test with simple examples first
  • Use the log output for error messages

Quick Reference

Essential Metadata Keys

template: Martin Template.pptx
pageTitleSize: 24
sectionTitleSize: 30
baseTextSize: 18
baseTextDecrement: 2
numbers: yes
BoldColour: ACCENT 1
ItalicColour: ACCENT 2

Slide Type Headers

# Presentation Title
## Section Title
### Content Title
#### Card Title
---                    # No title slide
### &nbsp;             # No title slide (alternative)

Content Blocks

* Bullets
|Table|Headers|
![](image.png)
```code```
``` funnel
``` run-python

Dynamic Controls

<!-- md2pptx: key: value -->

This cheat sheet covers the essential syntax and features of md2pptx. Use it as a reference when creating presentations to ensure proper formatting and take advantage of all available features.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment