Skip to content

alirezarezvani/claude-skills / markdown-html/skills/md-slides

md-slides

Verified

Turn a markdown file into a single-file HTML slide deck with keyboard navigation, presenter notes and print-to-PDF. Use whenever the user wants slides or a presentation from markdown or notes.

md-slides — Markdown deck → single-file HTML presentation

The slide-deck converter. Reads a markdown deck (HR or H1 boundaries, optional presenter notes), emits a single-file HTML presentation that runs in any browser with keyboard navigation, presenter mode, and print-to-PDF.

Three stdlib tools pipeline together:

slide_splitter.py  →  presenter_notes_parser.py  →  deck_html_renderer.py
   (md → ordered      (extract <!-- notes:         (slides + design-system
    slides with       --> blocks, attach            tokens → single-file
    titles)           per slide)                    HTML with keyboard nav)

When to invoke

SymptomAction
markdown-html-orchestrator routes input as SLIDESInvoke this skill
User runs /cs-md-slides <path>.md directlyInvoke this skill
Input has 3+ --- HR lines OR 5+ H1 headings with short bodiesInvoke this skill
Input is a long-form specRoute to md-document instead
Input is a code reviewRoute to md-review instead
Input has no clear slide boundariesRefuse, route to md-document
Input would produce 1 slideRefuse (it's a poster)

Pipeline

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

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

# 3. Render single-file HTML deck
python3 markdown-html/skills/md-slides/scripts/deck_html_renderer.py \
    --slides /tmp/deck.json --title "My Talk" --output deck.html

What ships in the HTML

  • All slides as <section class="slide"> — one visible at a time, controlled by JS
  • Keyboard nav — → / Space / PgDn advance; ← / PgUp previous; Home/End jump; P presenter mode; Esc exits presenter
  • URL-hash deep linking — #3 jumps to slide 3; browser back/forward walks slides; share deck.html#5 to send someone directly there
  • Progress bar — 3px at top showing position through the deck
  • Slide counter — bottom-right ("3 / 12")
  • Presenter mode (P key) — splits the window: current slide on left (60% width), panel on right with clock + speaker notes + next-slide preview
  • Print stylesheet — Cmd+P produces a PDF with one slide per page
  • @media (prefers-reduced-motion: reduce) honored
  • 12 brand CSS custom properties from design-system; design_style affects layout density
  • Reuses md-document's markdown parser — slide bodies render with consistent paragraph/list/code/table/callout handling

Hard rules

  1. Refuses input with no clear slide boundaries. Auto mode needs ≥ 3 HR lines or ≥ 5 H1 headings. Otherwise exit 6 — route to md-document.
  2. Refuses 1-slide decks. That's a poster, not a deck. Exit 5.
  3. Refuses input < 100 lines. Same Shihipar threshold as all converters.
  4. Refuses without onboarding. Same gate as every converter.
  5. --strict-notes refuses < 50% notes coverage. A deck where most slides have no notes isn't set up for presenter mode. Exit 7.
  6. Soft-warns slides > 40 source lines. Signal-to-noise; renders anyway but surfaces the count.
  7. Single-file output. All CSS + JS inline. Only external is Google Fonts CSS. Prism.js is opt-in via --syntax.
  8. No JS framework runtime. Vanilla JS + keyboard event handlers, no React/Vue/Svelte.

Forcing-question library (Matt Pocock grill discipline)

  1. Is this actually a deck, or a long document? Recommended: if you can't draw clear slide boundaries, it's not a deck. Canon: Tufte Cognitive Style of PowerPoint.
  2. HR (---) or H1 boundaries? Recommended: HR for typical decks; H1 for outline-driven decks. Canon: Marp / reveal.js / pandoc convergence.
  3. Will it be presented live or distributed for self-paced reading? Recommended: live → need presenter notes; self-paced → notes optional. Canon: Weinschenk 100 Things Every Presenter Needs to Know.
  4. Is there any slide over 40 source lines? Recommended: split it. Canon: NN/g — audience attention drops past ~6 bullets / 200 words.
  5. Is --syntax needed? Recommended: only for decks with substantial code blocks. Default off. Canon: single-file shareability discipline.

Distinct from

  • md-document — that's one continuous document. This is N discrete slides.
  • md-review — that renders diff hunks + annotations. This renders prose slides.
  • marketing/landing/ — that's a landing page, not a deck.
  • Keynote / PowerPoint — those are graphic-design tools. This is for markdown-authored decks projected from a browser.

Output artifact

{default_output_dir}/deck-{slug}.html (path resolved by orchestrator's output_path_resolver.py; collision suffix -2, -3, … by default).

References

  • Shihipar — Claude Code HTML output (Medium, 2026), Tier 3 use case "Slide Decks"
  • Reynolds — Presentation Zen (less is more discipline)
  • Atkinson — Beyond Bullet Points (the bullet-heavy failure mode)
  • Tufte — The Cognitive Style of PowerPoint (the polemic)
  • reveal.js / Big / Marp — convergent markdown-to-deck conventions
  • See references/ for full citations (presentation_ux, keyboard_nav_patterns, single_file_deck_conventions)
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 197kUpdated Claude CodeCodexVerifiedInstall