Write a story
A story is an animated, step-through diagram on the /docs site: stops joined by tracks,
tokens that move along a track, and one caption per step. It is data: one file,
docs/stories/<name>.json. You never touch the player (fleet/internal/docs/assets/stories.js).
Put one in a page
Write the marker on the line right before the Mermaid block, and keep the Mermaid block:
<!-- story: sign-in-device-flow -->
On GitHub the Mermaid shows. On /docs the story is drawn in its place. The Go test
(make -C fleet check) fails when a marker has no file, when a Mermaid block has no marker, and when a
story file is not valid.
The file
{
"w": 1000, "h": 360,
"alt": "what the picture shows, one sentence",
"zones": [{"x": 20, "y": 20, "w": 460, "h": 300, "label": "node-a"}],
"lanes": ["cli", "server"],
"stops": {
"cli": {"x": 130, "y": 60, "color": "you", "label": "fleet CLI", "sub": "on the laptop", "side": "up"}
},
"tracks": [{"from": "cli", "to": "server", "bend": [0, 0, 0, 0]}],
"steps": [
{"caption": "One plain sentence. `code` in backticks.", "label": "text on the token",
"moves": [["cli", "server"]], "bad": ["server"], "fix": []}
]
}
w(default 1000) andhare the picture size. The page scales it to the screen, so it never scrolls sideways. A phone shows it small: keep labels short, and prefer fewer stops.stops:x,y,color(you,agent,worker,server),label,sub(\nbreaks a line),sidewhere the text sits (downdefault,up,left,right),anchor(start,middle,end) to shift it.tracks: a line between two stops. It has a direction: a move goes alongfromtoto. A reply needs its own track the other way (give both abendso they do not lie on top of each other, for example[0,-30,0,-30]and[0,30,0,30]).bendis[dx1, dy1, dx2, dy2], the two curve handles relative to the ends.steps: each has acaption(what happens, in plain words) and optionalmoves(each must be a track),label(a short message on the first token),bad(stops turn red from this step on) andfix(clears them). A step with no moves just shows the caption.lanes: stops that drop a dashed life line downward. With stops placed at the sameyin a row and more stops below them (one per message), this gives the look of a sequence diagram.zones: a labelled box behind stops, for a machine, a cluster or a fleet.
A diagram that has no sequence (a layout of parts) is a story of one step, or a few steps that light up the parts one group at a time.
Rules
- Say only what the code does. Mark a planned thing as planned in the caption, with its issue.
- Name roles, not people or companies: "chief", "orchestrator", "node-a".
- The Go test estimates the width of every label. It fails when a label overlaps another label, a
stop or a track, or leaves the picture. Fix it by moving the stop, changing
side, or shortening the text, not by loosening the test. - Open the page and look at it. Try the first step and the last at phone width.
- Preview: run a scratch server that calls
docs.Handler.#step=3on the address opens every story on step 3.