md-slides 📽️

md-slides is a simple yet powerful Markdown-to-HTML presentation tool — like slidev-lite. Write your slides in Markdown, separate them with ---, and get a single self-contained HTML file with a dark theme, smooth transitions, keyboard navigation, and touch support.

✨ Part of the SCL339 open-source ecosystem.

Features ✨

• Zero config — Write Markdown, get a beautiful HTML presentation
• Single HTML file — Self-contained, no external dependencies or internet needed
• Dark theme — Modern, easy-on-the-eyes dark design
• Slide transitions — Smooth fade + slide-up effect
• Keyboard navigation — Arrow keys, Space, Home/End
• Touch support — Swipe left/right on mobile
• Fullscreen mode — Press f to go fullscreen
• Progress bar — Visual indicator of your progress
• Slide counter — Current slide / total slides
• Watch mode — Auto-rebuild on file changes (--watch)
• Custom templates — Bring your own HTML template (--template)

Installation 📦

# Run directly (no install needed)
npx md-slides presentation.md

# Or install globally
npm install -g md-slides
md-slides presentation.md

Usage 🚀

Quick Start

Create a file presentation.md:

# My Awesome Talk

A short intro

---

## Slide 2

- Point one
- Point two
- Point three

---

## Code Example

```python
def hello():
    print("Hello from md-slides!")

`

Thanks!

Questions?

Then run:

```bash
npx md-slides presentation.md

This generates presentation.html — open it in any browser.

CLI Options

md-slides <input.md> [options]

Options:
  -o, --output <file>   Output HTML file (default: <input>.html)
  -t, --template <file> Custom HTML template
  -w, --watch           Watch for changes and rebuild
  -h, --help            Show this help

Examples

# Basic usage
md-slides talk.md

# Custom output path
md-slides deck.md -o index.html

# Watch mode (auto-rebuild on save)
md-slides presentation.md --watch

# Custom template
md-slides slides.md -t my-template.html

Slide Separator 📄

Use --- on its own line to separate slides:

# Slide 1
Content here

---

# Slide 2
More content

---

# Slide 3
Final slide

Keyboard Shortcuts ⌨️

| Key | Action | |-----|--------| | → / ↓ / Space | Next slide | | ← / ↑ | Previous slide | | Home | First slide | | End | Last slide | | f | Toggle fullscreen |

Custom Templates 🎨

Create your own HTML template with these placeholders:

• {{TITLE}} — Presentation title (extracted from first slide)
• {{SLIDES}} — All slide HTML content
• {{SLIDE_COUNT}} — Total number of slides

md-slides deck.md -t my-theme.html

Why md-slides? 🤔

• Lightweight — No build tools, no npm run scripts, no webpack
• Portable — Single HTML file you can email, host on GitHub Pages, or open locally
• Focus on content — Write Markdown, get a presentation. That's it.
• Beautiful defaults — Dark theme looks great without any configuration

Example Output

Open the generated HTML in any browser:

Related Projects 🔗

Check out other SCL339 tools:

• auto-changelog-action — Auto-generate CHANGELOG from PR titles/labels
• pr-labeler-action — Auto-label PRs based on changed file paths

Development 🛠️

git clone https://github.com/SCL339/md-slides.git
cd md-slides
npm install
node index.js example.md -o example.html

License 📄

MIT — see LICENSE for details.