0.2.0

About this package#

A mind map the way it grows on a whiteboard: one term in the middle, the headings to its right and left, the examples behind them. brainroot sets such a map from a nested list. Every branch gets a colour it passes down to its leaves; the boxes are filled with a lighter shade of that colour, the connections run as soft curves.

The package builds on CeTZ. Boxes are measured, so they follow the font of the surrounding document.

Quick start#

#import "@preview/brainroot:0.2.0": brainroot, branch

The simplest input is a list: every item becomes a node, indented items its children.

#brainroot(title: [Forms of energy])[
  - Kinetic energy
    - Motion
    - Wind
  - Elastic energy
    - Stretching
  - Thermal energy
    - Fire
  - Potential energy
    - Gravity
    - Weight
]

Three marks in the list carry node options: a Typst label <name> at the end gives the node its id for cross-links, an item that is nothing but *bold* highlights it, one that is nothing but _emphasised_ becomes a gap.

#brainroot(title: [Photosynthesis], links: (connect("light", "dark", label: [ATP]),))[
  - Light reaction <light>
    - *Photolysis*
    - _ATP_
  - Dark reaction <dark>
    - Calvin cycle
    - _Glucose_
]

To describe a branch in more detail, write it as branch(label, ..children). A child is then either content, a leaf, or another branch(...). A list and branch calls may stand side by side; without title the first argument is the root.

Sides and colours#

Left alone, brainroot distributes the branches itself: the first ones go right until the right side is about half as tall as all branches together, the rest go left. side: left or side: right pins a branch, color gives it its own colour instead of the next one from the palette.

#brainroot(title: branch([Photosynthesis], fill: green.lighten(50%)), spacing: (max-width: 3cm),
  branch([Light reaction], branch([Photolysis], [Water is split]), [ATP], side: right),
  branch([Dark reaction], [Calvin cycle], [Glucose], color: purple),
  branch([Requirements], [Light], [Water], [CO₂], side: left),
)

Nodes#

A label is content: formulas, images and links work as they do anywhere. An icon sits left of the label or, with icon-at: "top", above it. The root is a branch too: title: branch([Energy], icon: ..., fill: ...). Per node you can set fill (a colour, or none for a ring), ink, and mark: true for a highlighted key term.

#brainroot(title: branch([Energy], icon: text(size: 1.6em, emoji.bolt), icon-at: "top"),
  branch([Formula], [$E = 1/2 m v^2$], [$E = m g h$], icon: emoji.abacus),
  branch([Link], link("https://typst.app")[typst.app]),
  branch([Important], branch([Key term], mark: true), branch([Ring], fill: none), branch([Red], ink: red)))

Gaps and the solution#

blank: true on a branch draws its box empty, at full size. blanks:
"leaves", "branches" or "all" does that for a whole class of nodes. The same map with solution: true fills the gaps in, with solution-ink in a colour that makes the answers stand out. Task and solution come from one source.

#brainroot(title: [Forms of energy], blanks: "leaves", map)
#brainroot(title: [Forms of energy], blanks: "leaves", solution: true, solution-ink: red, map)

Edge labels#

edge-label puts a small label on the edge that leads to a node. That turns the mind map into a probability tree or a decision tree. equal: true on a branch makes its children the same size, "width" or "height" in one direction; on the root it applies to the first level.

#brainroot(title: branch([Start], equal: true), layout: "right", theme: "outline", palette: "plain",
  branch([Heads], branch([Heads], edge-label: $1/2$), branch([Tails], edge-label: $1/2$), edge-label: $1/2$, equal: true),
  branch([Tails], branch([Heads], edge-label: $1/2$), branch([Tails], edge-label: $1/2$), edge-label: $1/2$, equal: true))

Cross-links, braces, clouds#

A mind map is a tree; the ideas in it rarely are. id names a node, connect(from, to) in links draws a curve between two nodes over the map, with label, arrow, dash and bend. The root is called "root". summary puts a labelled brace beyond a node’s children, cloud lays a cloud behind its subtree. Braces and clouds exist in the tree layouts, not in radial and star. arrange: "links" orders the branches and turns children around so that linked nodes come close together; here CO₂ moves next to glucose.

#brainroot(title: [Photosynthesis], arrange: "links",
  links: (connect("light", "dark", label: [ATP, NADPH]), connect("co2", "glucose", label: [C], dash: "dotted")),
  branch([Light reaction], [Photolysis], [ATP], [NADPH], id: "light", cloud: true),
  branch([Dark reaction], [Calvin cycle], branch([Glucose], id: "glucose"), id: "dark", summary: [products]),
  branch([Requirements], [Light], [Water], branch([CO₂], id: "co2"), summary: [from outside]))

Points and building up#

