Maps

#What a map is

A map is a collection of internotes drawn as a graph: each internote is a box, and a line joins two of them where one references the other. An internote can belong to any number of maps; adding it to one neither moves nor copies it. A map has its own title, description, tags and visibility.

A map is made in Studio: Create, then Map, gives it a title, description, tags and visibility and picks its first internotes, which can be none. On the map itself, Edit opens the map editor, where Add Internote brings in more. A map can instead take its members from a folder of a connected repository (A folder of internotes as a map).

The lines are the references written with internote and !internote between the map's members (References as map edges); nothing else draws one.

A reader opening a map gets:

• the graph, which pans and zooms, and a box per internote that opens it;
• on each box, signed in, a mark for an internote they have finished or bookmarked;
• a Glossary: every definition with a term in the members they may read, sorted by term, each linking to the definition in its internote;
• a read time, the sum of the members' estimated reading times.

#A folder of internotes as a map

A map can follow a folder of a connected repository. Every internote under the folder, at any depth, that has published at least once is a member, and each push adds and removes members to match. A nested folder can have a map of its own; an internote under both is a member of both. Only membership comes from the repository: the map's title, description and arrangement stay on the platform. Connecting a map to a folder is done from the map's details panel, as Publishing from GitHub describes.

The folder gives the map its members; the references between them give it its edges.

#References as map edges

When an internote is published, each reference in it is recorded as a connection to its target. connect is on by default; !connect makes the reference a link and nothing else. A reference to the internote itself is not recorded, and several references to one target are one connection. Saving a draft changes nothing: the connections are the published copy's.

scene{
    internote(ref: ./sampling-distributions.chalk)

    The same statistic in a paired design is in !internote(ref: ./paired-designs.chalk; !connect).
}

A map draws a connection between two of its members as an edge; a connection to an internote outside the map draws nothing. Above, the first reference connects and the second does not, so on a map holding all three internotes only the first is an edge.

The Tree and Burst presets (Arranging a map) read the edges as a tree. An internote sits below the internotes that reference it, and one referenced from several is placed under one of them, with the other edges drawn across. Where references form a cycle, the edge that closes it is drawn but does not shape the tree. An internote's children start in the order its references are written: the tree layout keeps that order unless another crosses fewer edges, and the burst layout places the root's children clockwise from the top in that order.

How to choose which internotes reference which is in Shaping a map from its subject.

#Arranging a map

A map nobody has arranged is drawn in the Clusters preset, worked out afresh from its references each time it is opened. Arranging it fixes every internote where the author leaves it: on the map, Edit opens the map editor, where Layouts applies a preset (the number keys 1 to 6 pick one while the menu is open), internotes can be dragged, and Save stores the positions. Every position, from a preset or a drag, snaps to a grid half a box's height square. An internote that joins an arranged map afterwards is placed in a row beneath the arrangement until the map is saved again.

The six presets, each read from the references alone:

• Clusters lets every reference pull its two internotes together while all of them push apart, starting from the Burst arrangement with the root held at the centre, then squashes the result vertically.
• Tree puts the root on the top row and each internote one row below the lowest internote that references it, under one of its referrers, with its other lines drawn across.
• Burst puts the root in the middle with the internotes it references pointing outward, clockwise from the top, each branch laid out as a small tree along its direction.
• Layered puts each internote in the column of its longest chain of references from a start, so it sits right of everything that references it and every line runs rightward.
• Radial deals the internotes round one ring, clockwise from the top, each followed by the branch it references; internotes with no references come last.
• Linear stacks them in one column, each below every internote that references it; internotes caught in a cycle of references go at the bottom.

The same nine internotes in each preset: