Every feature is demonstrated by using it. Two-column slides show the Markdown on the left and what it produces on the right.

Try it lines are things to do right now, on this deck. If one doesn't work, that's a bug: this deck is MD-Slides' tutorial and its acceptance test.

Slide separators (---) can't appear as bare lines inside code blocks, so the examples show slide bodies only. Open feature-tour.md for the full format.

Eight sections: Templates · Content · Speaker view · Navigation · Any screen · CLI · Themes · Validation

Three slots: H1 title (required, ≤ 2 lines), H2 subtitle (optional, ≤ 2 lines), **Author** (optional, ≤ 80 chars).

# Main Title
## Optional subtitle
**Optional author**

title is the only template that uses H1. All other templates use H2. The first slide of this deck uses the title template.

The content template is the workhorse — most slides use it. Two slots:

## Slide Heading

Body: markdown, lists, code blocks, images, tables.

Heading: required, ≤ 80 chars. Body: ≤ 12 lines and ≤ 150 words. Validation reports all violations together — you fix everything in one pass, not one at a time.

Split a slide into two independent columns using the ---column--- delimiter:

template: two-column
## Heading
Left column content here.
---column---
Right column content here.

Each column: ≤ 10 lines, ≤ 75 words. The ---column--- delimiter must be on its own line. The next slide demonstrates a live two-column layout.

The diagram template renders Mermaid charts to SVG at build time — requires mmdc installed.

template: diagram
caption: Optional caption
## Slide heading
```mermaid
graph LR
    A[Input] --> B[Output]
```

Flowcharts, sequence, class, Gantt, pie, ER, and state diagrams are supported. The next slide is a live diagram slide.

Every slide opens with a frontmatter block between --- markers. Supported keys:

Fenced code blocks with a language name get full syntax highlighting:

case class Slide(id: SlideId, template: Template, slots: Map[SlotName, SlotContent])

object SlideDeck:
  def validated(slides: List[Slide]): Either[NonEmptyList[ValidationError], SlideDeck] =
    Either.cond(
      slides.nonEmpty,
      SlideDeck(slides),
      NonEmptyList.one(ValidationError("Empty deck"))
    )

190+ languages via highlight.js. Specify the language immediately after the opening fence: ```scala .

def spell(n: Int): String = n match
    case  0 => "zero"
    case  1 => "one"
    case  2 => "two"
    case  3 => "three"
    case  4 => "four"
    case  5 => "five"
    case  6 => "six"
    case  7 => "seven"
    case  8 => "eight"
    case  9 => "nine"
    case 10 => "ten"
    case 11 => "eleven"
    case 12 => "twelve"
    case 13 => "thirteen"
    case 14 => "fourteen"
    case 15 => "fifteen"
    case 16 => "sixteen"
    case 17 => "seventeen"
    case 18 => "eighteen"
    case 19 => "nineteen"
    case 20 => "twenty"
    case _  => n.toString

Code blocks over 20 lines shrink to fit, and don't count against the 12-line body limit.

The diagonal stripes behind this slide come from its frontmatter. In your own deck you'd write:

template: content
background: images/stripes.png

background: takes an image path (copied into the output) or a data: URL, as here, which keeps the tour a single file. It overrides the theme background for this slide only. PNG, JPEG, SVG and WebP all work.

The speaker window shows the slide counter with ‹ › buttons, the elapsed timer, your notes, and the next slide's heading. On a phone it becomes one column.

The two windows stay in step: move in either one and the other follows (same browser, same device).

Timer: T pauses or resumes, R resets. {{timer}} in a header or footer shows it on slides.

Try it: press S, then change slides in either window.

Clickers just work. On a phone or tablet, swipe, tap, or use the ‹ › buttons.

Break mode (B): hides the slides and pauses the timer. Press B again to resume. Set a custom image with --break-screen or breakScreen in your config.

Goto (G): type a slide number and press Enter, or pick a slide from the list. On a touch screen, tap the slide counter.

History (P / N): back and forward through the slides you actually visited.

Try it: press G, type 3, press Enter, then press P to come back here.

This table is wider than a phone screen. The slide shrinks to fit, and the table re-wraps rather than overflowing.

Try it: rotate your phone, or resize this window. The slide re-fits.

The address bar tracks the current slide as #N. Reloading keeps your place, and a link can open any slide:

https://www.tjm.solutions/mdslides/demo/#12

Changing slides doesn't add browser history, so Back (or a phone's back gesture) leaves the deck rather than stepping through it. Use P and N for slide history.

Try it: look at the address bar, then reload. You stay on this slide.

Custom themes are folders: themes/mytheme/theme.json, used as --theme mytheme.

java -jar md-slides.jar config

Global Configuration:
  Location: ~/.mdslides/config.json
  Settings:
    defaults.theme: light
Project Configuration:
  Location: .mdslides/config.json
  Settings:
    theme: dark

Shows which settings are in effect and which file each came from.

java -jar md-slides.jar my-talk

1. If a saved session log exists, shows its report
2. Renders if my-talk.md changed since the last render
3. Opens the presentation in your browser

display my-talk just opens it; render my-talk just renders.

java -jar md-slides.jar render my-talk --theme light  # default
java -jar md-slides.jar render my-talk --theme dark

light — white background, dark text. dark — dark background, light text, teal accents. corporate — a neutral business look.

All pass WCAG 2.1 AA contrast. This deck's live demo uses dark.

In themes/mytheme/theme.json:

"background": { "color": "#1e1e1e", "image": "images/deck-bg.jpg" },
"templateBackgrounds": { "section-title": "images/section.png" }

Theme image paths are relative to the theme folder, and are copied into your output.

Priority: per-slide background: > templateBackgrounds > deck background.

This slide's frontmatter:

header: Feature Tour — Slide {{pageNumber}} of {{totalPages}}
footer: {{title}} · {{date}} · {{timer}}

Tokens: {{pageNumber}} {{totalPages}} {{timer}} {{title}} (the deck title) {{date}} (today).

Try it: check the header and footer on this slide. The timer ticks.

Content position per slide via frontmatter:

template: content
vertical-align: top

Three options: top · center (default) · bottom

Useful for sparse slides where centered text looks visually unbalanced, or for slides with code blocks that benefit from a predictable top position.

Highest wins: CLI flags > project .mdslides/config.json > global ~/.mdslides/config.json > defaults

{ "theme": "dark", "outputDir": "dist", "breakScreen": "images/break.png" }

{ "defaults": { "theme": "light" }, "paths": { "themesDir": "~/themes" } }

The first is a project config; the second a global one, where settings go under defaults.

Errors (the render stops): missing required slots, unknown templates, a two-column slide without exactly one ---column---, images without alt text, image files that don't exist.

Warnings (the render continues): headings over 80 characters, bodies over 12 lines or 150 words, columns over 10 lines or 75 words, theme colours below WCAG 2.1 AA contrast.

✗ Validation failed with 4 problem(s):
  - Slide 3: Structure Error - Required slot 'heading' is missing
  - Slide 3: Structure Error - Required slot 'body' is missing
  - Slide 4: Unknown template 'bogus'. Valid templates: title, content, diagram, closing, section-title, two-column
  - Slide 5: image file 'images/lamp.png' does not exist (looked for images/lamp.png)

✓ Validation passed with 1 warning(s):
  - Slide 2: Density Warning in 'body' slot - Content exceeds
    recommended line limit (actual: 17, guidance: 12 lines)

Validation reports every problem on every slide in one pass, before anything is written, so you fix them all at once. An image without alt text is reported by name: ![what it shows](photo.png).