Note columns — the screens, and the decisions
These are the mockups #729 was agreed against (2026-10-12), before any
code: seven desktop screens and three phone screens, in html/. They show
two or more columns of blocks on one row, written as Pandoc’s fenced divs.
They are drawn to look like Niman, in the Night palette of
lib/src/ui/theme/niman.dart. Where a mockup and the app disagree, the
app is what ships. The engine design behind them is the record
note-columns.md.
| Screen | Desktop | Phone |
|---|---|---|
| The read view: a picture and a facts table in a 40 % column beside prose and a callout; then the note full width; then three columns wrapping two and one; stacked in source order on a phone | Desktop-1-Read | Phone-1-Read |
live with the caret in a column, editing side by side: a selection inside the column, the fences as thin markers; stacked on a phone, with Columns on the keyboard’s toolbar |
Desktop-2-LiveCaret | Phone-2-Live |
live with the caret on a fence line: its source shown dimmed, so the width can be edited |
Desktop-3-LiveFence | — |
| A selection from the left column into the right, in source order, and what Copy puts on the clipboard | Desktop-4-SelectionAcross | — |
source: stacked, every line numbered, the fences coloured, a fold arrow on the :::: opener, the Insert columns template just written |
Desktop-5-Source | — |
| Exported: the HTML page and an A4 PDF page | Desktop-6-Export | — |
| The Insert columns command: the palette, the toolbar button, the context menu’s Insert › Columns | Desktop-7-Insert | in Phone-2-Live |
| Columns inside a callout, stacked | — | Phone-3-Nested |
Decided with them
- Pandoc’s and Quarto’s fenced divs:
:::: columns, then::: {.column width="40%"}or::: column, and:::closers. They are the only syntax with real renderers elsewhere. An opener is three colons or more and a class; trailing colons are optional. A closer closes the innermost div, as in Pandoc. Insert writes the outer fence longer, so djot and commonmark-hs close it in the same place. Onlycolumnsandcolumnare read, and any other::: foostays text. Content insidecolumnsbut outside anycolumnis a column of its own. The syntax is gated behindLineRules.appSyntax. Fences are never rewritten: Markdown comes back byte for byte. - An unclosed opener runs to the end of the note, like a code fence. This is the behaviour a writer already knows from fences.
- An opener needs a blank line, or a block start, before it; a closer
may end a paragraph. Pandoc asks for the blank line, and a
:::line inside prose should stay prose. - Any number of columns.
width="%"is honoured and the rest share equally. Each column is at least 16 em wide; columns that do not fit wrap, by the flex-wrap rule, in the app and in the exported CSS alike. A phone stacks them. The rule reads the width the block has, never the device type, so one rule covers a phone, a narrow window and a wide tablet. - Nesting, completely. Columns are read wherever blocks are: at the
top level, inside callouts, quotes, list items and columns. Only the
outermost
columnslevel sits side by side; deeper levels stack. Every context is tested. - Source order on a phone, with no syntax to reorder the columns. Reordering would need a second syntax, and no other renderer has one.
- A footnote definition inside a column goes to the note’s end, as everywhere.
liveis the complete solution: side by side and editable. It ships in one PR, with a commit per step. The source of a two-column page shown stacked while it is edited is the page changing under the writer, whichdocs/records/read-live-parity.mdexists to prevent. The record designs the engine: one sliver per column, the caret and hit testing per column, motion in source order, IME, undo, find, folds and the height map.sourcestays line by line, stacked.- No widening past the note column. The columns live inside
noteColumnWidth, as every other block does. - One syntax, no alias. There is no Obsidian
> [!multi-column]form: two ways to write one thing would be two things to keep in step.
Decided while drawing them, confirmed by the owner (2026-10-12)
- Fence lines are 0.5 em bands, in both modes. A column’s opener is
the room above its first block, and the outer fences are the block’s
margins. The bands take the same room in both modes, so a flip moves
nothing.
- With the caret in the block, each column’s opener draws a hairline
and a chip naming the column (
column · 40%). The outer opener draws a chip at the left (columns), and the closers draw nothing. - With the caret on a fence line, that line shows its source, as any revealed mark does.
- A fence is reached by a click or a tap on its band, by Home at the
start of a column’s first line, by a find match in it, or in
source. Arrows do not stop on hidden fences: Right at a column’s last character goes to the next column’s first.
- With the caret in the block, each column’s opener draws a hairline
and a chip naming the column (
- Line numbers in
live. The gutter numbers the outer opener and the outer closer, and a bracket between them spans the block. The lines of side-by-side columns are not numbered there, because there is one gutter and several columns.sourcenumbers every line. - The export’s CSS shares by
flex-growover a zero basis, withmin-width: min(16em, 100%). It replaces the issue’sflex-basis: 40%withflex: 1 1 16em, which lets a 40 % column grow past 40 %. With the new form a column gets exactly its share of the width after the gaps, and still wraps at 16 em. - Stacked columns are separated by the gap alone (1.5 em), which is the flex-wrap rule’s own row gap. A rule drawn between them would have no CSS counterpart in the export.
- Insert columns is a toolbar button (Columns,
view_column_outlined, after Table), a context-menu entry (Insert › Columns), a palette command (Insert columns, no shortcut), and an entry in the phone’s Insert sheet.