render-html skill

/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.
• Cross-model review at the artifact boundary (ARIS invariant). Academic-template HTML — used for the artifacts humans actually read (IDEAREPORT, AUTOREVIEW, KILLARGUMENT, PAPERPLAN) — is reviewed by a fresh cross-family Codex thread before being claimed as a finished view. 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 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 ////////// 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 $RENDERHTML 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: r

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

# S

The --review / --no-review flags are parsed by the SKILL orchestrator (Claude Code), not by renderhtml.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 IDEAREPORT" → idea-stage/IDEAREPORT.md, academic template
• "make AUTOREVIEW readable" → review-stage/AUTOREVIEW.md + --state review-stage/REVIEW_STATE.json
• "show the kill argument as HTML" → paper/KILLARGUMENT.md + --json paper/KILLARGUMENT.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 . Use for IDEAREPORT, AUTOREVIEW, KILLARGUMENT, PAPERPLAN.
• 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 (cross-model)

Decide whether to run review. Per ARIS invariant "executor must not judge its own output", the academic-template HTML is reviewed by a fresh cross-family Codex thread before being claimed as a delivered view. 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 shouldreview is true, fire a fresh mcpcodexcodex thread (NEVER codex-reply; pin model: gpt-6-astra + config: {"modelreasoningeffort": "xhigh"} per ../shared-references/reviewer-routing.md) with the prompt below. The reviewer reads the source MD + generated HTML directly; it does not** see this skill's intermediate state.

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 / blocks / math delimiters survive parsing
3. Callout routing — > 🚨 … got .callout-bad, > 💡 … got .callout-info, etc.
4. Safety / escaping — no raw / 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

Codex prompt (mandatory shape). Send this as a fresh thread (mcpcodexcodex, NOT codex-reply):

You are an independent ARIS HTML render auditor. This is a fresh review thread.

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 

Save outputs:

1. Write the JSON verdict to .review.json (sibling to the HTML).
2. Save the raw codex trace to .aris/traces/render-html/_run/review.{txt,json} per shared-references/review-tracing.md.
3. Print a one-line summary to the user: verdict, N blocking, N warnings, trace: .

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.

If mcpcodexcodex is not available (e.g., user runs /render-html on a Codex-CLI-only setup where Codex MCP isn't wired): emit verdict: REVIEWUNAVAILABLE to the sidecar, do not fabricate PASS, and tell the user the HTML was generated but not** independently reviewed. The user can manually invoke /research-review on the source MD or re-run with Codex MCP available.

Step 5: (Optional) Verify in browser

open 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, images
• Unordered/ordered lists with 2-space nested indentation
• Code blocks with optional language ( python ) — gets for highlight.js
• ASCII-art code blocks (heuristic: many box-drawing chars) → 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 , , , , , , etc. (block-level) — used for the existing Round-1/2/3 fix details in KILL_ARGUMENT.md

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 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 RENDERHTML = false in the skill's constants block or pass — render html: false. To globally disable: skip with environment variable ARISRENDER_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 --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. Cross-model Codex review (fresh thread) 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