md-slides
Converts 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 / space / PgDn / PgUp / Home / End / P / Esc keyboard navigation, presenter mode (split view with current slide + speaker notes + clock + next-slide preview), URL-hash deep linking, and `@media print` page-per-slide for PDF export. Triggers when the markdown-html-orchestrator classifies an input as SLIDES, or when invoked directly via /cs:md-slides. Reuses md-document's markdown parser for slide-body rendering and reads design-system tokens via config_loader.py. Refuses if input has no clear slide boundaries, produces a 1-slide deck, or `--strict-notes` is on with < 50% notes coverage. Use after orchestrator routing.
- License 许可
- MIT
- 最近更新
- 2026-10-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- md-slides
- tags
- [ "markdown", "html", "slides", "deck", "presenter-mode", "keyboard-nav", "print-to-pdf", "single-file", "design-system" ]
- author
- Alireza Rezvani
- license
- MIT
- version
- 2.10.3
- description
- Converts 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 / space / PgDn / PgUp / Home / End / P / Esc keyboard navigation, presenter mode (split view with current slide + speaker notes + clock + next-slide preview), URL-hash deep linking, and `@media print` page-per-slide for PDF export. Triggers when the markdown-html-orchestrator classifies an input as SLIDES, or when invoked directly via /cs:md-slides. Reuses md-document's markdown parser for slide-body rendering and reads design-system tokens via config_loader.py. Refuses if input has no clear slide boundaries, produces a 1-slide deck, or `--strict-notes` is on with < 50% notes coverage. Use after orchestrator routing.
- compatible_tools
- [ "claude-code", "codex-cli", "cursor", "antigravity", "opencode", "gemini-cli" ]
02 资源文件 7
- 资产文件assets/md_slides_template.html4.8 KB
- 参考文档references/keyboard_nav_patterns.md4.6 KB
- 参考文档references/presentation_ux.md5.1 KB
- 参考文档references/single_file_deck_conventions.md5.1 KB
- 脚本scripts/deck_html_renderer.py20.4 KB
- 脚本scripts/presenter_notes_parser.py3.9 KB
- 脚本scripts/slide_splitter.py9.9 KB
03 SKILL.md 正文
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
| Symptom | Action |
|---|---|
markdown-html-orchestrator routes input as SLIDES |
Invoke this skill |
User runs /cs:md-slides <path>.md directly |
Invoke this skill |
Input has 3+ --- HR lines OR 5+ H1 headings with short bodies |
Invoke this skill |
| Input is a long-form spec | Route to md-document instead |
| Input is a code review | Route to md-review instead |
| Input has no clear slide boundaries | Refuse, route to md-document |
| Input would produce 1 slide | Refuse (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/PgDnadvance;←/PgUpprevious;Home/Endjump;Ppresenter mode;Escexits presenter - URL-hash deep linking —
#3jumps to slide 3; browser back/forward walks slides; sharedeck.html#5to 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+Pproduces 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
- Refuses input with no clear slide boundaries. Auto mode needs ≥ 3 HR lines or ≥ 5 H1 headings. Otherwise exit 6 — route to md-document.
- Refuses 1-slide decks. That's a poster, not a deck. Exit 5.
- Refuses input < 100 lines. Same Shihipar threshold as all converters.
- Refuses without onboarding. Same gate as every converter.
--strict-notesrefuses < 50% notes coverage. A deck where most slides have no notes isn't set up for presenter mode. Exit 7.- Soft-warns slides > 40 source lines. Signal-to-noise; renders anyway but surfaces the count.
- Single-file output. All CSS + JS inline. Only external is Google Fonts CSS. Prism.js is opt-in via
--syntax. - No JS framework runtime. Vanilla JS + keyboard event handlers, no React/Vue/Svelte.
Forcing-question library (Matt Pocock grill discipline)
- 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.
- HR (
---) or H1 boundaries? Recommended: HR for typical decks; H1 for outline-driven decks. Canon: Marp / reveal.js / pandoc convergence. - 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.
- Is there any slide over 40 source lines? Recommended: split it. Canon: NN/g — audience attention drops past ~6 bullets / 200 words.
- Is
--syntaxneeded? 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)
04 同仓库更多 Skills
internal-comms
A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.).
eu-ai-act-reviewer
Review user journeys, public content, and codebases for potentially relevant EU AI Act provisions, with exact official citations, evidence gaps, application dates, and plain-language next actions. Use for EU AI Act issue-spotting, not final legal or compliance decisions.
discernment-nudge
After you give a substantive answer or draft that the user may act on — advice or recommendations, drafted artifacts such as goals, plans, pitches, proposals, or emails, estimates or projections, analysis or interpretation of data, factual claims they may rely on, or a multi-step argument — invoke this skill BEFORE finalizing your reply and then, if it applies, append 2-3 short follow-up questions, each tied to something specific in what you just produced, that help the user check key facts, probe the reasoning or assumptions, and notice missing context. Do this at most once per conversation. Skip it when the user asked a trivial how-to or simple lookup, wants a purely educational explanation, asked you only to format, convert, or assemble a file from content they provided, is writing code they will run, is doing creative writing or casual chat, or already asked you to double-check, cite, or review — the skill file explains these boundaries and the exact output format.
academy-guide
Stop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.
webapp-testing
Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
web-artifacts-builder
Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.