# Mermaid mind maps from slides, and parentheses that eat text

The other study skills in my network security course repo ([Study Skills](/articles/study-skills)) mostly answer in chat. `mind-map` is the one that draws. It outputs Mermaid, which renders on GitHub and in VS Code's Markdown preview (with a Mermaid extension) and diffs as plain text.

Most of the skill is choosing the right diagram. A `mindmap` is for "what's in this chapter". A protocol or an attack, with messages going between sender, receiver and attacker, is almost always a `sequenceDiagram`. A process or a decision is a `flowchart`. The map itself is built from the slides: slide titles become the 5 to 8 main branches, each node is a term or a short phrase in the slides' wording, and nothing goes in that the slides don't cover unless it's marked as extra.

## What a test render showed

The skill warns that parentheses, quotes and colons in node text break the mindmap parser, and says to wrap such text in `["..."]`. The cases went through mermaid-cli 11.12.0 while I was writing this.

Parentheses don't break the parser. They parse as a [node shape](https://mermaid.js.org/syntax/mindmap.html#different-shapes), with no error. This renders without an error, and the first node reads "keyed":

```mermaid
mindmap
  root((Hashing))
    MAC (keyed)
    Note: no key
```

`MAC (keyed)` became a rounded node labelled `keyed`, and the word MAC was gone. The colon in the second node rendered fine. Wrapped, both come out as written:

```mermaid
mindmap
  root((Hashing))
    a["MAC (keyed)"]
    b["Note: no key"]
```

Square brackets do the same: `MAC [keyed]` also renders as `keyed`. The wrapped form works without an id too, as `["MAC (keyed)"]`. So the rule holds for parentheses and brackets, for a quieter reason than the skill gives, and colons are fine in this version. Quotes weren't tested. One of the skill's output rules covers all of it: if you haven't rendered it, say the render is unchecked.

Save it as `.claude/skills/mind-map/SKILL.md` and change the slide path to yours. In the copy below the syntax note is corrected from the test, the render rule asks for an actual render with `mmdc`, and two small lines are cut.

````markdown
---
name: mind-map
description: Use when the user asks for a mind map, concept map, overview diagram or flow diagram of a lecture, chapter or topic. Produces Mermaid (mindmap, flowchart, sequence) that renders on GitHub and in VS Code, saved as a .md file next to the slides when asked.
---

# Mind maps and diagrams

Mermaid in a fenced block. It renders on GitHub and in VS Code's Markdown preview (with the
Mermaid extension), needs no build step, and diffs cleanly.

## Pick the diagram type

| What you're showing | Use |
|---|---|
| A chapter or topic broken into parts | `mindmap` |
| A process, a decision, how data flows | `flowchart LR` or `TD` |
| Messages between sender, receiver, attacker | `sequenceDiagram` |
| How concepts depend on or differ from each other | `flowchart` with labelled edges |

Protocols and attacks are almost always better as a `sequenceDiagram` than a mind map. Use a
mind map for "what is in this chapter" and for revision.

## Build it from the slides

1. Read the slides: `pdftotext -layout Lectures/<chapter>/slides.pdf -`. Slide titles are the
   main branches.
2. 5 to 8 main branches, 2 to 5 children each, 3 levels deep at most. If it needs more, split
   into two maps.
3. Node text is short: a term or a 2 to 4 word phrase, not a sentence. The explanation goes
   in chat, not in the node.
4. Use the slides' wording for terms so the map matches the exam.
5. Don't add a branch the slides don't cover unless it is marked as extra.

## Mermaid syntax that works

Mindmap is indentation based. The root is one node. Parentheses and square brackets in node
text parse as node shapes and silently swallow words (`MAC (keyed)` renders as `keyed`, no
error), so quote such text: `["MAC (keyed)"]`.

```mermaid
mindmap
  root((Message Authentication))
    Goals
      Source is who it claims
      Not altered
      Sequencing
      Timeliness
    Functions
      Message encryption
      MAC
      Hash function
    Digital signature
      Adds non-repudiation
```

Sequence diagram for a protocol:

```mermaid
sequenceDiagram
    participant A as Sender
    participant B as Receiver
    A->>B: M, MAC(K, M)
    B->>B: recompute MAC(K, M) and compare
```

## Output

- In chat by default: show the block and a two-line walk-through of how to read it.
- When asked to save: `Lectures/<chapter>/mindmap.md` with a title line and the block(s).
- Render it before saying it renders:
  `npx -p @mermaid-js/mermaid-cli mmdc -i map.mmd -o map.svg`, then read the text in the SVG.
  If you can't, say the render is unchecked.

## Don't

- Make decorative maps with 40 nodes.
- Add colors or styling unless asked.
````

see also: [Study Skills](/articles/study-skills)
