diff --git a/README.md b/README.md index 7653ba1..4fd25dd 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,8 @@ A Claude Code skill that turns hierarchical Markdown into an **interactive SVG m ![Install the skill, ask Claude to turn an outline into a mind map, and open the interactive result](assets/demo.gif) +**[▶ Live demo](https://jaderson-bit.github.io/mindmap-markmap-viewer/)** — an actual generated map, in your browser: pan, zoom, fold branches, export SVG/PNG. The page is one self-contained HTML file, exactly what the skill produces. + ## Why this exists markmap renders a Markdown outline as a zoomable mind map, but three things need a layer on top to be genuinely usable: @@ -42,10 +44,14 @@ cp -r mindmap-markmap-viewer ~/.claude/skills/ ## Usage ```python -import sys; sys.path.insert(0, "scripts") +import sys +from pathlib import Path + +SKILL = Path.home() / ".claude" / "skills" / "mindmap-markmap-viewer" # wherever you cloned it +sys.path.insert(0, str(SKILL / "scripts")) from render_markmap import build_html, set_expand_level, filter_markmap -src = open("assets/example.md", encoding="utf-8").read() +src = (SKILL / "assets" / "example.md").read_text(encoding="utf-8") # or your own outline # optional: src, n = filter_markmap(src, "branch b") # search + keep context # optional: src = set_expand_level(src, -1) # expand all open("mindmap.html", "w", encoding="utf-8").write(build_html(src, height=850)) @@ -54,7 +60,7 @@ open("mindmap.html", "w", encoding="utf-8").write(build_html(src, height=850)) Inside Streamlit: ```python -import sys; sys.path.insert(0, "scripts") +sys.path.insert(0, str(SKILL / "scripts")) # SKILL as above from render_markmap import render_markmap, set_expand_level render_markmap(set_expand_level(src, 2), height=850) ``` diff --git a/SKILL.md b/SKILL.md index d5c33c6..a34ac82 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,6 +1,6 @@ --- name: mindmap-markmap-viewer -description: Generate and render interactive mind maps from hierarchical Markdown using markmap.js (white font, search that filters the tree to matches + ancestors + descendants, expand-by-level control). Use when the user wants to turn outline/hierarchical content into a navigable mind map, or asks for a "markmap"/"mindmap" view, optionally embedded in Streamlit. +description: Turn Markdown outlines, notes, docs, or plans into an interactive mind map — a single self-contained HTML file that opens offline anywhere (markmap.js, white-on-dark, zoom/expand/export toolbar, search that keeps matches in context). Use whenever the user asks for a mind map, markmap, or concept map, wants to visualize or diagram the structure of a document or topic, summarize notes as a navigable tree, make an outline clickable or explorable, or embed such a map in Streamlit — even when they don't literally say 'mind map'. --- # Mindmap (markmap) Skill @@ -14,6 +14,14 @@ source.md ──► filter / set expand level (Python) ──► build_html( Helper functions live in `scripts/render_markmap.py`; a minimal source file is in `assets/example.md`; regression tests are in `evals/`. Deeper docs: [`references/internals.md`](references/internals.md) (how the helpers work) and [`references/lessons.md`](references/lessons.md) (real-world lessons + the adversarial counter-review behind the current code). +## When to use this skill + +- The user asks for a mind map, markmap, or concept map of anything. +- Hierarchical content — an outline, notes, a plan, a document's structure, a taxonomy — should become navigable, scannable, or shareable. +- A map must be sent to someone or opened with no setup: the output is one self-contained `.html` that works offline. +- A mind map should be embedded in a Streamlit app. +- An existing markmap renders blank, white-on-white, or truncated — this skill carries the known fixes (§2). + --- ## 1. Source format @@ -93,15 +101,24 @@ When there is a query, keep only nodes that **match** + their **path to the root ## 5. Minimal usage -The helpers live in `scripts/`, so put that directory on the import path first (point it at this skill's `scripts/` folder). +The helpers live in this skill's `scripts/` directory — and the working directory is +normally the **user's project, not this folder**, so a bare `"scripts"` on `sys.path` +won't resolve. Build paths from the skill's base directory (the path announced when +this skill loaded): -Single self-contained file (recommended) — writes the `.md` source of truth and a -fully **inlined** `.html` that opens offline anywhere, with no sibling `vendor/`: ```python -import sys; sys.path.insert(0, "scripts") +import sys +from pathlib import Path + +SKILL_DIR = Path(r"") # announced when the skill loaded +sys.path.insert(0, str(SKILL_DIR / "scripts")) from render_markmap import write_mindmap, apply_presets, set_expand_level, filter_markmap +``` -src = open("assets/example.md", encoding="utf-8").read() +Single self-contained file (recommended) — writes the `.md` source of truth and a +fully **inlined** `.html` that opens offline anywhere, with no sibling `vendor/`: +```python +src = Path("outline.md").read_text(encoding="utf-8") # the user's outline (sample: SKILL_DIR / "assets/example.md") src = apply_presets(src) # fill default markmap options (no override) # optional: src, n = filter_markmap(src, "branch b") # search + keep context # optional: src = set_expand_level(src, -1) # expand all @@ -118,7 +135,7 @@ open("mindmap.html", "w", encoding="utf-8").write(build_html(src, height=850)) Inside Streamlit: ```python -import sys; sys.path.insert(0, "scripts") +sys.path.insert(0, str(SKILL_DIR / "scripts")) # SKILL_DIR as in the setup above from render_markmap import render_markmap, set_expand_level render_markmap(set_expand_level(src, level), height=850) ``` diff --git a/docs/demo.md b/docs/demo.md new file mode 100644 index 0000000..31f9755 --- /dev/null +++ b/docs/demo.md @@ -0,0 +1,57 @@ +--- +markmap: + colorFreezeLevel: 2 + initialExpandLevel: 2 + maxWidth: 380 +--- + +# mindmap-markmap-viewer + +## What it is + +- Markdown outline + - becomes an interactive mind map +- One self-contained HTML file + - opens offline anywhere + - no CDN, no sibling files +- Built on markmap.js + - vendored, pinned versions + +## Toolbar + +- Zoom in / out +- Fit to window +- Expand all / collapse all +- Export + - SVG (vector) + - PNG (2x raster) + +## Search in context + +- Keeps the match +- Plus ancestors + - the path that explains where it lives +- Plus descendants + - the whole matched subtree +- Accent-insensitive + +## Authoring rules + +- 5-8 branches off the root +- 3-6 children per branch +- Labels of 1-3 words + - details go on child nodes +- apply_presets + - fills the frontmatter for you + +## Try it here + +- Drag to pan, scroll to zoom +- Click a circle to fold a branch +- Toolbar is bottom-right + +## Get it + +- github.com/Jaderson-bit/mindmap-markmap-viewer +- Ask Claude Code + - "Install this skill from the repo URL" diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..7da9212 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,227 @@ + + + + + + + + + + + +