---
description: Convert a markdown deck (slides separated by --- HR boundaries or by # H1 headings, with optional <!-- notes: ... --> presenter notes blocks) into a single-file HTML presentation with arrow-key navigation, presenter mode (split view with current slide + notes + clock + next-slide preview), URL-hash deep linking, and @media print page-per-slide for PDF export. Refuses 1-slide decks (it's a poster) or inputs without clear boundaries. Single-file output; Google Fonts CSS is the only external (Prism is opt-in via --syntax).
argument-hint: "<path to markdown deck> [--boundary auto|hr|h1] [--title \"My Talk\"] [--syntax] [--strict-notes]"
---

# /cs:md-slides — Markdown deck → single-file HTML presentation

Convert the markdown deck at **$ARGUMENTS** into a single-file interactive HTML presentation.

## Pre-flight gates (refuse, never override)

1. **Input < 100 lines** → refuse (markdown wins below Shihipar's threshold).
2. **Design-system not onboarded** → refuse, surface `/cs:design-system`.
3. **No clear slide boundaries** (auto mode: need ≥ 3 HR or ≥ 5 H1) → refuse, route to md-document.
4. **1-slide deck** → refuse (it's a poster, not a deck).
5. **`--strict-notes` with < 50% notes coverage** → refuse.
6. **Output directory unwritable** → refuse, ask user for `--out`.

## Pipeline

```bash
# 1. Resolve output path (doctype=slides → deck- prefix)
python3 markdown-html/skills/markdown-html-orchestrator/scripts/output_path_resolver.py \
    --input "<path>.md" --doctype slides

# 2. Split slides on --- HR or H1 (auto-detect)
python3 markdown-html/skills/md-slides/scripts/slide_splitter.py \
    --input "<path>.md" --boundary auto --output /tmp/slides.json

# 3. Extract <!-- notes: ... --> blocks per slide
python3 markdown-html/skills/md-slides/scripts/presenter_notes_parser.py \
    --slides /tmp/slides.json --output /tmp/deck.json

# 4. Render single-file HTML deck
python3 markdown-html/skills/md-slides/scripts/deck_html_renderer.py \
    --slides /tmp/deck.json --title "<deck title>" \
    --output <resolved-out>.html
```

## What ships in the HTML

- **All slides as `<section class="slide">`** with one visible at a time (CSS-controlled, no JS-required content)
- **Keyboard navigation**:
  - `→` / `Space` / `PgDn` → next slide
  - `←` / `PgUp` → previous slide
  - `Home` / `End` → first / last slide
  - `P` → toggle presenter mode
  - `Esc` → exit presenter mode
- **Presenter mode** — split view: current slide (60% width) + panel (40% width with clock + speaker notes + next-slide preview)
- **URL-hash deep linking** — `#3` jumps to slide 3; back/forward walks slides; share `deck.html#5` to land on slide 5
- **Progress bar** at top (3px); slide counter in bottom-right
- **Print-to-PDF** via browser's native print dialog: `@media print` makes each slide one page (`Cmd+P` / `Ctrl+P`)
- **`prefers-reduced-motion`** honored
- **12 brand CSS tokens** from design-system; design_style affects layout density

## Hard rules

- Output is one `.html` file. No multi-file output.
- External CDN: `fonts.googleapis.com` always; `cdn.jsdelivr.net` (Prism) only when `--syntax` is passed.
- No JS framework runtime. Vanilla JS + keyboard event handlers.
- Re-running on the same input writes `deck-{slug}-2.html` etc.

## Useful flags

- `--boundary {auto,hr,h1}` — slide boundary mode (default: auto)
- `--title "My Talk"` — sets the `<title>` and tab name
- `--syntax` — enable Prism.js CDN for code blocks (off by default; decks rarely need it)
- `--strict-notes` — refuse if < 50% of slides have presenter notes (use when presenter mode is essential)

## Output

Returns: slide count, notes coverage %, output path, design style applied, top features used, one forcing question.

## References

See `markdown-html/skills/md-slides/references/`:
- `presentation_ux.md` — Atkinson + Reynolds + Tufte + NN/g + Weinschenk + Marp/reveal.js/Big convergence
- `keyboard_nav_patterns.md` — reveal.js / Big / Spectacle keymap + WCAG 2.1.1 + 2.4.3 + MDN KeyboardEvent
- `single_file_deck_conventions.md` — Big + Marp + Pandoc + WCAG 2.3.3 + @media print