Appearance
The timeline
The timeline answers two questions that every other tool conflates into one, and keeps them apart on purpose.
Axis one — when the writing happened
Derived, never asserted.
An ordinary query over the op log, ordered by wall time. No file diffing, no journal-file convention, and deliberately no dependence on which page a block happens to live on.
A block's authored date is the time of its create op. Its location is whatever page its newest op points at. Those come from two different places, which is why moving a block between pages cannot disturb when it was written.
Axis two — the day the author chose
Stated, per block.
Deriving a date is the right answer to "when did this happen" and the wrong answer to "which day does this belong to" — a question nobody but the author can settle.
Put the caret in a block and use the strip above the editor (the same choices are in the block menu):
- + place on a day — pick a date. The button then reads
appears on 2014-03-12. - × — clear it, so the item shows only under the day it was written.
- pin — promote it within its day.
- hide — keep it out of the reading view.
Placement is per block, not per page. Filing a whole page under a date is what a journal already does; the point of this axis is that one item can be placed without moving the note it lives in.
The rule the design turns on
A declared date never touches the op's wall time. Backdating the op instead was the cheap implementation, and it would collapse the two axes into one — making "what did I actually do in March" unanswerable from then on. So it is a separate field, and the authored-date query reports exactly what it always did. There is a test that says so, and the design record explains why the shortcut was refused.
Reading them together
An item with a declared date appears twice across a wide enough range: under the day it was typed, and under the day it was placed. Each row carries a via tag saying which axis put it there — wrote, placed here, or both where they agree — plus the reciprocal date, so you can move between the two.
Showing it once and picking a winner would be picking which of two true things to hide.
The view shows every fact at once — the day the writing happened, the journal it is filed under, and the day it was placed on — because an entry carrying "filed under 10 January" while sitting under today is the argument.
Grouping and days
The raw log is not readable as a feed: one burst of typing is several ops. The feed groups them into one entry per block, per actor, per day, showing the content as it stood then and where the block lives now.
A burst is shown as one row, reading like "lead wrote 38 blocks on ADR 0003", with Show all to open it. Nothing is dropped, and a folded row counts every entry it holds.
- Six or more in a row by the same person on the same page fold where they stand, in order.
- Twelve or more in a day by the same person on the same page fold into one row wherever they fall in the day, shown at the time of the latest with the span they were written over ("09:02–17:40"). This happens before the timeline is paged. A large import is one row per page it made, and Load earlier entries reaches the day before it in a click.
- Pinned rows never fold, because a pin is a choice about that row.
- Placed rows fold only when a whole page was placed on the day, as an import dated by file does. A handful of items placed by hand are listed one by one.
Days are bucketed in your time zone. A day is a local calendar day, and bucketing in UTC files a Hong Kong evening under tomorrow.
The controls
| Control | What it does |
|---|---|
| Today / 7 days / 30 days / All | The range in view. |
| Only me | Just your own writing. |
| This page | Restrict to the page you have open. |
| Show hidden | Bring back items flagged hidden. |
Clicking a date in an entry jumps the view to that day, which is how you get from "written today, filed under March" to March.
Back to where you were
Open a page from the timeline and press Back: the timeline is as you left it — the same entries loaded, the same bursts unfolded, the same scroll. The timeline has an address of its own (?view=timeline), so it is a place in the browser's history like any page.
Choosing Timeline again from the sidebar or the palette reads it afresh from the top; only Back and Forward return to the one you left. Writing that arrived while you were away is offered by the news button, never pushed in under you.
It keeps up
An open timeline checks every ten seconds, and whenever you come back to the tab, for writing that has reached the server since it was read. When there is some, a button appears over the top of the list — New writing on 2 pages — and clicking it brings it in and takes you to the top. It never adds the writing by itself, because that would push down whatever you were reading.
"New" means arrived, not dated today: an edit somebody made offline last week and synced a minute ago is news, and appears under last week once you take it. Only pages you can open are ever counted.
Curation deletes nothing
hidden suppresses a row in the reading view and nothing else — the log is untouched, and Show hidden sits in the controls rather than in a settings panel, because the way back has to be visible.
A comprehensive view of a year is unreadable if every typo fix is in it, and unusable if suppressing one is indistinguishable from destroying it.
Paging
The timeline pages with a cursor, not an offset. An offset re-reads and discards everything before it, and it drops or repeats rows whenever somebody writes mid-walk — which on a timeline reads as the log having lost an entry.
Permission filtering happens inside the query. Filtering the results afterwards would give you short pages, empty pages with more still to come, and a rough measure of how much exists behind pages you cannot open.
In a feed reader
The last thirty days of the timeline are also an Atom feed, one entry per page per day — "Deploy runbook — Ana and Bo: 2 blocks written, 1 edited" — linking to the page.
A feed reader cannot sign in, so the feed takes a key in its address. Make one that can only read — a feed URL gets pasted into apps and synced to other devices, and the feed refuses any key that could do more:
bash
curl -X POST …/api/keys -b "$COOKIE" -H 'content-type: application/json' \
-d '{"name": "My feed reader", "scopes": ["read"]}'then subscribe to …/api/feed.atom?key=<the token>, or …/api/feed.atom?page=<id>&key=… for one page. It shows only what that key's owner may open, and revoking the key ends the subscription.
The feed carries titles and names, never what a page says. A hosted reader fetches your feed from its own servers and keeps it; the words stay behind the link, where the app decides every time whether you may read them.
A page read as a log
An incident, a meeting, an on-call shift: some pages are read as a sequence, and the question is when was this line written. Show when each line was written in the command palette puts the time at the start of every line of the page, from the same clock as the timeline: when the line was first written, wherever it has moved since. It is a way of looking at the page on this device; nothing about the page changes, and the Markdown does not include the times.
A page with the property timestamps: true shows them to everyone who opens it. Put it on a template and every page started from it does. An incident template might say:
yaml
template: true
numbered: true
series: INC
timestamps: trueCopy as a timeline puts the page on the clipboard as a Markdown list in the order it was written rather than the order it is in: each line with its time and who wrote it, the first draft of a post-incident review's timeline. A line typed in the last few seconds has its time once it has been saved.
Known limits
- One declared date per block. An item that belongs to two days has to be two items.
- A placed row has no time of day, because it has none — it sorts to the top of its day.
- Grouping differs per axis. Written rows are per block per actor per day; placed rows are per block, attributed to whoever created it.
- Nothing checks that a declared date is plausible. Unlike an offline time claim, which is clamped, this is a stated opinion about filing rather than a claim about when something happened — there is nothing to defend against.