points on a branch counts for grading a map; brainroot-points with the same arguments adds them up, show-points: true shows them as a badge on the box. reveal draws only the first branches, or those for which a function of the index is true. The layout stays put, so a map builds up branch by branch, in typstage with build(from => brainroot(..., reveal: i => from(i + 2)), steps: 5).

#brainroot(title: [Forms of energy], reveal: 2, show-points: true,
  branch([Kinetic energy], branch([Motion], points: 1), branch([Wind], points: 1)),
  branch([Elastic energy], branch([Stretching], points: 2)),
  branch([Thermal energy], [Fire]))

Layouts#

layout decides how the branches sit around the root. both is the two-sided map from above, right and left put everything on one side. down and up set a tree from top to bottom or the other way round, like an org chart. radial is the classic Buzan mind map: the whole tree fans out from the root, every subtree in a sector of its own. star only puts the branches on a circle around the root, their subtrees grow horizontally outward. fishbone is the Ishikawa cause-and-effect diagram: the root as the head of a spine, the branches as ribs alternating above and below, the leaves along the ribs; two levels below the root. layout also takes a dictionary: (kind: "down", align-levels: true) puts every level on one line in the tree layouts, as in an org chart; start is the angle of the first branch in radial and star. Distances live in spacing, see spacing-defaults.

#brainroot(title: [Forms of energy], layout: "down", map)

#brainroot(title: [Forms of energy], layout: "radial", map,
  branch([Pressure]), branch([Radiation], [Light]))

#brainroot(title: [Forms of energy], layout: "star", map,
  branch([Pressure]), branch([Radiation], [Light]))

#brainroot(title: [Bad grade], layout: "fishbone", theme: "outline",
  branch([Preparation], [started late], [no plan], [no practice]),
  branch([Lessons], [absent], [no notes]),
  branch([Exam], [time misjudged], [task misread]),
  branch([Setting], [noise], [tiredness]))

#brainroot(title: [Substances], layout: (kind: "down", align-levels: true), theme: "blocks",
  branch([Pure substances], branch([Elements], [Metals], [Non-metals]), [Compounds]),
  branch([Mixtures], [homogeneous], [heterogeneous]))

With radial and star the first branch sits at start (default 60deg), the others follow clockwise. With radial the children share their parent’s sector, weighted by the size of their subtrees, and sit on the ring of their depth; the rings begin at spacing.root and are stretched until no two boxes overlap.

Palettes#

palette provides the colours of the branches and the root; the boxes get the branch colour lightened by tint. Ten palettes are built in, all shown with the same map:

poster#

Bright and bold, like markers on a whiteboard. The default.

#brainroot(title: [Forms of energy], palette: "poster", map)

pastel#

Soft, muted tones.

#brainroot(title: [Forms of energy], palette: "pastel", map)

grayscale#

Greys only, for black-and-white printing.

#brainroot(title: [Forms of energy], palette: "grayscale", map)

mono#

One blue in varying lightness.

#brainroot(title: [Forms of energy], palette: "mono", map)

plain#

One dark ink for everything, as if drawn with a fountain pen.

#brainroot(title: [Forms of energy], palette: "plain", map)

earth#

Earth tones: terracotta, ochre, olive, sand.

#brainroot(title: [Forms of energy], palette: "earth", map)

ocean#

Sea: turquoise, teal, sea green.

#brainroot(title: [Forms of energy], palette: "ocean", map)

sunset#

Evening sky: red, orange, pink, violet.

#brainroot(title: [Forms of energy], palette: "sunset", map)

forest#

Forest: green with a little brown.

#brainroot(title: [Forms of energy], palette: "forest", map)

neon#

Loud, saturated colours.

#brainroot(title: [Forms of energy], palette: "neon", map)

Your own colours go in as an array, palette: (red, blue, green), or with a root colour as a dictionary, palette: (colors: (red, blue), root: black). A palette may also set ink, ink-dark, ink-light and ink-threshold, the text colours; base takes a built-in palette as the starting point: palette: (base: "ocean", root: black). The root itself is coloured by title: branch([...], fill: ...).

Themes#

A theme decides how boxes and edges look; the colours still come from the palette. Ten are built in:

soft#

Pastel boxes with rounded corners, soft S-curves. The whiteboard original.

#brainroot(title: [Forms of energy], theme: "soft", map)

outline#

White boxes with a coloured border, curves.

#brainroot(title: [Forms of energy], theme: "outline", map)

blocks#

Solid square boxes with white text, right angles: org-chart look.

#brainroot(title: [Forms of energy], theme: "blocks", map)

lines#

No boxes: the text sits on its coloured line and the edges flow into it. The classic mind map.

#brainroot(title: [Forms of energy], theme: "lines", map)