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-08-25
- 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" ]
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
webmcpify
Make a web app agent-ready — propose a WebMCP tool manifest, integrate, verify in a real browser, heal; unrelated code stays untouched. Use for "webmcpify", "add WebMCP", or "expose app actions to AI agents".
vardoger-analyze
Use when the user asks to personalize the GitHub Copilot CLI assistant, adapt Copilot to their style, use vardoger, or analyze their Copilot CLI conversation history. Reads the local session directory at `~/.copilot/session-state/`, extracts recurring preferences and conventions, and writes a fenced personalization block into `~/.copilot/copilot-instructions.md`. Runs entirely on the user's machine via the local `vardoger` CLI (`pipx install vardoger`); no network calls and no uploads. Triggers: 'personalize my copilot', 'analyze my copilot history', 'tailor copilot to me', 'run vardoger', 'update my copilot instructions from history', 'make copilot learn my style'.
transloadit-media-processing
Process media files (video, audio, images, documents) using Transloadit. Use when asked to encode video to HLS/MP4, generate thumbnails, resize or watermark images, extract audio, concatenate clips, add subtitles, OCR documents, or run any media processing pipeline. Covers 86+ processing robots for file transformation at scale.
terraform-azurerm-set-diff-analyzer
Analyze Terraform plan JSON output for AzureRM Provider to distinguish between false-positive diffs (order-only changes in Set-type attributes) and actual resource changes. Use when reviewing terraform plan output for Azure resources like Application Gateway, Load Balancer, Firewall, Front Door, NSG, and other resources with Set-type attributes that cause spurious diffs due to internal ordering changes.
technical-job-search
Use this skill when a software engineer asks for help with job search tasks: parsing or analyzing a job description, tailoring a CV/resume, writing a cover letter, evaluating a job offer, or drafting a post-interview follow-up email. Do not activate for general career advice unrelated to an active job search action.
steno-mode
Shorthand-first response compression that cuts ~40% of response tokens while preserving technical precision and exact literals. Use when the user says "steno mode", "shorthand mode", "compressed responses", "token reduction", "brief structured output", or invokes /steno. Supports four compression levels: lite, brief, court, machine. Do not trigger for requests needing polished prose such as onboarding/tutorial content, stakeholder or customer-facing copy, or teaching-focused explanations.