musingfox/viz-render

Viz Render Skill

Render markdown documents, Mermaid diagrams, or plan files as formatted HTML with syntax highlighting, math formulas, Mermaid, scroll animations, and dark mode. One skill, one script, three input shapes.

When to Use

• User asks to "view as HTML", "render in browser", "preview as a web page"
• User asks for a diagram (flowchart, sequence, architecture, ER, state, …)
• User references a plan by name (resolve from ~/.claude/plans/)
• Content contains complex tables, Mermaid, or math formulas
• Proactive: terminal output would contain a table with 4+ rows or 3+ columns
• Proactive: comparison, audit, feature matrix, or status report as ASCII
• Proactive: conversation output would exceed ~50 lines of structured content

When NOT to Use

• Short content (<20 lines) that renders fine in terminal
• User explicitly wants terminal/text output
• User is asking to edit or modify the content, not view it
• Simple diagrams (2–3 nodes with obvious relationships)

Input Shapes → Workflow

Shape A: file path

User gave an absolute/relative path to a markdown file.

bash "${CLAUDE_PLUGIN_ROOT}/lib/render.sh" "{file_path}" "doc-{name}"

Shape B: plan name (bare name, no path separator, no .md)

List available plans or resolve by name against ~/.claude/plans/:

INPUT="$ARGUMENTS"
PLANS_DIR="$HOME/.claude/plans"

if [ -z "$INPUT" ]; then
    echo "Available plans in $PLANS_DIR:"
    ls -t "$PLANS_DIR"/*.md 2>/dev/null | head -20 | xargs -n1 basename | sed 's/\.md$//' | sed 's/^/  - /'
elif [ -f "$INPUT" ]; then
    DOC_FILE="$INPUT"; DOC_NAME=$(basename "$DOC_FILE" .md)
    bash "${CLAUDE_PLUGIN_ROOT}/lib/render.sh" "$DOC_FILE" "doc-$DOC_NAME"
else
    DOC_FILE="$PLANS_DIR/$INPUT.md"
    [ -f "$DOC_FILE" ] && bash "${CLAUDE_PLUGIN_ROOT}/lib/render.sh" "$DOC_FILE" "doc-$INPUT" \
      || { echo "Plan not found: $INPUT.md"; ls -t "$PLANS_DIR"/*.md 2>/dev/null | head -10 | xargs -n1 basename | sed 's/\.md$//' | sed 's/^/  - /'; }
fi

Shape C: inline content or Mermaid code

Write the content (or Mermaid wrapped in a ```mermaid fence) to a temp markdown file, then render.

For inline markdown, write to /tmp/viz-doc-{timestamp}.md.

For bare Mermaid code, wrap as:

# {Diagram Title}

```mermaid
{mermaid code}
```

…write to /tmp/viz-diagram-{name}.md, then:

bash "${CLAUDE_PLUGIN_ROOT}/lib/render.sh" "/tmp/viz-diagram-{name}.md" "diagram-{name}"

Generating Mermaid From Scratch

When the user requests a diagram without providing the code:

1. Pick a diagram type (see references/diagram-types.md for syntax)
2. Keep it focused: 5–15 nodes, descriptive labels <30 chars, no-space IDs
3. If requirements are too broad, suggest splitting into multiple diagrams

Output

The render script prints the output HTML path (under /tmp/viz/{project}/) and opens it in the default browser. Report the path to the user.

Recipes (interactive HTML artifacts)

If the markdown file starts with frontmatter viz: <recipe>, the render script swaps the generic viewer for a recipe-specific interactive template. Recipes treat markdown as the canonical source: the HTML reads from it on load and exports a roundtrippable markdown back to the clipboard on Export.

Use a recipe when the user wants an output they will iterate on (mark items as done/wontfix, filter, edit fields), not just read.

Available recipes:

• pr-review — severity-grouped finding cards with status badges, inline-editable metadata, and severity filters. See references/recipes/pr-review.md for the markdown structure spec.

Workflow:

1. Author the markdown with the recipe's frontmatter and structure.
2. bash "${CLAUDE_PLUGIN_ROOT}/lib/render.sh" <file.md> <output-name>
3. User edits in HTML → clicks Export → updated markdown is on clipboard.
4. User pastes back to chat → agent overwrites the source .md → re-render.

Markdown without viz: frontmatter falls through to the generic viewer unchanged.

The recipe Save endpoint listens on port 18090 by default. If that port is taken (e.g. by another local service), set VIZ_PORT=<port> in the environment before invoking render.sh.

References

• Diagram type syntax: references/diagram-types.md
• Recipe specs: references/recipes/
• Mermaid docs: https://mermaid.js.org/
• Live editor: https://mermaid.live