/mindmap-render

name: mindmap-render
description: Generate beautiful, high-resolution mindmaps from Markdown unordered lists. Outputs interactive HTML, HD PNG, and PDF with colorful branch themes.

When to use this skill

Use this skill when the user asks to:

• Create a mindmap from a topic or data.
• Convert a Markdown outline into a visual mindmap image or PDF.
• Generate a colorful, presentation-quality mindmap with auto-export to PNG/PDF.
• Build a structured outline (unordered list) and then render it as a mindmap.

Prerequisites

Assume the runtime environment already has Python 3.10+, Playwright, and Chromium installed (they are provisioned in the container). **Do not proactively run `pip install` or `playwright install`** — just run the render script directly. Only if the first run fails with a clear missing-dependency error (ImportError, missing-browser error, etc.), then repair the environment:

pip install -r scripts/requirements.txt
playwright install chromium

and retry. Never install speculatively before a failure is observed.

Workflow

Step 1 — Determine input source

Ask the user (or infer from context):

• **Topic**: What is the central theme?
• **Data source**: Do they already have a Markdown file, or should you research and write one?
• **Source fidelity vs synthesis** — a spectrum, not a binary. The more specifically the request points to a **named existing artifact** (a particular book's table of contents (ToC), a particular course's syllabus, a specific spec or documentation structure, a numbered chapter list), the more you should **reproduce the source's real structure verbatim** — preserve original labels and numbering, follow the source's natural depth, and add NO fabricated descriptions. The more the request is a **broad topic** with no single canonical source, the more the structural targets below apply. Most requests sit somewhere on this spectrum; judge and lean accordingly.
• **Theme**: `air` (light blue glow + white cards, default), `editorial` (warm paper + jewel-tone branches), `midnight` (deep black + neon accents), or `zen` (soft misty background + muted pastels).
• **Language**:
• If the user explicitly specifies a language (e.g. "in English", "in Japanese"), use that language for all node text (labels + layer-5 descriptions).
• Otherwise, match the language of the user's request; default to English when the request language is unclear.
• Do not translate proper nouns, model names, or established technical terms — preserve them inline.

**Default structural targets — for synthesis work only.** These do NOT apply when you are faithfully reproducing a named source (in that case, follow the source's actual shape). They also yield to any numbers the user gives explicitly.

• **1 root** + **6–10 top-level branches** (default aim: ~9).
• **Maximum depth = 5 layers** (root → branch → subtopic → item → leaf-with-description). Layer 5 is reserved for the **important, information-dense** nodes — it is **not** a mandatory floor for every path.
• **Layer-5 leaves (when present) MUST carry a substantive description** — around **200 Chinese characters** (or ~150 English words if the mindmap is in English), roughly 2–4 sentences — that explains mechanism, why it matters, quantitative detail, or a concrete example. A one-line label is not enough at layer 5; if you cannot write ~200 Chinese characters of real content, the node does not belong at layer 5.
• Intermediate nodes (layers 2–4) stay concise (1–10 words) and may themselves be terminal leaves when that is the right level of detail.
• **Asymmetry is required, not a flaw.** Branches should be weighted by importance and information value, *not* padded for visual symmetry:
• Pillar branches (where the real substance lives) should go deep and wide, with many children and rich layer-5 descriptions.
• Supporting / well-known branches can stop at layer 2 or 3. Do not expand common knowledge the target reader already owns, and do not invent filler children just to match sibling counts.
• When deciding "expand or stop," ask: *Would a knowledgeable reader learn something here?* If no, prune.
• The hierarchy is intentionally irregular. In Step 2c, report the shape honestly rather than forcing every branch to layer 5.

If the user gives different numbers, use theirs; otherwise treat the defaults above as **guidance with judgment** — breadth/depth targets are firm, but per-branch expansion is deliberately uneven.

Step 2a — User provided a Markdown file

If the user already has a `.md` file, note its path and proceed to Step 3.

Step 2b — Generate the Markdown outline yourself

**CRITICAL: If the user has NOT provided a `.md` file, you MUST perform web research BEFORE writing the outline.** Do not rely solely on internal knowledge.

1. **Research** (mandatory): Use `WebSearch` to find authoritative, high-quality sources:

• Official book table of contents (publisher's catalog, Douban Books listing).
• Wikipedia structured sections.
• Academic course syllabi or reputable blog series.
• Official documentation / white-paper outlines.
• Recent industry reports, survey papers, or conference proceedings (e.g. NeurIPS, ICML, JPMorgan Quantitative Research).

**Fail loudly if the authoritative source cannot be found.** When the user names a specific artifact (a particular book, edition, course, spec) and repeated searches do not surface its real ToC / syllabus / structure, **STOP** and tell the user: *"I couldn't find the authoritative structure of [X]. Please paste the ToC, confirm the edition/title, or allow me to produce a synthesized overview instead."* **Never invent chapter/section structure to fill the gap.** This is the single most important rule of this step.

2. **Write the outline** — choose the mode based on Step 1's fidelity-vs-synthesis judgment:

**a) Faithful reproduction** (user pointed to a specific named artifact and you located its real structure): copy the