Render HTML

/render-html: Markdown → single-file HTML for human reading

Markdown is for writers. HTML is for readers. ARIS workflow nodes write Markdown (canonical, audit-trail-friendly, machine-parseable). /render-html turns selected artifacts into a polished single-file HTML view for the human who actually has to read them. The Markdown stays the source of truth.

When to use this skill

Use /render-html for ARIS artifacts that have a real human reader:

Do NOT use for:

• LaTeX paper output — the final reader-facing artifact is PDF, not HTML.
• SKILL.md files — those are internal LLM-facing protocol.
• .aris/traces/* review traces — forensic debug, not human display.
• Every Markdown file in your project — only artifacts that benefit from sticky TOC, callouts, math, or score progressions.

Core invariants

• MD / JSON is canonical, HTML is generated view. Edit the source, then re-render. Do not hand-edit the HTML.
• Review at the artifact boundary (ARIS invariant). Academic-template HTML — used for the artifacts humans actually read (IDEA_REPORT, AUTO_REVIEW, KILL_ARGUMENT, PAPER_PLAN) — is reviewed by Claude in a fresh self-review pass before being claimed as a finished view (no external model is configured; see auto-review-loop's "Self-Review Backend (No Second Model)" for the pattern and its honest tradeoff — no independence guarantee). Dashboard-template HTML (cockpit / debug views) skips review by default but accepts --review to force it. See § HTML Review Gate below.
• Drift detection. Every rendered HTML embeds the source path, SHA256, and generation timestamp in <meta> tags AND in the visible page header. If the HTML and source diverge, the meta tells you which version of the source produced it.
• Single-file output. No build system, no separate CSS, no node_modules. Just one .html.
• CDN-friendly default, --offline fallback. MathJax 3 and highlight.js load from cdn.jsdelivr.net by default. Pass --offline to skip both — math will appear as raw $x$, code blocks won't get syntax highlighting, but everything stays readable.
• Pure stdlib helper. render_html.py uses only re, html, hashlib, json, datetime, pathlib, argparse, sys. No pip install required.
• Defense-in-depth XSS sanitization. The helper strips <script>/<style>/<iframe>/<object>/<embed>/<form>/<input>/<button>/<link>/<meta>/<base> tags, all on* event-handler attributes (onclick, onload, …), and rewrites javascript:/vbscript:/data: href/src/action schemes to #blocked-unsafe-url:. ARIS workflow artifacts should not contain these in the first place, but the sanitizer is the safety net in case an LLM hallucinates one. Markdown text content is HTML-escaped separately and never reaches the sanitizer.

Tool Location

Arch C self-contained: the canonical implementation lives at skills/render-html/scripts/render_html.py (this SKILL's own scripts/ subdirectory), together with its templates at skills/render-html/scripts/templates/{academic,dashboard}.html. The helper is new — no legacy tools/ shim exists.

Resolve $RENDER_HTML with the hybrid chain (Layer 0 prefers the self-contained location for the owning SKILL; Layers 1-3 are the shared-runtime chain documented in shared-references/integration-contract.md §2, Policy A — skill-local gate):

# Layer 0: self-contained (CC 1.0+ exposes $CLAUDE_SKILL_DIR).
RENDER_HTML=""
if [ -n "${CLAUDE_SKILL_DIR:-}" ] && [ -f "$CLAUDE_SKILL_DIR/scripts/render_html.py" ]; then
  RENDER_HTML="$CLAUDE_SKILL_DIR/scripts/render_html.py"
fi
# Layers 1-3: shared-runtime chain (non-CC hosts + manual installs).
if [ -z "$RENDER_HTML" ]; then
  cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
  if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills.txt ]; then
      ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null) || true
  fi
  RENDER_HTML=".aris/skills/render-html/scripts/render_html.py"
  [ -f "$RENDER_HTML" ] || RENDER_HTML="skills/render-html/scripts/render_html.py"
  [ -f "$RENDER_HTML" ] || { [ -n "${ARIS_REPO:-}" ] && RENDER_HTML="$ARIS_REPO/skills/render-html/scripts/render_html.py"; }
  [ -f "$RENDER_HTML" ] || RENDER_HTML=""
fi
[ -z "$RENDER_HTML" ] && {
  echo "ERROR: render_html.py not resolved (layer 0: \$CLAUDE_SKILL_DIR/scripts/; layers 1-3: .aris/skills/render-html/scripts/, skills/render-html/scripts/, \$ARIS_REPO/skills/render-html/scripts/)." >&2
  echo "       /render-html cannot produce HTML output. Fix: rerun bash tools/install_aris.sh, or copy from \$ARIS_REPO/skills/render-html/scripts/." >&2
  exit 1
}

Invocation

# Default: academic template, output to <input>.html alongside source
python3 "$RENDER_HTML" idea-stage/IDEA_REPORT.md

# Dashboard template for cockpit-style views
python3 "$RENDER_HTML" research-wiki/SUMMARY.md --template dashboard

# Custom output path + title + eyebrow
python3 "$RENDER_HTML" review-stage/AUTO_REVIEW.md \
  --out review-stage/AUTO_REVIEW.html \
  --title "Auto Review — overnight run" \
  --eyebrow "Workflow 2"

# Embed sidecar state JSON (rendered as a folded <details> JSON block at end)
python3 "$RENDER_HTML" review-stage/AUTO_REVIEW.md \
  --state review-stage/REVIEW_STATE.json

# Embed sidecar JSON (e.g., for KILL_ARGUMENT.md + KILL_ARGUMENT.json)
python3 "$RENDER_HTML" paper/KILL_ARGUMENT.md \
  --json paper/KILL_ARGUMENT.json \
  --title "Kill Argument — adversarial review"

# Offline (no CDN; math + code render as plain text)
python3 "$RENDER_HTML" idea-stage/IDEA_REPORT.md --offline

# JSON-only input (wrapped in a <pre><code class="language-json"> block)
python3 "$RENDER_HTML" review-stage/REVIEW_STATE.json --template dashboard

# Language attr (default zh-CN; set for English-primary artifacts)
python3 "$RENDER_HTML" docs/SKILLS_CATALOG.md --lang en

# Skip review (academic template otherwise reviews by default)
python3 "$RENDER_HTML" idea-stage/IDEA_REPORT.md
# … then the skill skips the self-review step if --no-review
# was on the command line. Pass --review to a dashboard render to force it.

The --review / --no-review flags are parsed by the SKILL orchestrator (Claude Code), not by render_html.py. The helper itself stays pure stdlib and never calls MCP. See § HTML Review Gate below for the exact resolution and prompt.

Workflow

Step 1: Identify the artifact

From $ARGUMENTS, determine what to render. Common patterns:

• "render IDEA_REPORT" → idea-stage/IDEA_REPORT.md, academic template
• "make AUTO_REVIEW readable" → review-stage/AUTO_REVIEW.md + --state review-stage/REVIEW_STATE.json
• "show the kill argument as HTML" → paper/KILL_ARGUMENT.md + --json paper/KILL_ARGUMENT.json
• "research-wiki dashboard" → look for research-wiki/SUMMARY.md or generate from raw entity counts (Phase 2 work; for Phase 1 just render SUMMARY.md if present, else fall back to listing top-level wiki structure)

Step 2: Pick template

• academic (default): linear long-form. Sticky TOC sidebar + serif body + callouts + tables + math + Q&A <details>. Use for IDEA_REPORT, AUTO_REVIEW, KILL_ARGUMENT, PAPER_PLAN.
• dashboard: grid layout, smaller font, denser metrics cards, no TOC sidebar. Use for research-wiki cockpit, RESUBMIT_REPORT, multi-project overviews.

Step 3: Run the helper

Use the resolver above to get $RENDER_HTML, then invoke. The script writes the HTML alongside the source by default (or wherever --out says) and prints a one-line confirmation including the source SHA256 prefix.

Step 4: HTML Review Gate (self-review)

Decide whether to run review. Per the ARIS invariant "executor must not judge its own output as if it were still the same act of production", the academic-template HTML is reviewed in a dedicated fresh pass before being claimed as a delivered view. No external model is configured, so this is a Claude self-review pass, not a cross-model one — see auto-review-loop's "Self-Review Backend (No Second Model)" for the full rationale and the honest tradeoff (no independence guarantee; self-review can't catch blind spots the way a different model could). Resolution:

should_review = explicit --review present
             or (template == "academic" and --no-review NOT present)

So:

• --template academic (default) → review by default. Skip with --no-review.
• --template dashboard → no review by default. Force with --review.
• Phase 2 workflow auto-emit (activated 2026-05) selects per-skill via the RENDER_HTML hooks documented below — interim views default to --no-review, final / audit-class deliverables default to full gate.

If should_review is true, Claude runs a dedicated fresh self-review pass with the prompt below — re-reading the source MD + generated HTML directly off disk, not from memory of generating them, and not carrying forward this skill's intermediate state from the render step.

Scope of review (narrow on purpose). The HTML reviewer audits render fidelity / safety / structure only — not claim truthfulness. Claim audit belongs upstream (/paper-claim-audit, /research-review, /result-to-claim). Specifically the reviewer checks:

1. Information fidelity — every section, claim, table, code block, list, math snippet, sidecar payload is present in the HTML (no silent drop)
2. Structural integrity — heading hierarchy / nested lists / table cells / code fences / <details> blocks / math delimiters survive parsing
3. Callout routing — > 🚨 … got .callout-bad, > 💡 … got .callout-info, etc.
4. Safety / escaping — no raw <script> / onclick= / javascript: / unreplaced placeholders / template-leak survives
5. Expected-difference allowance — frontmatter strip, generated header/footer/meta, TOC insert, sanitized unsafe HTML are all expected, not flagged

Self-review prompt (mandatory shape). Run this as a fresh, dedicated pass — not a continuation of the render step:

You are the ARIS HTML render auditor. This is a fresh review pass: re-read the
files below directly rather than relying on what you remember producing.

Read these files directly:
- Source artifact: <ABS path to source.md or source.json>
- Generated HTML:  <ABS path to out.html>
- Optional sidecars: <state.json>, <kill_argument.json> (if any)

Task: Audit whether the generated HTML is a faithful, safe, structurally
usable view of the source artifact. Do NOT judge whether the research
claims are true. Judge only rendering fidelity.

Checks:
1. Information fidelity — sections / claims / tables / code blocks /
   lists / math / sidecars not silently dropped or materially altered.
2. Structural integrity — heading hierarchy, tables, nested lists,
   code fences, details/summary, math delimiters preserved.
3. Callout routing — warning/critical/good/info blockquotes map to
   appropriate CSS classes when present.
4. Safety/escaping — no unexpected raw script/style/iframe/form/
   event-handler/javascript/data URL survives from source.
5. Placeholder/template leakage — no unreplaced {{PLACEHOLDER}} or
   parser private placeholder character appears.
6. Expected differences — frontmatter strip, generated header/footer/
   meta, TOC insertion, sanitized unsafe HTML are EXPECTED and not a
   defect.

Return STRICT JSON first, then a short prose note:

{
  "verdict": "PASS|WARN|FAIL|ERROR",
  "checks": {
    "source_hash_match": "pass|warn|fail|unknown",
    "information_fidelity": "pass|warn|fail",
    "structure": "pass|warn|fail",
    "math_code_tables": "pass|warn|fail",
    "callouts": "pass|warn|fail|not_applicable",
    "safety_escaping": "pass|warn|fail",
    "placeholder_leak": "pass|warn|fail"
  },
  "blocking_issues": [
    {"severity": "fail",
     "source_location": "L<n>...",
     "html_location": "<selector or near-text>",
     "issue": "...",
     "suggested_fix": "..."}
  ],
  "warnings": [
    {"severity": "warn", "issue": "...", "suggested_fix": "..."}
  ],
  "summary": "one paragraph"
}

Verdict rules:
- PASS: no material fidelity/safety issue.
- WARN: readable output with minor unsupported-Markdown or cosmetic
  degradation only.
- FAIL: missing/altered meaningful content, broken tables/math/code/
  callouts that change interpretation, unsafe executable HTML, source
  hash mismatch, or placeholder leakage.
- ERROR: files could not be read or audit could not complete.

Save outputs:

1. Write the JSON verdict to <out_path>.review.json (sibling to the HTML).
2. Save the raw self-review trace to .aris/traces/render-html/<YYYY-MM-DD>_run<NN>/review.{txt,json} per shared-references/review-tracing.md, noting "backend": "self".
3. Print a one-line summary to the user: verdict, N blocking, N warnings, trace: <path>.

If verdict == FAIL: the HTML is NOT a delivered review-passed view. Tell the user the blocking issues, point them at the source (fix MD or template, not the HTML), and re-render. Do not silently overwrite or mark as complete.

If verdict == WARN: deliver the HTML but surface the warning list. User decides whether to fix or accept.

Because self-review only requires Claude itself, it is available whenever this skill runs — there is no REVIEW_UNAVAILABLE fallback to fall back to. The tradeoff is independence, not availability: a self-reviewed PASS means "Claude re-checked its own render fresh and found no issue," not "an independent model checked it." If the user has an external model / Codex CLI configured and wants that instead, they can manually invoke /research-review on the source MD.

Step 5: (Optional) Verify in browser

open <out.html> on macOS, xdg-open on Linux, start on Windows. Math + code highlighting need internet (CDN); offline mode degrades gracefully to readable text.

What the helper supports

Markdown subset (chosen to match what ARIS workflows actually emit):

• Headings #/##/###/#### with auto-generated IDs for TOC
• Paragraphs, bold **x**, italic *x* / _x_, inline code `x`, strikethrough ~~x~~, links [t](url), images ![a](url)
• Unordered/ordered lists with 2-space nested indentation
• Code blocks with optional language (```python) — gets <pre><code class="language-python"> for highlight.js
• ASCII-art code blocks (heuristic: many box-drawing chars) → <pre class="diagram"> with a distinct cream-yellow background
• Tables with :--- / :---: / ---: alignment
• Blockquotes > ... — emoji-prefix detection routes to callout variants:
  • ⚠️ → .callout-warn (Warning)
  • 💡 / 📝 → .callout-info (Tip / Note)
  • ✅ / 🔒 → .callout-good (OK / Guarantee)
  • ❌ / 🚨 → .callout-bad (Blocked / Critical)
• HTML passthrough for <details>, <summary>, <div>, <figure>, <table>, <section>, etc. (block-level) — used for the existing Round-1/2/3 fix details in KILL_ARGUMENT.md
• LaTeX math: inline $x$ and display $$x$$ pass through verbatim to MathJax

What the helper does NOT support (intentional simplifications):

• Footnotes ([^1])
• Definition lists
• Reference-style links [label][ref]
• Setext-style headings (=== / --- underline form — ARIS doesn't emit these)

Frontmatter (--- ... ---) at the very top of the file is stripped before rendering (SKILL.md frontmatter style); the body that follows is what gets converted.

Two-phase integration plan (Phase 1 was this skill; Phase 2 is workflow hooks, activated 2026-05)

Phase 1 (originally shipped): Opt-in only. Users explicitly called /render-html <artifact.md> after a workflow completes.

Phase 2 (activated 2026-05): Eight key skills now auto-emit HTML at workflow termination, each guarded by a RENDER_HTML = true constant that the user can flip off per skill (or pass — render html: false at invocation).

Cost-tiered review gate (per artifact type):

--no-review for interim reports is intentional: the source MD has already been reviewed by the producing skill's own cross-model gate, and the HTML render only converts structure — it doesn't add new claims. Full review at every checkpoint would multiply Codex calls per pipeline by 4-6×.

To disable HTML output for a specific skill: set RENDER_HTML = false in the skill's constants block or pass — render html: false. To globally disable: skip with environment variable ARIS_RENDER_HTML=0 (planned, not yet implemented; flag per skill in the meantime).

Customizing the templates

The two templates live at skills/render-html/scripts/templates/{academic,dashboard}.html. Each is a single self-contained HTML file with inline CSS using {{PLACEHOLDER}} substitution. To customize:

1. Copy one of the templates to a new name, e.g., my_brand.html.
2. Edit the CSS variables in :root { ... } to change colors, the font stack, or layout dimensions.
3. Add the template name to the --template choices in render_html.py argparse.
4. Re-run /render-html <input> --template my_brand.

The default templates are derived from the user's own academic-newspaper tutorial style (Source Serif Pro + Songti SC, 3-color palette, sticky TOC, low-flash). Stay close to that idiom for ARIS artifacts unless you have a specific reason to break the visual language.

External alternatives (for richer surfaces)

For deck / poster / Xiaohongshu card / tweet card / data report style outputs, point users to html-anything (Apache-2.0, 3000⭐ at time of writing). It ships 75 SKILL.md templates across 9 surfaces and detects 8 coding-agent CLIs (including Claude Code, Codex, Copilot). ARIS does not depend on it — /render-html covers ARIS-native artifacts; html-anything is the recommended path for richer publishing surfaces.

Key rules

• Do not auto-render every Markdown file. Only artifacts on the whitelist above. File proliferation is the main anti-pattern.
• Do not hand-edit the generated HTML. Edit the source, then re-render. The embedded SHA256 in the HTML meta tells you if the source has changed since render.
• academic-template HTML is a reviewed artifact by default, not raw output. A dedicated fresh Claude self-review pass (no external model configured; see auto-review-loop's "Self-Review Backend") gates the academic deliverables — the same way /proof-checker, /paper-claim-audit, /citation-audit, /kill-argument gate their respective products. --no-review is appropriate for interim auto-emits (e.g., idea-stage/IDEA_REPORT.html, per-round review-stage/AUTO_REVIEW.html) where the source MD has already passed an upstream review gate — the HTML render is then a structural conversion, not a new claim audit. For shipped / reviewer-facing / audit-class outputs, keep the full gate.
• The reviewer audits rendering, not research. Claim truthfulness is owned upstream by /paper-claim-audit, /result-to-claim, /research-review. The HTML reviewer asks: "did the renderer faithfully + safely convert this source?" — nothing more.
• CDN dependency is opt-out, not opt-in. Most users have internet; --offline is for air-gapped runs / archival.
• The default style is academic-newspaper, not marketing-flashy. Match the existing ARIS tonal voice. If you want decks/posters/social cards, point users to html-anything.
• Pure stdlib only. Adding a pip install dependency to render_html.py requires an explicit decision — the helper currently has none. MCP calls live in the skill orchestrator, never in the helper script.