From 935447f0fbbb9304378974b277f9cf2f0ea13252 Mon Sep 17 00:00:00 2001 From: Jaderson Vargas Date: Tue, 9 Jun 2026 18:11:18 -0300 Subject: [PATCH 1/3] SKILL.md/README: resolve helper paths from the skill base dir, not the CWD The usage snippets said sys.path.insert(0, scripts), which only works when the working directory happens to be the skill root. In a real session the CWD is the user's project, so the first invocation hit an ImportError before self-correcting. Co-Authored-By: Claude Fable 5 --- README.md | 10 +++++++--- SKILL.md | 21 +++++++++++++++------ 2 files changed, 22 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 7653ba1..520152e 100644 --- a/README.md +++ b/README.md @@ -42,10 +42,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 +58,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..c49e8fe 100644 --- a/SKILL.md +++ b/SKILL.md @@ -93,15 +93,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 +127,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) ``` From a6e34ec3c852145ca63942f455a7ec54b0a808e7 Mon Sep 17 00:00:00 2001 From: Jaderson Vargas Date: Tue, 9 Jun 2026 18:17:02 -0300 Subject: [PATCH 2/3] SKILL.md: trigger-optimized description + 'When to use this skill' section Description now leads with the outcome (offline single-file map), names more of the phrasings users actually type (concept map, visualize the structure of a doc, summarize notes as a navigable tree, clickable outline), and nudges activation even when 'mind map' is not said. The new section doubles as the marketplace's required 'When to Use'. Co-Authored-By: Claude Fable 5 --- SKILL.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/SKILL.md b/SKILL.md index c49e8fe..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 From 758ed6e1781f69364772eabd8617d1f957717f4a Mon Sep 17 00:00:00 2001 From: Jaderson Vargas Date: Tue, 9 Jun 2026 18:17:04 -0300 Subject: [PATCH 3/3] GitHub Pages live demo (docs/) + README link docs/index.html is a real build_html output (self-contained, offline) of docs/demo.md, served via Pages from master:/docs. Browser-verified: root + 6 branches render, full toolbar incl. SVG/PNG export. Co-Authored-By: Claude Fable 5 --- README.md | 2 + docs/demo.md | 57 ++++++++++++ docs/index.html | 227 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 286 insertions(+) create mode 100644 docs/demo.md create mode 100644 docs/index.html diff --git a/README.md b/README.md index 520152e..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: 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 @@ + + + + + + + + + + + +