Sample 04 — Diagrams for Explaining Ideas

A diagram is useful when the relationship matters more than the sentence order. A mindmap groups ideas, a timeline shows sequence, a comparison separates alternatives, and a flowchart makes a decision visible.

This sample uses an imaginary explanation-writing workflow throughout. Every visualization has editable source, and none of the examples describes a real research project or historical timeline.

Begin with a nested list

A mindmap is an ordinary nested Markdown list inside mindmap. Indentation defines the relationships. The renderer supplies the drawing and keeps a complete text outline.

1
:::mindmap[An explanation worth keeping]{layout="map"}
2
- A useful explanation
3
  - Question
4
    - Name the uncertainty
5
    - State the assumptions
6
  - Evidence
7
    - Work through an example
8
    - Keep the source
9
  - Interpretation
10
    - Explain the connection
11
    - Identify a limitation
12
  - Next step
13
    - Try a counterexample
14
    - Refine the model
15
:::

Try it: select a branch and collapse its children. Search for “counterexample” to find a node even if its branch is closed. Use Fit to bring the visible structure back into view.

When the map has keyboard focus, Up/Down traverses visible nodes, Right expands or enters a branch, and Left collapses or returns to its parent. Space or Enter toggles a selected branch. Search, selection, and collapse are reader navigation; they do not edit the article's Markdown.

Use a tree for a directional hierarchy

The tree layout puts the hierarchy to the right of its root. The same list-based format works for an outline, a decision hierarchy, or a small taxonomy.

1
:::mindmap[Review checklist]{layout="tree"}
2
- Review an explanation
3
  - Meaning
4
    - Claim is explicit
5
    - Terms are defined
6
  - Evidence
7
    - Example can be checked
8
    - Sources can be found
9
  - Presentation
10
    - Labels are readable
11
    - Alternatives remain accessible
12
:::

Readers can change Map/Tree in the controls. Expanded viewing opens a dedicated dialog and retains the current selection and layout. The More menu offers depth and branch controls, SVG/PNG export, and a copy of the complete Markdown outline.

On touch screens, ordinary scrolling continues through the article. Enable Explore map when you want to pan or pinch inside the visualization. The text outline is also a useful way to read a larger map without navigating its canvas.

Make a sequence visible with a timeline

A timeline uses a list rather than a separate JSON language. Each item needs enough context to stand on its own.

1
:::timeline[Four passes through an explanation]
2
- **Question** — Describe the uncertainty in one sentence.
3
- **Sketch** — Connect a model to a simple example.
4
- **Check** — Look for an assumption or counterexample that changes the result.
5
- **Revision** — Keep the supported claim and record the remaining question.
6
:::

This is an authored process timeline. The site's Archive is different: it is generated from publication dates and does not need a Markdown timeline component.

Compare alternatives side by side

Use comparison when the reader needs to weigh alternatives. Two to four option children are supported. As with rich tabs, the outer fence is longer than its children's fences.

1
::::comparison[Which representation helps here?]
2
:::option[A concise list]
3
- Easy to scan in a fixed order.
4
- Easy to edit, quote, and copy.
5
- Best when the hierarchy is shallow.
6
:::
7

8
:::option[A diagram]
9
- Makes connections and branches visible.
10
- Useful for exploring a relationship.
11
- Needs a readable text alternative.
12
:::
13
::::

The options stack on a phone. A comparison is a reading layout, not a control that chooses a winner for the reader.

Describe a decision with Mermaid

Use a mermaid fence when a diagram needs explicit edges and decisions. This flowchart makes revision a visible branch rather than implying that every first attempt succeeds.

1
```mermaid
2
flowchart LR
3
  Q["Ask one question"] --> M["Make a model"]
4
  M --> T["Try an example"]
5
  T --> D{"Does it explain the result?"}
6
  D -- "Not yet" --> M
7
  D -- "Enough for now" --> N["Write the limits"]
8
```

flowchart LR
  Q["Ask one question"] --> M["Make a model"]
  M --> T["Try an example"]
  T --> D{"Does it explain the result?"}
  D -- "Not yet" --> M
  D -- "Enough for now" --> N["Write the limits"]

The explanation around a diagram still matters. Here, “enough for now” means the article states a limited claim with visible assumptions; it does not mean that a single example proves a general result.

Show an exchange with a sequence diagram

A sequence diagram emphasizes who sends information and in what order. It is useful for software interactions as well as explanatory workflows.

1
```mermaid
2
sequenceDiagram
3
  autonumber
4
  participant R as Reader
5
  participant A as Article
6
  participant N as Notes
7
  R->>A: Follow a claim
8
  A-->>R: Show evidence and a source
9
  R->>N: Record an unanswered question
10
  N-->>R: Suggest the next investigation
11
```

sequenceDiagram
  autonumber
  participant R as Reader
  participant A as Article
  participant N as Notes
  R->>A: Follow a claim
  A-->>R: Show evidence and a source
  R->>N: Record an unanswered question
  N-->>R: Suggest the next investigation

Keep diagrams useful in every reading mode

Mindmaps and Mermaid diagrams are compiled to static light/dark SVG before publication. The reader's device does not need to run Mermaid to draw these examples. Mindmap exploration is a separate enhancement; its static drawing and text outline remain available if that enhancement cannot load.

Mermaid includes a source disclosure so the diagram's description remains inspectable. Mindmaps retain their complete nested outline. Print styles present the diagrams and the full mindmap structure without requiring interactive controls.

When adapting this article, choose the smallest representation that explains the relationship. Give every diagram a sentence that says what to notice, and keep labels short enough to read at ordinary article width.