minidocBlocks
Blocks
The package
@epure/minidoc-blocks gives every minidoc site the same ::: blocks:
callouts, quotes, flows, screen mockups, sequences and state machines. A
site passes one transform to run, and its pages can use them all.
pnpm add -D @epure/minidoc-blocks
import { run } from "@epure/minidoc"
import { blocks } from "@epure/minidoc-blocks"
await run({ glob: "content/config.yaml", transform: { md: blocks({}) } })
The site copies blocks.css and one theme from the package, and sets the
theme on its html element: <html data-blocks-theme="soft">.
Each plate below is a scenario of the package. The markdown is what an author writes. The nodes are what the package reads in it: a middle language between the markdown and the HTML, which a live editor can redraw one block at a time. The page is what a reader sees. The switch at the top of this page changes the theme of every page drawn here, and nothing else.
The plates are built from the fixtures in blocks/test/ when the site is
built. A plate whose nodes are not the ones its fixture expects says so.
Callouts
A callout sets a few lines apart and says what they are. Seven come with
the package: note, draft, settled, open, technical, principle
and rejected. Its body is markdown, and it may hold another block when
its colons are more than the inner block's.
A project adds its own with blocks({ callouts: { risk: "Accepted risk" } }).
Its colour is the variable --tone-risk.
Markdown
::: note Keep each page **short**. :::
Nodes
callout note "Note" | Keep each page **short**.
Page
Release notes
Publishing the handbook
Each release of the handbook goes through the same few steps. They are written down here, so that anyone on the team can run one.
The next section lists who signs off, and what each of them checks before the release goes out.
Markdown
::: open Who signs the export? - the author - a reviewer :::
Nodes
callout open "Open question" | Who signs the export? | | - the author | - a reviewer
Page
Release notes
Publishing the handbook
Each release of the handbook goes through the same few steps. They are written down here, so that anyone on the team can run one.
The next section lists who signs off, and what each of them checks before the release goes out.
Markdown
::: draft A ::: ::: settled B ::: ::: technical C ::: ::: principle D ::: ::: rejected E :::
Nodes
callout draft "Draft" | A callout settled "Settled" | B callout technical "Technical" | C callout principle "Principle" | D callout rejected "Rejected" | E
Page
Release notes
Publishing the handbook
Each release of the handbook goes through the same few steps. They are written down here, so that anyone on the team can run one.
The next section lists who signs off, and what each of them checks before the release goes out.
Markdown
:::: settled We keep the format. ::: quote "Ada Lovelace" It weaves algebraic patterns. ::: ::::
Nodes
callout settled "Settled"
| We keep the format.
quote author "Ada Lovelace"
| It weaves algebraic patterns.Page
Release notes
Publishing the handbook
Each release of the handbook goes through the same few steps. They are written down here, so that anyone on the team can run one.
The next section lists who signs off, and what each of them checks before the release goes out.
Markdown
::: risk The cache may serve a stale page for a minute. :::
Nodes
callout risk "Accepted risk" | The cache may serve a stale page for a minute.
Page
Release notes
Publishing the handbook
Each release of the handbook goes through the same few steps. They are written down here, so that anyone on the team can run one.
The next section lists who signs off, and what each of them checks before the release goes out.
Quotes
A quote names its author in double quotes, and its date after it. Both are optional.
Markdown
::: quote "Ada Lovelace" 1843 The Analytical Engine weaves algebraic patterns. :::
Nodes
quote author "Ada Lovelace" date "1843" | The Analytical Engine weaves algebraic patterns.
Page
Release notes
Publishing the handbook
Each release of the handbook goes through the same few steps. They are written down here, so that anyone on the team can run one.
The Analytical Engine weaves algebraic patterns.
The next section lists who signs off, and what each of them checks before the release goes out.
Markdown
::: quote "Grace Hopper" It is easier to ask forgiveness than permission. :::
Nodes
quote author "Grace Hopper" | It is easier to ask forgiveness than permission.
Page
Release notes
Publishing the handbook
Each release of the handbook goes through the same few steps. They are written down here, so that anyone on the team can run one.
It is easier to ask forgiveness than permission.
The next section lists who signs off, and what each of them checks before the release goes out.
Markdown
::: quote Less, but better. :::
Nodes
quote | Less, but better.
Page
Release notes
Publishing the handbook
Each release of the handbook goes through the same few steps. They are written down here, so that anyone on the team can run one.
Less, but better.
The next section lists who signs off, and what each of them checks before the release goes out.
Flows
A flow is a numbered list. Each top item is a column with a bold title, and the numbered list under it holds its steps. A bullet under a step is a detail. Without columns, a flat numbered list is one column of steps.
The markdown stays a readable nested list in an editor, on GitHub, or with no stylesheet at all.
Markdown
::: flow
1. **Upload**
1. The file arrives
- the original file
2. Its hash is computed
- the reference hash
2. **Viewing**
1. A reader asks for a range
2. The parts are checked
- each hash against the index
:::Nodes
flow "Flow"
column "Upload"
step "The file arrives"
detail "the original file"
step "Its hash is computed"
detail "the reference hash"
column "Viewing"
step "A reader asks for a range"
step "The parts are checked"
detail "each hash against the index"Page
Release notes
Publishing the handbook
Each release of the handbook goes through the same few steps. They are written down here, so that anyone on the team can run one.
The next section lists who signs off, and what each of them checks before the release goes out.
Markdown
::: flow 1. Write the page 2. Build the site - `pnpm build` 3. Publish :::
Nodes
flow "Flow"
column
step "Write the page"
step "Build the site"
detail "`pnpm build`"
step "Publish"Page
Release notes
Publishing the handbook
Each release of the handbook goes through the same few steps. They are written down here, so that anyone on the team can run one.
The next section lists who signs off, and what each of them checks before the release goes out.
Screen mockups
ui-dialog draws a screen. Its body is markdown, and some lines become
widgets:
| Line | Widget |
|---|---|
[Cancel] [[Continue]] |
buttons; double brackets mark the primary one |
[Continue]* |
the button the person clicks |
( ) No (x) Yes |
radio buttons |
[ ] No [x] Yes |
checkboxes |
Password : ____ |
an input field |
ui-flow holds screens in the order a person sees them. A project names
who presents a screen with blocks({ "ui-dialog": { owners: { … } } }),
and each owner's colour is --tone-<owner>.
Markdown
::: ui-dialog Delete the page The page and its history are removed. [Cancel] [[Delete]] :::
Nodes
ui-dialog title "Delete the page"
| The page and its history are removed.
actions
button "Cancel"
button "Delete" primaryPage
Release notes
Publishing the handbook
Each release of the handbook goes through the same few steps. They are written down here, so that anyone on the team can run one.
The page and its history are removed.
The next section lists who signs off, and what each of them checks before the release goes out.
Markdown
::: ui-dialog Sign in [Cancel] [[Continue]]* :::
Nodes
ui-dialog title "Sign in"
actions
button "Cancel"
button "Continue" primary clickedPage
Release notes
Publishing the handbook
Each release of the handbook goes through the same few steps. They are written down here, so that anyone on the team can run one.
The next section lists who signs off, and what each of them checks before the release goes out.
Markdown
::: ui-dialog Export Format ( ) PDF (x) HTML [x] Include images [ ] Include drafts File name : ____ :::
Nodes
ui-dialog title "Export"
| Format
options
radio "PDF"
radio "HTML" on
options
check "Include images" on
check "Include drafts"
field "File name"Page
Release notes
Publishing the handbook
Each release of the handbook goes through the same few steps. They are written down here, so that anyone on the team can run one.
Format
The next section lists who signs off, and what each of them checks before the release goes out.
Markdown
::: ui-dialog provider Sign in with your account Password : ____ [[Sign in]]* :::
Nodes
ui-dialog owner provider "Identity provider" title "Sign in with your account"
field "Password"
actions
button "Sign in" primary clickedPage
Release notes
Publishing the handbook
Each release of the handbook goes through the same few steps. They are written down here, so that anyone on the team can run one.
The next section lists who signs off, and what each of them checks before the release goes out.
Markdown
::: ui-dialog provider settings :::
Nodes
ui-dialog title "provider settings"
Page
Release notes
Publishing the handbook
Each release of the handbook goes through the same few steps. They are written down here, so that anyone on the team can run one.
The next section lists who signs off, and what each of them checks before the release goes out.
Markdown
:::: ui-flow Changing a password ::: ui-dialog Settings [[Change password]]* ::: ::: ui-dialog New password New password : ____ [Cancel] [[Save]]* ::: ::::
Nodes
ui-flow caption "Changing a password"
ui-dialog title "Settings"
actions
button "Change password" primary clicked
ui-dialog title "New password"
field "New password"
actions
button "Cancel"
button "Save" primary clickedPage
Release notes
Publishing the handbook
Each release of the handbook goes through the same few steps. They are written down here, so that anyone on the team can run one.
The next section lists who signs off, and what each of them checks before the release goes out.
Sequences
A sequence code block draws what passes between parties, in order. Its
first line names the parties, left to right. Each line after it is a step
down the page: a -> b label is a message, a -x b label a refusal, and
a = label a party's state. {legend} adds a legend, and the words after
sequence on the fence are its caption.
The nodes are the drawing itself: every box, line and label, placed. A
project names its kinds of party with blocks({ sequence: { kinds: { … } } }),
and writes a party as name:kind.
Markdown
```sequence browser app browser -> app sign in app -> browser token ```
Nodes
sequence
frame -10 -10 252 134
head party 0 0 84 26 "browser"
head party 148 0 84 26 "app"
life 42 26 114
life 190 26 114
message 42 190 50
label 116 45 "sign in"
message 190 42 82
label 116 77 "token"Page
Release notes
Publishing the handbook
Each release of the handbook goes through the same few steps. They are written down here, so that anyone on the team can run one.
The next section lists who signs off, and what each of them checks before the release goes out.
Markdown
```sequence Locked out
person:person app:app
{legend}
person -> app password
app -x person wrong password
person = locked
```Nodes
sequence
frame -10 -10 252 166
head person 0 0 84 26 "person"
head app 148 0 84 26 "app"
life 42 26 146
life 190 26 146
message 42 190 50
label 116 45 "password"
refused 190 42 82
label 116 77 "wrong password"
state 13 104 58 20 "locked"
caption "Locked out"
key person "the person, in their browser"
key app "the application"
key message "a message, and what it carries"
key refused "a refusal"
key state "the state of a party"Page
Release notes
Publishing the handbook
Each release of the handbook goes through the same few steps. They are written down here, so that anyone on the team can run one.
The next section lists who signs off, and what each of them checks before the release goes out.
Markdown
```sequence browser app browser -> bank pay ```
Error
sequence: no party called bank
Page
The build stops here.
sequence: no party called bank
Markdown
```sequence browser ```
Error
sequence: a sequence runs between two parties at least
Page
The build stops here.
sequence: a sequence runs between two parties at least
State machines
A states code block draws steps and the moves between them. Its first
lines are a grid: each word is a box, and a dot leaves a cell empty. After
a blank line, a -> b label is a move. A move between rows curves. A label
sits in the middle of its move, unless {0.2} says where, and
{0.2 right} puts it on the right of the way.
Markdown
```states draft review published draft -> review submit review -> published approve ```
Nodes
states
frame -10 -19 320 59
box step 0 0 55 30 "draft"
box step 101 0 69 30 "review"
box step 216 0 84 30 "published"
move 55 15 89 15 67 15 101 15
label 78 3 middle "submit"
move 170 15 204 15 182 15 216 15
label 193 3 middle "approve"Page
Release notes
Publishing the handbook
Each release of the handbook goes through the same few steps. They are written down here, so that anyone on the team can run one.
The next section lists who signs off, and what each of them checks before the release goes out.
Markdown
```states Review draft review . rejected draft -> review submit review -> rejected refuse rejected -> draft rework ```
Nodes
states
frame -10 -19 206.82 173
box step 0 0 55 30 "draft"
box step 101 0 75 30 "review"
box step 101 114 75 30 "rejected"
move 55 15 89 15 67 15 101 15
label 78 3 middle "submit"
move 138.5 30 138.5 68.22 151 75.78 151 114
label 155 73 start "refuse"
move 126 114 126 55.75 27.5 88.25 27.5 30
label 74 92 middle "rework"
caption "Review"Page
Release notes
Publishing the handbook
Each release of the handbook goes through the same few steps. They are written down here, so that anyone on the team can run one.
The next section lists who signs off, and what each of them checks before the release goes out.
Markdown
```states draft review draft -> published publish ```
Error
states: no box called published
Page
The build stops here.
states: no box called published
Markdown
```states Review
draft review:decision published:end
. rejected:end
{legend}
draft -> review submit
review -> published approve
review -> rejected refuse
```Nodes
states
frame -10 -19 326 173
box step 0 0 55 30 "draft"
box decision 101 0 75 30 "review"
box end 222 0 84 30 "published"
box end 101 114 75 30 "rejected"
move 55 15 89 15 67 15 101 15
label 78 3 middle "submit"
move 176 15 210 15 188 15 222 15
label 199 3 middle "approve"
move 138.5 30 138.5 67.8 138.5 76.2 138.5 114
label 150 76 start "refuse"
caption "Review"
key step "a step"
key decision "a decision"
key end "an end"Page
Release notes
Publishing the handbook
Each release of the handbook goes through the same few steps. They are written down here, so that anyone on the team can run one.
The next section lists who signs off, and what each of them checks before the release goes out.
Markdown
```states
draft review
. rejected
{legend}
draft -> review submit
review -> rejected refuse {fail}
rejected -> draft rework {0.4 fail}
```Nodes
states
frame -10 -19 206.82 173
box step 0 0 55 30 "draft"
box step 101 0 75 30 "review"
box step 101 114 75 30 "rejected"
move 55 15 89 15 67 15 101 15
label 78 3 middle "submit"
move fail 138.5 30 138.5 68.22 151 75.78 151 114
label 155 73 start "refuse"
move fail 126 114 126 55.75 27.5 88.25 27.5 30
label 88 96 middle "rework"
key step "a step"
key fail "a refusal" movePage
Release notes
Publishing the handbook
Each release of the handbook goes through the same few steps. They are written down here, so that anyone on the team can run one.
The next section lists who signs off, and what each of them checks before the release goes out.
Markdown
```states
draft review
draft -> review submit {oops}
```Error
states: no kind called oops, line 3
Page
The build stops here.
states: no kind called oops, line 3
The strict check
A block name that the site does not know, a block left open, or a close with too few colons stops the build, with the line in the page. Colons inside a code block are text.
Markdown
Some text. ::: warning Careful. :::
Error
Unknown block on line 3: warning
Page
The build stops here.
Unknown block on line 3: warning
Markdown
::: note Never closed.
Error
Unclosed block on line 1
Page
The build stops here.
Unclosed block on line 1
Markdown
:::: note Text. :::
Error
Mismatched block close on line 3
Page
The build stops here.
Mismatched block close on line 3
Markdown
Write a note like this: ```markdown ::: note Keep it short. ::: ```
Nodes
| Write a note like this: | | ```markdown | ::: note | Keep it short. | ::: | ```
Page
Release notes
Publishing the handbook
Each release of the handbook goes through the same few steps. They are written down here, so that anyone on the team can run one.
Write a note like this:
::: note
Keep it short.
:::
The next section lists who signs off, and what each of them checks before the release goes out.
The HTML contract
The nodes are drawn into HTML whose class names the stylesheet and the
themes rely on. That HTML is held by its own fixture,
blocks/test/html.test.yaml, one scenario for each kind of node. The page
around the blocks, with its anchors, its highlighted code and its wrapped
tables, is held by blocks/test/page.test.yaml.
A theme sets variables and nothing else. Every colour comes from a
--tone-* variable, and a block mixes its fill and its edge from it.
Shapes are variables too: radii, padding, the label's case and spacing,
the quote's rule, the screen's width and shadow, and the gaps of a flow.