alirezarezvani/claude-skills / markdown-html/skills/md-slides
md-slides
VerifiedTurn 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.8 KB |
| assets/md_slides_template.html | other | 4.8 KB |
| references/keyboard_nav_patterns.md | markdown | 4.6 KB |
| references/presentation_ux.md | markdown | 5.1 KB |
| references/single_file_deck_conventions.md | markdown | 5.1 KB |
| scripts/deck_html_renderer.py | script | 20.4 KB |
| scripts/presenter_notes_parser.py | script | 3.9 KB |
| scripts/slide_splitter.py | script | 9.9 KB |
references/single_file_deck_conventions.md
View on GitHub# Single-File Deck Conventions
**Why this exists:** The orchestrator's single-file discipline document establishes the rule for the whole domain. This document records the md-slides-specific decisions — what's different about decks vs documents, and what the single-file constraint means specifically for presentation artifacts.
## The contract
One `.html` file, projected from any browser. Externals limited to:
- **`fonts.googleapis.com`** — Google Fonts CSS for typography
- **`cdn.jsdelivr.net`** — Prism.js, ONLY when `--syntax` is explicitly passed (opt-in; off by default)
Why Prism is opt-in for decks (vs always-on for md-document):
- Most decks have few/short code blocks; the Prism payload is overhead for a typography-heavy artifact
- A speaker projecting a deck doesn't need pixel-perfect syntax fidelity; the audience reads from a distance
- Print-to-PDF benefits from absence of CDN dependencies (the print artifact is the artifact, not a server)
## Why single-file specifically matters for decks
1. **Projector-friendly**: the speaker opens one file from their laptop. No server, no `npm start`, no build artifact directory.
2. **Conference WiFi-tolerant**: even if WiFi fails mid-talk, the deck keeps working. Google Fonts is cached after first paint; Prism (when enabled) gracefully degrades to plain `<pre>`.
3. **PDF-exportable**: the same `.html` file becomes a PDF via the browser's print dialog (`Cmd+P` / `Ctrl+P`). The `@media print` stylesheet makes each slide one page.
4. **Email-attachable**: a 15-30 KB single-file deck attaches to email and renders inline in modern clients.
5. **Reproducible**: the deck-as-artifact is deterministic. Re-running the renderer on the same markdown produces the same HTML (no timestamps, no random IDs).
## What we deliberately don't externalize
- **CSS** — fully inline. Base CSS + design-system tokens + style overrides = ~6-7 KB.
- **JavaScript** — fully inline. Vanilla JS + IntersectionObserver-free navigation = ~3 KB.
- **Slide content** — every `<section>` is in the HTML. No lazy-loading, no fetch.
- **Speaker notes** — stored in the `data-notes` attribute of each `<section>`. Travels with the slide.
- **Images** — currently passed through as URLs; users wanting full single-file portability for image-heavy decks can pre-process to base64 (out of scope for v2.10.3).
## Why no transitions / animations
Three reasons:
1. **Speaker pacing** — transitions add latency between key press and visible response. For a brisk talk, that latency adds up.
2. **Recording-friendly** — many talks get screen-recorded. A snap transition is easier to edit than a fade.
3. **`prefers-reduced-motion`** — about 35% of users have motion-sensitivity preferences enabled (per WCAG WG estimates). A motion-free deck works for everyone by default.
If a deck genuinely needs motion, the user can add a `<style>` override block to the rendered HTML (it's a `.html` file — fully editable).
## Print-to-PDF discipline
```css
@media print {
html, body { height: auto; overflow: visible; }
.chrome, .progress, .presenter-panel { display: none !important; }
.slide {
display: flex !important; /* override "only active is visible" */
position: relative; /* break out of absolute positioning */
height: 100vh; /* one slide = one page */
page-break-after: always;
break-after: page;
}
.slide:last-child { page-break-after: auto; }
}
```
The result: `Cmd+P` from the deck produces a PDF where each slide is one A4/Letter page. No PDF generation pipeline needed; the browser does it.
## Sources
### 1. Tom MacWright — *Big* (github.com/tmcw/big, MIT)
The single-file deck tool that proved the model works. Used at speaking engagements by the JavaScript community for over a decade.
### 2. reveal.js — Single-file export (revealjs.com/installation/#full-setup)
reveal.js can produce a single-file output but typically ships multi-file. We adopt the single-file end of the spectrum exclusively.
### 3. Slides.com — HTML export
Slides.com's "export to HTML" produces a single-file artifact. Validates the user demand for the format independent of any one tool.
### 4. Marp — *Marp CLI HTML output* (marp.app)
Markdown-to-deck tool. Outputs single-file HTML by default. Our `---` boundary + `<!-- notes: -->` syntax is read-compatible with Marp's input.
### 5. Pandoc — `--standalone` flag (pandoc.org)
The pattern of "compile to single self-contained HTML." We honor the same constraint.
### 6. MDN — `@media print` (developer.mozilla.org/en-US/docs/Web/CSS/@media/print)
The browser-native primitive that makes "deck as printable PDF" work without any PDF library.
### 7. WCAG 2.2 §2.3.3 *Animation from Interactions* and `prefers-reduced-motion`
The accessibility-driven case for motion-free defaults. Our deck respects this preference automatically.
## Applied to `md-slides`
`deck_html_renderer.py` emits the single-file shape: inline CSS + inline JS + all `<section>` elements with `data-notes` attributes. The only external is Google Fonts CSS; Prism is opt-in via `--syntax`. Print-to-PDF works out of the box.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |