fengyunzaidushi/markmap-skill

Content-First Markmap Mind Map

Organize projects, documents, codebases, or concepts into Markmap-renderable Markdown, and validate the structure or generate HTML as needed.

Core Rules

• Whole-to-part: The root node describes the object and purpose, then unfolds real main concepts, flows, modules, and details.
• Organize the map using the material itself. Do not invent generic classification headings to cater to beginners.
• Remove purely categorical headings such as "Project Orientation", "Mechanism", "Development Landscape", "Core Concepts", "Main Modules", "Use Cases", unless those terms are part of the original material.
• Each node can have at most 7 direct children; preferably around 5, only extend to 6-7 when the content genuinely requires it.
• Do not flatten more than 7 branches just because there is a lot of real content; group by real sub-themes within the material.
• If a level seems to need more than 7 branches, first merge similar items, then reorder as "overall → group → local details".
• Analogies are optional. Only use them if they truly aid memory, and place them after the content label; do not let the analogy become the node's main body.
• Do not fabricate certainty. Before summarizing a repository, read the README, documentation, package config, tests, source directory, and local scripts.
• Keep the map concise. Use short content labels for nodes, and add a brief evidence-based note only when necessary.

When handling complex repositories or long documents, first read references/analogy-structure.md.

Workflow

1. First, examine the material.
   • Repository: read README, AGENTS.md/CLAUDE.md, package config, documentation, and top-level directory.
   • Document: identify the topic, claims, sections, recurring concepts, and terms that need memorization.
2. Draft the Markdown from whole to parts.
   • Use one H1 root heading to describe the object.
   • Use ## to unfold the real backbone of the content — do not use "categorical buckets for the reader".
   • Prefer real concepts, systems, flows, file paths, APIs, claims, or responsibilities from the material for each node.
   • Continue expanding only when details aid understanding; do not force extra branches.
   • Each parent node has at most 7 direct children, preferably around 5; if more than 7, regroup by real sub-themes.
3. Validate the Markdown with a script:

python3 ~/.codex/skills/markmap-analogy-mindmap/scripts/validate_and_render.py input.md --validate-only

4. When HTML delivery is needed, render with Markmap:

python3 ~/.codex/skills/markmap-analogy-mindmap/scripts/validate_and_render.py input.md -o output.html

5. If validation fails, fix the map structure first. Do not bypass the "generic headings" and "too many branches per level" checks unless the user explicitly requests a non-standard map.

Markmap Rendering

The script tries (in order):

1. markmap
2. npx --yes markmap-cli
3. A prebuilt CLI located at /root/markmap

If no renderer is available, deliver the validated Markdown as output and note that HTML was not generated.

Output Requirements

• After creating the files, return the paths of .md and .html.
• State which sources were examined and the results of the validation/rendering commands.
• Unless the user asks to modify the source repository, only read the source materials.
• For Chinese users, output the mind map in Chinese by default; use English only for commands, paths, APIs, package names, and terms that must remain in English.