marp2pptx

Marp to PowerPoint Converter (Pure JavaScript)

Convert Marp markdown presentations to theme-compatible, fully editable PowerPoint files with a single command.

✨ Features

• ✅ Single Language - Pure JavaScript/Node.js solution
• ✅ One Command - marp2pptx slides.md - that's it!
• ✅ Theme Compatible - Apply any PowerPoint theme, all slides adapt
• ✅ Fully Editable - All text, bullets, and formatting editable in PowerPoint
• ✅ Standard Layouts - Uses Title and Content placeholders
• ✅ Fast - Converts presentations in < 1 second
• ✅ No Python Required - Only Node.js needed
• ✅ Wildcard Support - Convert multiple files at once with *.md

⚠️ Known Limitations

Marp Themes Not Supported (v0.1.0)

Currently not supported:

• ❌ Marp theme directives (theme: gaia, theme: uncover, etc.)
• ❌ Local Marp theme files (.css)
• ❌ Remote Marp themes (URLs)
• ❌ Custom <style> blocks from Marp files

What this means: The tool extracts the content structure (headings, bullets, text) from your Marp markdown but ignores Marp theme styling. Instead, it creates a generic PowerPoint file that you can theme using PowerPoint's built-in themes.

Workflow:

Marp Markdown (any theme) → Generic PowerPoint → Apply PowerPoint Theme

Workaround: Use the color options to customize the base colors:

marp2pptx slides.md --primary-color "#3498DB" --accent-color "#E74C3C"

Planned for future versions:

• 🔮 Marp theme parsing (local and remote)
• 🔮 Automatic color extraction from Marp themes
• 🔮 Font mapping from Marp to PowerPoint

Note: Even without Marp theme support, the generated PowerPoint files are fully editable and theme-compatible. You can apply any PowerPoint theme and all slides will adapt automatically.

🚀 Quick Start

Installation

# Install dependencies
npm install

# Or install globally (optional)
npm link

Usage

# Basic usage
node bin/marp2pptx.js input.md

# Specify output file
node bin/marp2pptx.js input.md -o presentation.pptx

# Custom colors
node bin/marp2pptx.js input.md --primary-color "#3498DB" --accent-color "#E74C3C"

# If installed globally
marp2pptx input.md -o output.pptx

📖 CLI Options

Usage: marp2pptx [options] <input>

Arguments:
  input                          Input Marp markdown file

Options:
  -V, --version                  Output version number
  -o, --output <file>            Output PowerPoint file (default: "output.pptx")
  --primary-color <color>        Primary color for headings (default: "#E67E22")
  --accent-color <color>         Accent color (default: "#16A085")
  --bg-color <color>             Background color (default: "#FFFFFF")
  --text-color <color>           Text color (default: "#2C3E50")
  -q, --quiet                    Suppress output messages
  -h, --help                     Display help

📝 Supported Markdown Features

Headings

# Heading 1
## Heading 2
### Heading 3

Lists

- Bullet point 1
- Bullet point 2

1. Numbered item 1
2. Numbered item 2

Formatting

**Bold text**
*Italic text*
`Inline code`

Code Blocks

```python
def hello():
    print("Hello World!")
```

Blockquotes

> This is a quoted text

Marp Directives

<!-- _class: lead -->
<!-- _header: "Section Title" -->
<!-- _paginate: false -->

🎨 How to Apply Themes

• Open the generated PowerPoint file
• Go to Design tab
• Click any theme in the Themes gallery
• All slides automatically adapt!

Recommended themes:

• Ion (modern)
• Organic (nature-inspired)
• Facet (contemporary)
• Basis (professional)

📦 Project Structure

marp2pptx-js/
├── package.json           # Dependencies and scripts
├── bin/
│   └── marp2pptx.js      # CLI entry point
├── lib/
│   ├── index.js          # Main library
│   ├── parser.js         # Marp markdown parser
│   ├── converter.js      # Markdown to HTML converter
│   └── generator.js      # PPTX generation with placeholders
├── test/
│   ├── sample.md         # Test file
│   └── output.pptx       # Generated output
└── README.md

🔧 How It Works

Marp Markdown
      ↓
   Parser
   (Splits slides, extracts directives)
      ↓
   Converter
   (Markdown → HTML)
      ↓
   Generator
   (HTML → PPTX with placeholders)
      ↓
Theme-Compatible PowerPoint

🎯 Technical Details

Dependencies

