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.

references/keyboard_nav_patterns.md

View on GitHub
# Keyboard Navigation Patterns

**Why this exists:** Every presenter expects ← / → to advance slides, Space to advance, and Esc to exit presenter mode. These conventions are 20 years old. This document records what `md-slides` honors and why each binding is wired the way it is.

## The keymap

| Key | Action | Source |
|---|---|---|
| **→ / Space / PgDn** | Next slide | reveal.js, Big, Spectacle, Keynote, PowerPoint — universal |
| **← / PgUp** | Previous slide | universal |
| **Home** | First slide | reveal.js / Big convention |
| **End** | Last slide | reveal.js / Big convention |
| **P** | Toggle presenter mode | reveal.js convention |
| **Esc** | Exit presenter mode (if active) | universal accessibility expectation |
| **Ctrl/Cmd + P** | Print to PDF (browser-native) | browser default; we don't intercept |

We deliberately do NOT bind:
- **Number keys (1-9)** for slide jump — too easy to hit accidentally during typing
- **F11** for fullscreen — browser default; we don't override
- **Touch gestures** — out of scope; click-to-advance is sufficient for the click-to-advance case
- **Vim keys (h/j/k/l)** — niche; the arrow keys are the universal expectation

## Implementation discipline

```js
document.addEventListener("keydown", function (e) {
    if (e.metaKey || e.ctrlKey || e.altKey) return;  // Don't fight browser shortcuts
    switch (e.key) {
        case "ArrowRight":
        case "PageDown":
        case " ":
            e.preventDefault(); next(); break;
        // ...
    }
});
```

- **Modifier-aware**: we check `metaKey/ctrlKey/altKey` and bail. This means `Cmd+R` reloads (browser default), `Ctrl+P` prints (browser default), and we don't fight them.
- **`preventDefault()` on every match**: Space normally scrolls; we replace that with advance-slide.
- **`replaceState` for URL hash**: each slide change updates `#N` in the URL so deep links work + back button moves through slides naturally.

## URL hash deep linking

Every slide has `id="slide-N"`. The initial render reads `location.hash` and jumps to that slide on load. Sharing `deck.html#3` puts the reader directly on slide 3. Browser back/forward buttons walk slide history.

This works because we use `history.replaceState` (not `pushState`) for arrow-key navigation — otherwise every arrow click would push a new entry and back-button behavior would feel wrong.

## Accessibility

- **`@media (prefers-reduced-motion: reduce)`** — transitions and animations are suppressed when the user prefers reduced motion. The deck still works; it just doesn't animate.
- **Presenter panel uses `<aside aria-label="Presenter view (toggle with P)">`** — screen readers announce its purpose.
- **Slide counter is plain text** — `<span id="counter">1 / 5</span>` is announced by screen readers as the slide changes (we update the text content).
- **No focus traps** — keyboard users can Tab out of any interactive element naturally.
- **No JS-required content** — the slides are static `<section>` elements; JS just controls visibility. With JS off, the first slide renders correctly and the user can scroll through all of them.

## Sources

### 1. reveal.js — *Keyboard Bindings* (revealjs.com)
The convention-setter for web-based decks. Established: ← / → / Space / PgUp / PgDn / Home / End / Esc / F. We honor the subset our scope requires.

### 2. Tom MacWright — *Big* (github.com/tmcw/big)
Single-file deck tool. Validates the minimum viable keybinding set (arrow / space) and the URL-hash navigation pattern.

### 3. Spectacle (github.com/FormidableLabs/spectacle)
React-based deck framework. Same keymap conventions. Reinforces the arrow + space pairing.

### 4. WCAG 2.2 §2.1.1 *Keyboard* (w3.org/WAI/WCAG22)
All functionality must be operable through a keyboard interface. Our nav, presenter toggle, and Esc-to-exit all satisfy this.

### 5. WCAG 2.2 §2.4.3 *Focus Order* (w3.org/WAI/WCAG22)
Focus order must preserve meaning. We don't trap focus or jump focus across slide changes; default tab order applies.

### 6. NN/g — *Keyboard Accessibility* (Jakob Nielsen, 2024 update)
Best practices for keyboard-only navigation: don't fight modifier shortcuts, always provide a visible escape from modal states (P toggles back, Esc also works).

### 7. MDN — *KeyboardEvent.key* (developer.mozilla.org)
The standardized key value strings we match against ("ArrowRight" not "Right"; " " for space; "PageDown" not "PgDn"). Cross-browser-stable since 2018.

## Applied to `md-slides`

The JS payload in `deck_html_renderer.py` wires all of the above, in ~80 lines of vanilla JS, no framework. The presenter panel and progress bar update reactively as the user presses keys.
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: 198kUpdated 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: 198kUpdated 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: 198kUpdated 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: 198kUpdated Claude CodeCodexVerifiedInstall