markmap-analogy-mindmap

Content-First Markmap Mind Maps

Organize projects, documents, codebases, or concepts into Markdown that can be rendered with Markmap, and validate the structure and generate HTML when needed.

Core Rules

• Whole before parts: the root topic states the object and purpose, then expand real main concepts, processes, modules, and details.
• Organize the mind map using the material itself. Do not invent vague category headings just to accommodate beginner readers.
• Remove headings that only serve as categories, such as "project positioning", "operating mechanism", "development landscape", "core concepts", "main modules", "use cases", etc., unless these words are already part of the source text.
• Each node defaults to at most 5 direct child nodes; this is a default hard constraint, not a suggested value.
• Only when the user explicitly states "more branches are allowed / more than 5 is allowed / at most N" may the limit be raised; even after raising it, restraint should still be exercised.
• Do not flatten more than 5 branches just because there is a lot of real content; continue grouping by the real subtopics in the material.
• If a certain level appears to need more than 5 branches, first merge similar content, then rearrange according to "whole -> grouping -> local details".
• Analogies are optional. Use them only when 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, first look at the README, docs, package configuration, tests, source directory, and local scripts.
• Keep the mind map concise. Use short content labels for nodes, and add one evidence-based explanatory sentence when necessary.

When handling a complex repository or long document, first read references/analogy-structure.md。

Workflow

1. First inspect the material.
   • Repository: first look at README、AGENTS.md/CLAUDE.md, package configuration, docs, and top-level directories.
   • Document: first find the topic, claims, chapters, recurring concepts, and terms that need to be remembered.
2. Draft the Markdown from whole to parts.
   • Use one H1 root heading to state the object.
   • Use ## to expand the real content backbone, not "category buckets for readers".
   • For each node, prefer writing the real concepts, systems, processes, file paths, APIs, claims, or responsibilities from the material.
   • Continue expanding only when details help understanding; do not force branches just to fill them out.
   • Each parent node defaults to at most 5 direct child nodes; when there are more than 5, regroup by real subtopics.
3. Validate the Markdown with a script:

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

Only if the user explicitly allows more branches may a higher limit be specified:

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

1. When HTML delivery is needed, render the Markmap:

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

1. If validation fails, fix the mind map structure first. Unless the user explicitly requests a non-standard mind map, do not bypass the "vague categories" and "too many hierarchical branches" checks.

Markmap Rendering

The script will try in order:

1. markmap
2. npx --yes markmap-cli
3. Local /root/markmap built CLI

If no renderer is available, use the validated Markdown as the deliverable and state that HTML was not generated.

Output Requirements

• After creating the file, return .md and .html Path.
• State which sources were checked, and the results of verification/rendering commands.
• Unless the user requests modifying the source repository, treat source materials as read-only.
• For Chinese users, output mind maps in Chinese by default; use English only when commands, paths, APIs, package names, or terminology must be kept in English.