Skip to content

Pages and the tree ​

A page is a title, an ordered tree of blocks, a set of properties, and a place in the workspace's page tree. There is no separate "document", "note" or "database row" type — database views select pages, journals are pages, and a row in a table is a page like any other.

Working with the tree ​

From the sidebar you can:

  • Create a page — at the root, or as a child of an existing one.
  • Rename it. The slug used by export follows the title, and exported links are rewritten with it, so renaming does not break the files.
  • Nest and reorder by dragging. Drop a page on the top or bottom edge of another to put it before or after it; drop it on the middle of a row to put it inside. A line or an outline shows where it will land, and a page is never offered a place inside itself. From the keyboard, Alt ↑ and Alt ↓ on a focused row move it among its siblings. Position in the tree is data about the page, not about its content — moving a page changes nothing about what it says or when it was written.
  • Trash it, and restore it later.

Rearranging a page's children is an edit to that page, so it needs write access to it; at the root it needs the same capability as creating a page there. Over the API, PATCH /api/pages/<id> takes before — the sibling to go directly before, or null for last — alongside parentId to move and place in one request.

Creating a page at the root is a capability (create_root_pages) rather than something everybody has, because a root page belongs to nobody in particular. Admins and members hold it by default; guests do not. See roles and permissions.

What the tree shows you ​

The tree lists only pages you may see. That filtering happens in the query rather than afterwards — a page you cannot open does not appear as a gap, and its title does not leak.

A page carrying a journal date shows a ◷ beside it and is titled by its date. See journals.

A title too long for the tree is cut short, and hovering over it shows the whole title. To see more, drag the tree's right edge. You can also focus the edge with Tab and move it with the arrow keys; Home and End jump to its narrowest and widest. Double-click the edge to put it back. This browser remembers the width. On a phone the tree is a drawer and has no edge to drag.

Starred and recent ​

Star a page — the star on its row in the page tree, or Star this page in the palette — and it is listed under Starred at the top of the sidebar, on every device you sign in on. A page you can no longer open, or that goes to the trash, drops off the list.

Recent lists the last few pages this browser opened, newest first. It is kept in the browser, so each device has its own.

Where a page sits ​

A page inside another shows its trail beneath the header — Engineering / Services / Deploy runbook — and each step opens that page. A very deep page shows the top of the tree and its two nearest parents, with the rest as "…". A parent you cannot open is not named: the trail stops where your view of the tree does.

Starting from a template ​

Any page with the property template: true is a template, and Notesflow comes with 161 built-ins and 33 kits besides. See templates for the gallery, placeholders, snippets and kits.

Numbered records: decisions, RFCs, reviews ​

Set up decision records in the command palette makes three things: a Decisions page, an ADR template beneath it (Context, Decision, Consequences), and on the Decisions page a view listing every record, newest first, with its number, status, owner and what replaced it.

New page from “ADR template” then makes the next record: ADR 0001, ADR 0002, and so on, numbered by the server so two people starting one at the same moment never get the same number, and never one that an ADR now in the trash already had. Rename it as usual. The number stays in its number property, so the view sorts it as a number.

Any template can number its pages. Give it numbered: true and a series (a short word such as RFC or PIR) as well as template: true. Its pages copy the series and get the next number in it. Through the API, POST /api/records with { "series": "RFC" } sets up the same three things for another series.

When a record is replaced, set its superseded_by property to the record that replaced it, written [[ADR 0040: Use SQLite]] or just its title. Its header then says Superseded by, linking to that record. The [[…]] form is the one Obsidian reads as a link in frontmatter, so an exported record says the same thing there.

Archiving ​

Archive is for a page that is finished rather than wrong: last year's roadmap, the runbook for a service that was turned off. Choose Archive this page from the command palette (Ctrl K), and the page and everything under it:

  • leave the page tree, search, database views, the [[ picker, and the list of places a name is mentioned without a link;
  • stay readable and editable, reachable by any link to them, in backlinks, in history and in the export. Nothing about the page changes but where it is offered.

Archived pages are listed under Archive at the foot of the page tree, and an archived page says so beneath its title, with Bring back beside it. Search can still look there: GET /api/search?archived=1.

Archive is not the trash. A trashed page is on its way out; an archived one is kept on purpose. A page that is both is in the trash.

Deleting, and what survives ​

Trashing a page removes it from the tree. It does not rewrite the op log: the blocks that were on it keep their identity and their authored dates, which is what makes restoring one a restoration rather than a re-creation.

A trashed page gives up its slug, so a new page with the same title takes the plain name in the export rather than status-2. Restored, it gets its old slug back if that is still free, and a numbered one if another page has taken it since.

Purging a page for good ​

Trashing keeps everything, on purpose. When something must really go — a customer's personal data, a page that should never have been written — somebody holding Purge pages and redact writing from history (admins, unless a role says otherwise) can purge it from the trash: the trash icon beside Restore, then the page's title typed back. The page, everything trashed under it, and every version of everything ever written on them leave the tree, the timeline, search, history, comments, suggestions, notices, the task list and the assistant's index at once. It cannot be undone, and there is no delay: the trash was the time to change your mind.

A block that was moved out of the page to one that still exists is not purged with it; it is still somebody's writing there. Use redaction for it.

What a purge cannot reach is said before you confirm: backups until they age out, git exports and mirrors that already committed it, mail, chat notices, webhooks and models it already went to, and a device that has the page open and never comes back online. If it was a password or a key, change it first.

The people who wrote on the page are told in their inbox who purged it and when, never what it said, unless the workspace or they have turned that off. A workspace on a legal hold cannot be purged at all (its settings); and a deployment may keep what is purged out of everybody's sight rather than erased (operations).

Pages in other workspaces that have been shared with you appear under Shared with you, below the tree — never inside it. Putting them in the tree would say they were this workspace's pages, and they are not. See sharing a page.

Moving a page does not move its history ​

This is worth stating on its own, because it is the thing most tools get wrong.

A block's authored date comes from the create op in the log. Its location comes from the newest op that points at a page. Those are two different columns computed from two different places, so moving a block — or a whole page — between parents cannot disturb when anything was written.

Drag a paragraph from today's journal into a project page next week and the timeline still reports it under the day you typed it.

Blocks and the op log are canonical. Markdown is a projection. Git is a target.