# Rich HTML

> Render content as a polished, self-contained HTML deck or document - with Mermaid diagrams, cards, tables, and a cohesive dark theme - instead of plain Markdown. Use when asked to create an HTML deck, slide presentation, visual recap of completed work, or a rich HTML page, report, or summary that Markdown cannot express.

- Skill: `n0an/rich-html` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add n0an/rich-html`
- Raw SKILL.md: https://api.skillmd.com/api/skills/n0an/rich-html/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: n0an (https://skillmd.com/u/n0an)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/n0an/rich-html

---


Produce a single self-contained `.html` file that presents content far more expressively than Markdown. Markdown is clean but flat - it cannot draw a Mermaid diagram, lay out a card grid, color-code a callout, run as a navigable slide deck, or offer a download button for a result file. This skill outputs HTML that can.

The motivating ritual: after a long, intensive run - a research loop that tried 200 ideas, a multi-hour build, a deep refactor - ask for an HTML deck of what worked, what did not, and what to do next. Page through it with a coffee: clear slides, honest reflection, and buttons to download the best artifacts. HTML beats Markdown for exactly this.

Two output profiles cover almost everything:

- **Deck** - fullscreen slides with keyboard / click / swipe navigation, a progress bar, and a counter. Use for a recap of completed work, a highlights showcase, a pitch, a walkthrough, anything meant to be presented one beat at a time.
- **Document** - one long scrolling page with sections, tables, and inline diagrams. Use for architecture write-ups, reports, specs, references, anything meant to be read and scanned.

When the user does not specify, infer the profile from intent (see `references/content-guide.md`): "deck / presentation / slides / recap / showcase / highlights" lean deck; "doc / report / reference / overview / architecture / spec" lean document. If genuinely ambiguous, ask once.

## Workflow

1. Pick the profile (deck vs document) from the request and `references/content-guide.md`.
1. Copy the matching template from `assets/` (`deck-template.html` or `document-template.html`) as the starting point. Do not hand-roll the scaffolding - the templates already solve navigation, theming, and the Mermaid render gotcha.
1. Replace the placeholder content with the real material: lead with the outcome or headline, then showcase the highlights. Use cards, big-stat numbers, callout notes, and tables from `references/design-system.md`.
1. Add Mermaid diagrams wherever a picture beats prose (flows, dependency graphs, sequences) following `references/mermaid.md`.
1. Save the file (see Output) and tell the user the path plus how to open it.

If you only need part of this, load only the relevant reference file.

## Core Instructions

- **One self-contained `.html` file.** Inline all CSS and JS. The only external dependency is the Mermaid CDN `<script>`, and only when the file actually contains diagrams. Everything else must work offline by double-clicking the file.
- **Start from the templates in `assets/`.** They carry the full design system and the working navigation / render logic. Vary the content and the accent colors, not the scaffolding.
- **Dark theme by default** using the GitHub-dark palette (`--bg:#0d1117`). Keep the CSS variable tokens; recolor accents per topic if you want, but keep the look cohesive.
- **Decks must render Mermaid lazily**, only once a slide becomes visible. A diagram rendered while its slide is `display:none` measures a zero-size box and collapses to an empty SVG. The deck template already handles this with `startOnLoad:false` + per-slide `mermaid.run()` - keep that intact. See `references/mermaid.md`.
- **Documents can use `startOnLoad:true`** because every diagram is laid out and visible from the start.
- **Content over chrome.** Real numbers, concrete outcomes, short skimmable lines. Lead with the result. Cut filler. A deck slide holds one idea; a document section holds one topic.
- **Keep it legible.** Use the fluid `clamp()` type scale from the templates, keep contrast high, and let documents read fine even with JS disabled.
- **Make artifacts downloadable when they exist.** If the work produced files worth grabbing (best experiment, result JSON, generated audio, a log), add download buttons that link to them. Place the file next to the `.html` (or use a relative path) and use `<a class="btn" href="..." download>`. See `references/design-system.md`.

## Output

- **Default save location:** `llmtemp/` inside the current repository if that folder exists; otherwise the current working directory. If the user names a path, use it.
- **Filename:** kebab-case, ending in `.html` (for example `session-recap.html`, `module-architecture.html`).
- After writing, report the absolute path and tell the user they can open it with `open <path>` on macOS (or just double-click it).
- **Serve it on a local port when the file links to downloadable artifacts or the user wants to browse it like an app.** Download links and any `fetch` are most reliable over `http://` rather than `file://`, and a served deck is shareable on the local network. Run a static server from the file's folder and give the user the URL:

  ```bash
  cd <folder with the .html and its artifacts>
  python3 -m http.server 8000   # then open http://localhost:8000/<file>.html
  ```

  Ask before starting a long-lived server; for a quick local view, opening the file directly is enough.

## References

- `references/content-guide.md` - choosing deck vs document, structuring a "completed work" showcase, and writing punchy, skimmable content.
- `references/design-system.md` - the shared CSS tokens and components: palette, fluid typography, cards, pills, tags, callout notes, big-stat numbers, flow steps, grids, and gradient text.
- `references/deck-format.md` - the slide-deck anatomy: slide structure, navigation (keyboard / click / swipe), progress bar, counter, nav dots.
- `references/document-format.md` - the scrolling-document anatomy: sections, panels, tables, legends, and ASCII diagrams.
- `references/mermaid.md` - embedding and theming Mermaid, the deck visibility gotcha, and the diagram types that work best.

## Assets

- `assets/deck-template.html` - a complete, working slide deck. Copy and fill.
- `assets/document-template.html` - a complete, working scrolling document. Copy and fill.