Preview

/preview — HTML Preview

Render vault content as styled HTML for browser viewing. Markdown stays the source of truth; HTML is the presentation layer.

Context

Today's date: !date +%Y-%m-%d

Config: @core/config.yaml Preview rules: @.claude/rules/preview-formats.md HTML shells: @templates/html/ Processing logic: @_core/PROCESSING.md

Usage

/preview docs/project-a/checkout-flow.md
/preview decisions/project-a/2026-06-29-auth-approach.md
/preview progress all
/preview progress project-a --week
/preview decide auth-approach
/preview block api-rate-limit
/preview meet 2026-06-29-sync-sprint-review
/preview reports/2026-06-29-progress-all.md

Flags

| Flag | Effect | |------|--------| | --with-links | Inline first paragraph from linked notes | | --no-open | Write HTML only, do not open browser | | --shell memo\|prd\|status\|executive | Force template shell | | --link | Write preview: path to source note frontmatter |

Session Task Progress

TaskCreate: "Resolve preview source"
  activeForm: "Resolving preview source..."

TaskCreate: "Render HTML"
  activeForm: "Rendering HTML preview..."

TaskCreate: "Open and verify"
  activeForm: "Opening preview in browser..."

Processing Steps

1. Parse Input

Determine source mode:

| Input pattern | Action | |---------------|--------| | Path to .md file | Read that file directly | | progress {project\|all} | Synthesize like /progress, use status shell | | decide {slug} | Glob decisions/*/*{slug}*.md, pick latest | | block {slug} | Glob blockers/*/*{slug}*.md | | meet {slug} | Glob meetings/*{slug}*.md | | doc {project} {slug} | Read docs/{project}/{slug}.md |

If ambiguous, ask user to clarify path.

2. Gather Content

File mode: Read markdown + frontmatter.

Synthesis mode (progress): Follow /progress gather steps:

• Scan dailies, blockers, docs, decisions for project/timeframe
• Build structured sections: Shipped, In Progress, Blockers, Decisions
• Count metrics for status shell

3. Select HTML Shell

Auto-detect from source:

| Source | Shell | |--------|-------| | docs/ | shell-prd.html | | decisions/, meetings/, blockers/ | shell-memo.html | | progress synthesis | shell-status.html | | reports/*executive* | shell-executive.html | | Other | shell-memo.html (default) |

Override with --shell flag.

4. Convert Markdown → HTML

• Remove YAML frontmatter block
• Map frontmatter to shell vars: project, status, date, title (from H1 or filename)
• Convert body markdown to semantic HTML
• Resolve [[wikilinks]] per preview-formats.md
• Escape user content in HTML (no XSS — literal text only)

5. Write Output

• Ensure reports/previews/ exists
• Filename: {date}-{slug}.html (slug from source file or synthesis type)
• Load shell template, replace all {{PLACEHOLDER}} tokens
• Write complete self-contained HTML file

6. Open Browser

Unless --no-open:

# macOS
open "reports/previews/{filename}.html"

# Linux
xdg-open "reports/previews/{filename}.html" 2>/dev/null

# Windows
start "" "reports/previews/{filename}.html"

7. Optional: Link Back to Source

If --link and source is a single vault note:

• Edit source frontmatter: preview: reports/previews/{filename}.html

8. Append Vault Log

Append to 01-index/_vault-log.md:

• Action: preview
• Files: output HTML path + source path
• Details: shell used, synthesis or file mode

Output

Preview ready: reports/previews/2026-06-29-checkout-flow.html
Shell: prd
Source: docs/project-a/checkout-flow.md
Opened in browser.

Error Handling

| Situation | Action | |-----------|--------| | Source file not found | Suggest similar paths via Glob | | Empty vault (progress) | Report "no data in timeframe" — do not write empty HTML | | Browser open fails | Report file path; user can open manually |

Design Principles

• Typography first — readable fonts, generous line-height, print-ready
• No dependencies — pure HTML/CSS, no npm/pip required
• Self-contained — single file, embedded styles, works offline
• Source preserved — never modify markdown body unless --link requested

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kv0906
• Source: kv0906/pm-kit
• License: MIT
• Homepage: https://willtran.xyz

Install and usage instructions live in the source repository linked above.