marp2pptx/README.md

Convert Marp markdown presentations to theme-compatible, editable PowerPoint files. Single command, zero Python dependencies, fully editable output.

# 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:
```bash
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

```bash
# Install dependencies
npm install

# Or install globally (optional)
npm link
```

### Usage

```bash
# 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
```markdown
# Heading 1
## Heading 2
### Heading 3
```

### Lists
```markdown
- Bullet point 1
- Bullet point 2

1. Numbered item 1
2. Numbered item 2
```

### Formatting
```markdown
**Bold text**
*Italic text*
`Inline code`
```

### Code Blocks
````markdown
```python
def hello():
    print("Hello World!")
```
````

### Blockquotes
```markdown
> This is a quoted text
```

### Marp Directives
```markdown
<!-- _class: lead -->
<!-- _header: "Section Title" -->
<!-- _paginate: false -->
```

## 🎨 How to Apply Themes

1. Open the generated PowerPoint file
2. Go to **Design** tab
3. Click any theme in the **Themes** gallery
4. 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:

1. **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

2. **Converter** (`lib/converter.js`)
   - Uses `marked` library to parse markdown
   - Converts to structured HTML elements
   - Applies custom styling with CSS
   - Handles inline formatting

3. **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**:

```javascript
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

```bash
# 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)
```markdown
---
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

```bash
npm link

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

### Publish to npm

```bash
npm publish

# Users install with
npm install -g marp2pptx
```

### CI/CD Integration

```yaml
# 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

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

### Customization

Want different colors? Edit `lib/generator.js`:

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

### Debugging

Enable debug mode:

```bash
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?

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. 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!