/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