# Htmlify > Generate beautiful, pedagogical HTML companions for superpowers-gstack MD artifacts (design docs, handoffs, plans). Auto-opens via --open; generates per-directory dashboards. Triggered manually or via PostToolUse hook. - Skill: `paretofilm/htmlify` (Agent Skill, multi-file: 44 files) - Install (CLI): `npx skillmds@latest add paretofilm/htmlify` - Raw SKILL.md: https://api.skillmd.com/api/skills/paretofilm/htmlify/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: Paretofilm (https://skillmd.com/u/paretofilm) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/paretofilm/htmlify --- # /htmlify Lager visuelt elegante HTML-companions ved siden av MD-artefakter, og en aggregert dashboard-side per katalog. Designet for vibe-codere som ikke orker å lese verbose MD-output fra skills som /office-hours, /autoplan, /plan-eng-review, /context-handoff osv. **Når det aktiveres:** - Bruker sier "html-ify", "lag html av", "generer HTML companion" - Bruker spør "kan jeg få en penere visning av denne MD-en" - PostToolUse-hook (når installert) auto-trigger ved Write/Edit på artefakt-MD - Invoked programmatically by `/superpowers-gstack:swiftui-design-consultation` for Phase 3 proposal preview and Phase 6 DESIGN.html generation ## How to invoke Skill-katalogen oppdages av Claude Code som "Base directory for this skill" ved invokering. Wrapper-binæren `bin/htmlify` self-lokaliserer og kan kjøres fra hvilken som helst cwd: ```bash "$SKILL_DIR/bin/htmlify" ``` Hvor `$SKILL_DIR` er katalogen denne SKILL.md filen ligger i. Eksempel når installert via Claude Code marketplace: ```bash ~/.claude/plugins/cache/paretofilm-plugins/superpowers-gstack//skills/htmlify/bin/htmlify ``` Wrapper-en sjekker at `bun` og deps er installert; printer feilmelding (exit 5) hvis ikke. ## First-run setup (one-time) Deps må installeres én gang per installasjons-lokasjon. Wrapperen forteller deg den nøyaktige kommandoen hvis den feiler: ```bash cd "$SKILL_DIR" && bun install ``` Etterpå er skill'en klar til bruk uansett antall invokeringer. ## Usage ### Render én MD til HTML companion ```bash "$SKILL_DIR/bin/htmlify" ``` Output: `/.superpowers-html/.html`. Også en `companion.css` blir kopiert til samme katalog. ### Med auto-open (macOS) ```bash "$SKILL_DIR/bin/htmlify" --open ``` ### Generer dashboard for en katalog ```bash "$SKILL_DIR/bin/htmlify" dashboard ``` Output: `/.superpowers-html/index.html` med liste av alle artefakter i katalogen sortert by mtime desc. ### Flags - `--plan ` — Last v2 rendering plan (rik layout: comparison-matrix, flowchart-svg, pullquote, callout-box, stats-bar, two-column, expandable, diff-card, feedback-panel). Uten flagget rendres v1-template. - `--open` — Åpne resulterende HTML i **Safari** (macOS only) som distraksjonsfri leser. **Alle eksisterende Safari-vinduer lukkes først** så HTML-en er det eneste som vises. Brukerens default-nettleser røres ikke. - `--no-clobber` — Skip render hvis HTML er nyere enn MD - `--force-rebuild` — Tving render selv ved no-clobber ## Enhanced rendering (v2 — plan-driven layout) v1 gir "penere MD med strukturerte cards" — det er en god default. **v2 gjør HTML-en til en informativ plansje** med komponenter som comparison-matrix, flowchart-svg, pullquotes, stats-bar, callout-boxes, diff-cards og en interaktiv feedback-panel. V2 fungerer via en **rendering plan** (JSON-fil) som du genererer **i Claude Code-sesjonen** (gratis under Max-plan; **bruker IKKE Anthropic API**) og sender til CLI med `--plan`. ### Når bruke v2? - MD-en er lang/tett og ville hatt nytte av visuell hierarki - Det er en sammenligning, et flytdiagram, før/etter, eller en tidslinje skjult i prosaen - Du vil ha en feedback-runde fra brukeren (sjekkbokser + radio + kommentar → clipboard JSON) ### Hvordan generere en plan (i denne sesjonen) 1. **Les MD-en** med Read-tool. 2. **Identifiser visuelle muligheter**: - H2 med "Approaches Considered" / "Options" → `comparison-matrix` - H2 med arkitektur/pipeline/flyt → `flowchart-svg` - Memorable quote i teksten → `pullquote` med `after_section` - "Note:" / "Warning:" / "Insight:" → `callout-box` - Metrics, before/after counts → `stats-bar` - To kolonner som speiler hverandre → `two-column` - Lang side-info som ikke skal dominere → `expandable` - Kodeblokker som er "før/etter" → `diff-card` 3. **Skriv plan-JSON** til en temporary fil med strukturen under. 4. **Kjør CLI**: `"$SKILL_DIR/bin/htmlify" --plan --open` 5. **Sett alltid `feedback_panel`** med relevante premises/approaches + tilpasset spørsmål. Bruker kan trykke "Copy feedback as prompt" og lime inn i neste sesjon. ### Plan-JSON skjema ```json { "version": 1, "sections": [ { "heading": "Approaches Considered", "treatment": "comparison-matrix", "data": { "items": [ {"title": "Option A", "summary": "...", "pros": ["..."], "cons": ["..."], "effort": "1d", "risk": "low"}, {"title": "Option B", "pros": ["..."], "cons": ["..."], "highlighted": true} ] } }, { "heading": "Architecture", "treatment": "flowchart-svg", "data": { "orientation": "LR", "nodes": [{"id": "a", "label": "Input"}, {"id": "b", "label": "Process", "emphasis": true}, {"id": "c", "label": "Output"}], "edges": [{"from": "a", "to": "b"}, {"from": "b", "to": "c", "label": "transform"}] } } ], "pullquotes": [ {"text": "...", "attribution": "...", "after_section": "Problem Statement"} ], "feedback_panel": { "enabled": true, "premises": ["P1 label", "P2 label"], "approaches": ["A1 label", "A2 label"], "custom_questions": [ {"id": "q1", "label": "Did this layout help?", "type": "radio", "options": ["yes", "no"]}, {"id": "q2", "label": "Free notes", "type": "text"} ] } } ``` ### Treatments-katalogen | Treatment | Når bruke | Data-form | |-----------|----------|-----------| | `section-card` | Default — vanlig prosakort | (ingen — bruker MD-body) | | `comparison-matrix` | 2-5 alternativer side-ved-side | `{items: [{title, summary?, pros?, cons?, effort?, risk?, highlighted?}]}` | | `flowchart-svg` | Pipelines, state machines, arkitektur | `{nodes: [{id, label, shape?, emphasis?}], edges: [{from, to, label?}], orientation?: "TB"\|"LR"}` | | `pullquote` | Memorable quote (kan også stå i `pullquotes`-array) | `{text, attribution?}` | | `callout-box` | Note/warning/insight/danger | `{level?: "info"\|"warn"\|"insight"\|"danger", title?, body}` | | `stats-bar` | Tall, metrics, before/after counts | `{items: [{label, value, delta?, trend?: "up"\|"down"\|"flat"}]}` | | `two-column` | Sammenligning innenfor ett tema | `{left: {heading?, body}, right: {heading?, body}}` | | `expandable` | Lang side-info som skal kunne kollapses | `{summary, body, open?}` | | `diff-card` | Før/etter kode eller tekst | `{title?, before: {label?, content}, after: {label?, content}}` | ### Viktige regler - **Bruk ALDRI API** — plan-generering skjer i denne Claude Code-sesjonen (Max-plan compute = gratis) - **Headings må matche MD-en** — case-/whitespace-insensitivt. Plan-seksjon uten matching H2 rendres som ny seksjon. - **`treatment: "section-card"`** = ikke override; bruk default rendering - **`feedback_panel` har alltid et kommentar-felt** — uavhengig av om premises/approaches/custom_questions er tomme - **Plan = optional** — uten `--plan` får brukeren v1-rendering (samme som før) ## Frontmatter types som støttes - `type: design-doc` — fra /office-hours - `type: handoff` — fra /context-handoff (eller filnavn `handoff.md` for legacy) - `type: plan` — fra /autoplan - Manglende eller ukjent frontmatter → generic fallback med banner ## Exit codes - 0 — success - 1 — usage error (bad CLI args) - 2 — schema validation failure - 3 — MD parse error - 4 — I/O error (file not found, not writable) - 5 — setup error (deps not installed, bun missing) ## Auto-trigger (PostToolUse hook) For automatisk å fyre htmlify når en skill skriver en artefakt-MD, kjør installeren én gang. Path avhenger av om du jobber fra repo-rota eller fra plugin-installasjonen: **Fra repo (utvikling):** ```bash ./scripts/setup-htmlify-hook.sh ``` **Fra plugin-installasjonen (marketplace):** ```bash ~/.claude/plugins/cache/paretofilm-plugins/superpowers-gstack//scripts/setup-htmlify-hook.sh ``` Hook'en matcher: - Filnavn `handoff.md` - Mønstre: `*-design-YYYYMMDD-HHMMSS.md`, `*-plan-YYYYMMDD-HHMMSS.md` - Alle MD-er under `.gstack/projects/` - Loop-prevention: skip MD-er i `.superpowers-html/` Hook-skriptet self-lokaliserer — det vil alltid kalle `htmlify` fra den katalogen den selv ligger i, så det er trygt å installere hooks fra plugin-cache-stien. ## Development Kun relevant hvis du jobber fra repo-rota i `~/Developer/superpowers-gstack/`: ```bash cd skills/htmlify bun install # first run bun test # 138 tests (v2) ``` Artefakter brukt under utvikling: se design-doc og test-plan i `~/.gstack/projects/Paretofilm-superpowers-gstack/`.