mdslides

Markdown presentations for humans and AI agents. One markdown file per deck, a web app editor with a live preview, and a CLI + JSON API so any agent can create, edit and export decks programmatically.

Zero runtime dependencies — just Node.js (>= 16).

Documentation

• AGENTS.md — orientation for AI agents working in this repo
• docs/format.md — the presentation markdown format
• docs/cli.md — CLI reference & agent recipes
• docs/api.md — REST API reference
• docs/architecture.md — internals & contributing

Quick start

node server.js                # web app at http://localhost:4210
# or, from this repo root:
npm run start

Create and present a deck from the terminal:

node bin/mdslides.js new my-deck --topic "Redis at scale" --theme dark
node bin/mdslides.js render my-deck -o my-deck.html    # self-contained HTML
node bin/mdslides.js pdf my-deck -o my-deck.pdf        # print page / PDF
node bin/mdslides.js serve                             # open the web app

The markdown format

One slide per --- separator. Optional front matter at the very top:

---
title: "My deck"
theme: dark            # 16 built-in themes
author: "Ada"
---

# Slide one

- Bullet
- Another {reveal}

<!-- note: speaker notes, shown with the N key -->

---

## Side-by-side columns

:::columns
## Left
- one
- two

## Right
- three
:::

---

```js
console.log("highlighted code")
```

---

$$
\int_0^1 x^2 \, dx = \frac{1}{3}
$$

---

```mermaid
flowchart LR
  A --> B
```

---

## Image layout

![Diagram](diagram.png "right opacity:0.7")

Features: speaker notes (<!-- note: ... -->), syntax-highlighted code, side-by-side :::columns blocks, 16 themes, KaTeX math ($...$ / $$...$$), Mermaid diagrams ( ```mermaid fences), incremental reveals ({reveal}), image layout directives ("right", "left", "bg" with opacity:0.7), tables, images, quotes, and HTML everywhere markdown allows it. Front matter (title, subtitle, author, date) drives a styled title slide; omit title and your first slide renders verbatim instead. Separator lines and note markers inside fenced code blocks are never treated as slide boundaries. Export is a single self-contained .html (no network needed at present time) with arrow keys, fullscreen (F), overview grid (O), speaker notes (N), laser pointer (L), draw-on-slide pen (D), blank canvas (C), black-out (B), progress bar, presenter fragment stepping, and PDF-friendly print styles.

For AI agents

The CLI speaks two dialects: human-friendly logs and --json machine output.

# Skeleton from a topic + outline
mdslides new deck-name --topic "Subject" --slides "Intro,Motivation,Design,Demo,Next" --theme dark --json

# Provide the whole markdown directly (stdin)
printf '%s' '---\ntitle: "X"\n---\n\n# X\n\n---\n\n## Notes\n' | mdslides new deck-name --json

# Render / PDF
mdslides render deck-name -o out.html --json
mdslides pdf deck-name -o out.pdf --json

# Inspect
mdslides list --json
mdslides show deck-name

--json returns objects like:

{ "ok": true, "action": "new", "name": "deck-name",
  "path": "/abs/path/decks/deck-name.md", "slides": 5 }

Generate a deck with your own LLM

Set MDSLIDES_LLM to any command-line model that reads a prompt on stdin and prints markdown on stdout, then add --llm:

export MDSLIDES_LLM="claude -p --output-format text"        # example
mdslides new q3-review --topic "Q3 review" --slides "Wins,Misses,Next" --llm --json

REST API

Method	Path	Body / query	Purpose
GET	/api/decks	—	list deck names
POST	/api/decks	{name, content?}	create deck (from content or a skeleton)
GET	/api/decks/:name	—	get deck markdown
PUT	/api/decks/:name	{content}	save deck
DELETE	/api/decks/:name	—	delete deck
POST	/api/generate	{topic, slides[], theme}	generate skeleton markdown
POST	/api/render	{markdown, theme?}	render slides for embedding
GET	/api/export/:name?format=html|pdf	—	self-contained HTML / print page

Example (an agent creating + exporting a deck):

curl -s localhost:4210/api/decks/welcome            # read the sample deck
curl -s localhost:4210/api/export/welcome          # full HTML

CLI reference

mdslides new <name> [--topic T] [--slides "a,b,c"] [--theme X] [--llm] [--json]
mdslides list [--json]
mdslides show <name>
mdslides render <name|file.md|-> [-o out.html] [--theme X] [--json]
mdslides pdf  <name|file.md|-> [-o out.pdf] [--json]
mdslides lint <name|file.md|-> [--json]
mdslides themes [--json]
mdslides serve [--port N]
mdslides open <name>

- reads markdown from stdin. pdf writes a print-ready page and, when a headless Chrome/Chromium is on PATH (or CHROME_BIN is set), the actual PDF. lint checks a deck for structural problems (exit code 1 on errors). themes lists the 16 built-in themes.

Project layout

bin/mdslides.js     CLI
server.js           HTTP server (web app + JSON API)
lib/                renderer, themes, exporter, generator
public/             web app (editor + preview)
decks/*.md          your presentations
docs/               guides: format, CLI, API, architecture
AGENTS.md           orientation for AI agents working in this repo

Deck files live in decks/ and are plain markdown — edit them with any tool. To use a different deck directory, change DECKS in server.js or run the CLI from a location where decks/ sits next to bin/.

Tests

npm test

Covers the markdown parser, columns/notes extraction, HTML export, the HTTP API and the CLI.

License

GNU General Public License v2.0 — Copyright (C) 2026 Sameer Somnath Sangle.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License. See the LICENSE file for details.