• pptxgenjs (^3.12.0) - PowerPoint generation
• jsdom (^23.0.0) - HTML parsing
• marked (^11.0.0) - Markdown parsing
• commander (^11.1.0) - CLI framework
• chalk (^4.1.2) - Colored console output

Architecture

The converter uses a three-stage pipeline:

• Parser (lib/parser.js)

  • Removes YAML frontmatter and style tags
  • Splits content by --- separator
  • Extracts Marp directives from HTML comments
  • Returns array of slide objects with metadata

• Converter (lib/converter.js)

  • Uses marked library to parse markdown
  • Converts to structured HTML elements
  • Applies custom styling with CSS
  • Handles inline formatting

• Generator (lib/generator.js)

  • Parses HTML with jsdom
  • Creates PowerPoint with master layouts
  • Uses placeholder-based approach
  • Generates theme-compatible PPTX

Why Placeholders Matter

Instead of absolute positioning, this tool uses PowerPoint's placeholder system:

slide.addText(title, {
  placeholder: 'title',  // ← Uses PowerPoint's title placeholder
  fontSize: 44,
  bold: true
});

slide.addText(content, {
  placeholder: 'body',   // ← Uses PowerPoint's body placeholder
  fontSize: 18
});

Benefits:

• ✅ Themes can override placeholder positions
• ✅ Themes can change fonts and colors
• ✅ Content automatically reflows
• ✅ Professional, theme-compatible output

📊 Comparison with Previous Versions

Feature	Python + JS	Pure JavaScript
Languages	2 (Python, JS)	1 (JavaScript)
Installation	pip + npm	npm only
Commands	2 steps	1 command
Output Quality	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Theme Support	✅	✅
Editability	✅	✅
Speed	Fast	Very Fast
Maintenance	Medium	Easy
Code Size	~740 lines	~400 lines

🧪 Testing

# Test with sample file
node bin/marp2pptx.js test/sample.md -o test/output.pptx

# Check output
open test/output.pptx

Expected Results:

• 7 slides generated
• 0 errors
• File size: ~85-90 KB
• All slides editable
• Theme-compatible

📝 Example Input/Output

Input (sample.md)

---
marp: true
---

<!-- _class: lead -->
# My Presentation
## Subtitle Here

---

## Slide Title

- Point 1
- Point 2
- Point 3

Output

• Slide 1: Title slide (centered, uses title/subtitle placeholders)
• Slide 2: Content slide (left-aligned, uses title/body placeholders)
• Both slides: Fully editable, theme-compatible

🚢 Deployment

Global Installation

npm link

# Now use anywhere
marp2pptx ~/Documents/presentation.md

Publish to npm

npm publish

# Users install with
npm install -g marp2pptx

CI/CD Integration

# GitHub Actions
- name: Convert Marp to PowerPoint
  run: |
    npm install -g pptxgenjs jsdom marked commander chalk
    node bin/marp2pptx.js slides.md -o output.pptx

- name: Upload Artifact
  uses: actions/upload-artifact@v3
  with:
    name: presentation
    path: output.pptx

💡 Tips

Best Practices

• Keep slides simple - 5-7 bullets maximum
• Use standard markdown - Avoid complex HTML
• Test with themes - Try different themes to see what works best
• Version control - Keep your Marp files in git

Customization

Want different colors? Edit lib/generator.js:

const COLORS = {
  primary: 'E67E22',    // Change heading color
  accent: '16A085',     // Change accent color
  text: '2C3E50',       // Change text color
  // ...
};

Debugging

Enable debug mode:

DEBUG=true node bin/marp2pptx.js input.md

🆚 vs. Marp CLI

Feature	marp2pptx (this tool)	Marp CLI
Installation	npm install	npm install
Command	marp2pptx file.md	marp file.md --pptx
Theme Compat	✅ Guaranteed	❓ Unknown
Editability	✅ Placeholders	❓ Unknown
Customization	✅ Full control	⚠️ Limited
Dependencies	jsdom, pptxgenjs, marked	Browser (Chromium)
Speed	⚡ Very Fast	⚠️ Slower (browser)

🤝 Contributing

Found a bug? Have a feature request?

• Fork the repository
• Create a feature branch
• Make your changes
• Test thoroughly
• Submit a pull request

📄 License

MIT - Free for commercial and personal use

🙏 Credits

• Marp - Markdown presentation ecosystem
• PptxGenJS - PowerPoint generation library
• marked - Markdown parser
• jsdom - DOM implementation for Node.js

Made with ❤️ for the Marp community

Need help? Open an issue!