The mdNotebook protocol

Status:   1.0.8 - agreed, being implemented
Updated:  2026-11-19

This document specifies everything a server and client must agree on:

  1. The notebook format - how sections, pages, attached files, drafts and conflict copies are laid out on disk. The server and every client use the same layout. The server's disk is the canonical copy, and each client keeps a full local copy laid out exactly the same way.
  2. The wire protocol - a small set of HTTP requests for reading and writing files, and for acting on whole sections and pages (move, copy, delete, publish, restore...).
  3. The sync algorithm - how a client reconciles its local copy with the server, including clashes.

The design is built around one idea:

The server stores nothing but content, and understands sections and pages. All of a notebook's state is its files on disk: there is no database and nothing kept per client. (The server's only other state is the list of logged-in devices, 3.3, kept in its own directory.) Every action on a section or page (move, copy, delete, publish...) is one request, done in one step on the server, so a lost connection never leaves a page half moved. Clients work on their local copy, offline or online, and syncing sends their actions to the server, then pushes and pulls the content that differs, using content hashes to detect clashes.

The server enforces the protocol. Clients are expected to follow this document, but the server MUST NOT rely on them doing so. It checks every request against every rule it can (names, pages, orphans, drafts, the bin, author, permissions...) and refuses any request that would break one, so a buggy or hostile client can't damage a notebook. Wherever this document says a client MUST or MUST NOT do something the server can check, the server checks it. Clients SHOULD check the same rules first, so the user gets a clear message instead of a refused request.

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are used as in RFC 2119.


Contents

    1. Terminology
    1. The notebook format
    1. Transport and authentication
    1. Requests
    1. The sync algorithm
    1. Hooks (server behaviour)
    1. Server configuration
    1. Client behaviour (non-normative)
    1. Why not ...? (design notes)
  • Appendix A. Worked examples

1. Terminology

Term Meaning
Notebook One directory tree of markdown: a website, a book, a diary. Each notebook has a short name used in URLs, e.g. and-e.co.uk or myDiary.
Path A location relative to the notebook root. Segments are separated by /, with no leading or trailing /. E.g. food/chiliConCarne.page/page.md. The root itself is the empty path.
Section A directory in the notebook that isn't a page. Clients present sections (or chapters), never folders.
Page A directory whose name ends .page, holding the page's markdown in page.md and its attached files (2.2). A page is one unit: it's moved, copied and deleted whole.
Attached file Any other non-hidden file in a page directory (2.3).
Draft An unpublished version of a page, in the page's hidden .draft directory (2.6).
Conflict copy Another device's complete version of a page or draft, kept inside the page after a clash (2.7).
Orphan Anything non-hidden that breaks the layout rules, e.g. a loose file in a section. Orphans aren't allowed (2.3).
Hidden Any path where any segment starts with .. Hidden paths hold working state such as drafts, conflict copies and the bin.
Hash Lowercase hex SHA-256 of a file's exact bytes. It identifies a version of a file.
Page hash, section hash One hash for a whole page or section, so a request can say "only if it's still this version" (2.10).
Manifest The list of every section and file (with hashes) in a notebook.
Bin Where deleted things go, so they can be restored. It is synced like everything else (2.8).
Deletion One directory in the bin, holding everything deleted by one action.
Base A client's record of each file's hash at the end of its last successful sync. It lets the client tell "I changed this" from "the server changed this".
Journal A client's list of actions (move, delete, publish...) done locally but not yet confirmed by the server (5.4).

2. The notebook format

2.1 Names

So that a notebook can be stored on Linux, Android, Windows and macOS file systems, every path segment MUST:

  • be valid UTF-8, 1-255 bytes long.
  • not contain / \ : * ? " < > |, tab, newline or any other control character.
  • not be . or .., and not end with a space or ..
  • not be a Windows reserved name (CON, PRN, AUX, NUL, COM1-COM9, LPT1-LPT9, with or without an extension, any case).

Two paths in the same directory MUST NOT differ only by letter case (Photo.jpg and photo.jpg). Windows, macOS and Android can't hold both. The server rejects any request that would create one.

Names ending .page are pages, so a section's name MUST NOT end .page. A page and a section in the same directory MUST NOT have the same name apart from .page (aboutMe.page beside aboutMe/), because a website built from the notebook would put both at aboutMe/. The server refuses any request that would create the pair.

Clients SHOULD name new pages (and sections) from the title like this:

  1. Split the title into parts at every :, - and _.
  2. In each part, drop every character that isn't a letter, a digit or a space, then write the words in camelCase: the first word all lower case, each later word with only its first letter in upper case.
  3. Join the non-empty parts with -, and add .page for a page.

So "FFmpeg: Change PIDs in a Stream" becomes ffmpeg-changePidsInAStream.page, and "Chili con carne (the good one!)" becomes chiliConCarneTheGoodOne.page.

2.2 Pages and metadata

A page is a directory, NAME.page, holding:

food/katsuCurry.page/page.md        the page's markdown
food/katsuCurry.page/katsu.jpg      attached files (2.3)
food/katsuCurry.page/.draft/        only while there's a draft (2.6)
  • Names starting page. are reserved for the page's own content. Today the only one allowed is page.md (later versions may allow other formats).
  • A page directory MUST hold page.md, or a draft with .draft/page.md, or both. A page with only a draft has never been published: clients show it as an unpublished page.
  • A page is flat: no non-hidden subdirectories, and no page inside a page. (Subdirectories may be allowed in a later version.)

page.md is a UTF-8 text file with \n line endings. Clients MUST write \n line endings. Line endings are never converted in transit, because that would change the hash.

A page MAY start with a metadata block ("YAML front matter", but only simple key: value lines):

---
title: About Me
description: (Andrew Cornford)
author: andrew
created: 20230309185254
edited: 20260721153726
---
The page's markdown starts here.
  • Each line is split on the first :. The key and value are trimmed.
  • Clients MUST keep every key they don't recognise, with its value, in its original order.
  • Keys with special meaning:
Key Meaning
title The page title. Clients show this instead of the directory name wherever they can.
description Optional short summary.
author The username of the user who last published the page (or created it, if it's new). The client sets it on every publish. The server refuses to write a page's page.md, or to publish a draft, when author isn't the authenticated user (403). Moves, copies and restores don't change page.md, so they aren't checked.
created yyyyMMddHHmmss, local time. Set by the client when a page is first published, if missing.
edited yyyyMMddHHmmss, local time. Set by the client every time a page is published.

Other tools may use their own keys. The metadata editor shows and edits them like any other key.

2.3 Attached files

Every non-hidden file in a page directory other than page.md is an attached file of that page: images, PDFs, even other markdown files. Its name is just its name, with no prefix.

aboutMe.page/page.md
aboutMe.page/pictureOfMe.jpg     <- attached file "pictureOfMe.jpg"
aboutMe.page/myCV.pdf            <- attached file "myCV.pdf"
  • An attached file's name MUST NOT start with page. (2.2).
  • An attached file belongs to its page. It can be renamed within the page, copied to another page, and deleted, but it can't be moved to another page on its own. (A client may offer "Move to page..." as a copy followed by a delete.)

Links. Links are ordinary relative links, resolved against the page's directory, so they work in any markdown tool: ![Me](pictureOfMe.jpg) for an attached file, [Chili](../chili.page/page.md) for another page (../chili.page/ and ../chili.page mean the same page). When rendering, clients open a link to a page as that page, and show a link to an attached file as that file.

Orphans aren't allowed. These are orphans:

  • a non-hidden file directly in a section (not in a page);
  • a non-hidden directory inside a page;
  • a page directory with neither page.md nor .draft/page.md;
  • a file in a page whose name starts page. but isn't page.md.

The server refuses any request that would create an orphan, and never lists or serves one. Orphans found on disk (e.g. a file copied in by hand) are ignored: never listed, served, moved or deleted. The server logs each one as a warning, with its path and the rule it breaks, when it first finds it (at startup, or on a later scan of the notebook), not again on every scan. A page and a section with the same name (2.1) found on disk are logged as an error; both are still listed, so nothing vanishes, until someone fixes it by hand. Clients never show orphans.

2.4 Sections

Sections (directories) are part of the notebook and are synced, including empty ones. Clients present them as sections or chapters, not folders.

Index pages. A page named index.page is its section's index page, its introduction. Clients SHOULD show it first in its section. The notebook root can have one too. Its links are relative to SECTION/index.page/, like any page's.

When browsing a section, clients list only its subsections and pages, never attached files. A page's attached files are listed, viewed, added and removed from that page (in the editor or page view).

2.5 Hidden paths

Hidden paths are working state, not content:

  • They are only visible to users with edit permission. Users with read-only permission never see them in a manifest and can't fetch them.
  • Changes to hidden paths never trigger hooks (section 6), except moving things into and out of the bin.
  • Anything that publishes or processes a notebook (a site generator, a backup, git) SHOULD ignore them. For git, add .* to the notebook's .gitignore (or don't, if drafts should be versioned).

Only these hidden names have meaning:

Name Where Meaning
.draft in a page The page's draft (2.6).
.conflict-yyyyMMddHHmmss-DEVICE in a page A conflict copy of the page (2.7).
.draftConflict-yyyyMMddHHmmss-DEVICE in a page A conflict copy of the draft (2.7).
.bin at the root The bin (2.8).
.mdntmp-* anywhere The server's temporary files (2.9).

The server ignores every other hidden path: it's never listed, served, changed or warned about. So a notebook can be a git repository (.git, .gitignore) without that reaching the clients. Clients don't create other hidden paths in their local copy.

2.6 Drafts

A draft is an unpublished version of a page, or a page that has never been published. It lives in the page's .draft directory, laid out exactly like the page: page.md and attached files.

The draft is a complete copy of the page as it will be once published, attached files included. Example: editing aboutMe.page, replacing the CV and adding a photo:

aboutMe.page/page.md
aboutMe.page/myCV.pdf
aboutMe.page/.draft/page.md
aboutMe.page/.draft/newCV.pdf
aboutMe.page/.draft/photo.jpg
  • Starting a draft copies page.md and every attached file into .draft (one request, done on the server, so nothing is uploaded again).

  • Save as draft writes the draft locally. It syncs like any other files, so a draft started on one device can be finished on another.

  • A new page starts as a page directory holding only .draft/page.md.

  • The draft follows the same rules as the page: flat, page.md required, no other page.* names.

  • Links in a draft are written as they will be once published, relative to the page directory, so publishing never changes them. In the draft's preview, links to attached files resolve to the draft's copies.

  • Publish replaces the page with the draft, in one step:

    1. The client sets author to the user's username and edited to now in the draft's page.md (and created, if it's missing).
    2. Attached files of the page that aren't in the draft move to the bin (2.8), in one deletion.
    3. Every file in .draft replaces (or becomes) the file of the same name in the page, and .draft is removed.

    In the example, myCV.pdf goes to the bin, and the page is left with page.md, newCV.pdf and photo.jpg.

  • Discard draft moves the whole .draft directory to the bin.

  • A page has at most one draft.

2.7 Conflict copies

When a page, or its draft, has been changed differently on two devices (5.5), the server's version stays in place, and the other device's version is kept inside the page as a complete copy:

aboutMe.page/.conflict-20261113093000-pixel8/            the page as it was on pixel8:
aboutMe.page/.conflict-20261113093000-pixel8/page.md     page.md and every attached file
aboutMe.page/.conflict-20261113093000-pixel8/photo.jpg
aboutMe.page/.draftConflict-20261113093000-pixel8/...    the same, for a clash in the draft

DEVICE is the client's device name, restricted to [A-Za-z0-9-], and the time is UTC.

  • A conflict copy is one whole version: a file that isn't in it is a file that version doesn't have. Nothing is borrowed from the current page.
  • It never contains a .draft of its own. A clash in the page and a clash in the draft give two separate conflict copies.
  • It can't be edited, only kept or deleted.
  • There can be several, if several devices clash before anyone resolves them.

Conflict copies sync like any other files, so every device sees the clash. Clients MUST flag a page that has conflict copies, and SHOULD let the user preview each version. To resolve:

  • Keep a conflict copy: it replaces the page's own files (or the draft, for a .draftConflict-), and the version it replaces goes to the bin, in one step.
  • Delete a conflict copy (keeping the current version): it goes to the bin.

Once resolved there are no conflict copies left, and the losing versions can still be restored from the bin.

2.8 The bin

Deleting something moves it to the bin. It stays there for 90 days (configurable on the server), and can be restored or permanently deleted from any device in the meantime.

Layout. On the wire and in every client's local copy, the bin is the hidden directory .bin at the notebook root. Each deletion gets its own directory, named after the time of deletion (yyyyMMddHHmmss, UTC). Inside it, the deleted things keep their original paths:

.bin/20261113093000/food/chiliConCarne.page/...           a deleted page, whole (draft included)
.bin/20261114120512/networking/...                         a deleted section, whole
.bin/20261115080000/aboutMe.page/myCV.pdf                  an attached file on its own
.bin/20261116101500/aboutMe.page/.draft/...                a discarded draft

Where something came from and when it was deleted are both in its path, so the server keeps no records about the bin. The client chooses the deletion's name (5.4), so every device agrees on it. If that name is already taken, the client adds one second until it's free.

The layout rules (2.2, 2.3) don't apply inside the bin: an attached file or a draft can be in the bin without its page, as above.

Deleting:

  • A page: the page directory, with everything in it (draft and conflict copies included), moves into one new deletion.
  • A section: the whole directory moves into one new deletion, whether or not it's empty.
  • An attached file: moves into a new deletion. Attached files removed by publishing a draft go the same way (2.6).
  • A draft (discard) or a conflict copy: moves into a new deletion.

Restoring moves something from a deletion back to its original path (or another path the user chooses), creating any sections that no longer exist. If something now exists at that path, the client asks for a new name or place. Part of a deletion (e.g. one page from a deleted section) can be restored on its own. An empty deletion directory is removed. An attached file can only be restored into a page that exists, and a draft only into a page that has no draft. Clients SHOULD check this before offering to restore, and the server refuses it (409).

Permanently deleting something in the bin is a DELETE request (4.13). There's no other way to destroy content, and DELETE is refused anywhere outside the bin (403).

Read-only. Nothing in the bin can be edited. Clients MUST NOT offer to edit pages in the bin, though they SHOULD offer to view them. The server refuses a PUT with If-Match under .bin (403). It still allows creating new files there with If-None-Match: *, which sync needs (5.5).

Emptying. The server permanently deletes each deletion once its name is more than bin.keepDays (default 90) days in the past. It checks at startup and then every hour. Clients never empty the bin themselves. They see the deletions go when they next sync.

Where it's stored on the server. The bin can be any directory (bin.directory in 7). By default it's .bin inside the notebook directory. It can be outside the notebook, or a subdirectory of the notebook with another name (e.g. deleted). Whatever its real location, the server always presents it as .bin. If it's a subdirectory of the notebook, the server leaves the real directory out of the notebook itself, so it never appears twice. A real .bin in the notebook directory that isn't the configured bin is ignored, and the server logs a warning.

Presentation. Clients show the bin as its own "Bin" view, never as a section of the notebook. It lists each deletion by title and original location, with how long it has left. Unlike the section view, the Bin view lists attached files, drafts and conflict copies too, because each can be deleted on its own. Only editors see the bin, because it's hidden (2.5).

2.9 Temporary files

While writing, the server MAY create files named .mdntmp-*. They never appear in manifests, and the server deletes any it finds at startup.

2.10 Page and section hashes

Some requests act on a whole page or section, and must only go ahead if it's still the version the client expects. For that, a page or section has one hash, worked out from its files:

  1. Take every file inside it, leaving out conflict copies (and, for a section, leaving out .bin). For a page this includes its draft.
  2. For each, write the line HASH<TAB>RELATIVEPATH\n, where RELATIVEPATH is relative to the page or section (e.g. page.md, .draft/photo.jpg, chili.page/page.md). For a section, also write -<TAB>RELATIVEPATH/\n for each subsection, so empty sections count.
  3. Sort the lines by ordinal (byte) order, join them, and take the SHA-256 of the UTF-8 bytes, as lowercase hex.

Clients work these out from the manifest (4.3) the same way, so they never need to ask for them. The hash of the root section is the hash of the whole notebook (without the bin).

2.11 Markdown

A page means the same thing whatever renders it: the apps' preview, the docs site, or a website built from the notebook. So the markdown a page is written in is part of the format. It's CommonMark (https://commonmark.org, version 0.31), plus these extensions:

  • Tables: GitHub-style pipe tables, with : in the separator row for alignment.

  • Fenced code blocks (part of CommonMark). The info string's first word becomes class="language-WORD" on the <code> element.

  • Heading ids. Every heading gets an id, so #anchor links work. The id is made from the heading's text:

    1. Normalise to Unicode NFKD and drop every non-ASCII character.
    2. Drop every character that isn't a letter, digit, _, - or whitespace, trim, and lower-case it.
    3. Replace each run of whitespace and - with a single -.
    4. If the id is already used in the page, add _1, _2... until it isn't.

    So "Method (the long way)" becomes method-the-long-way.

  • Table of contents: a paragraph that is exactly [TOC] is replaced by <div class="toc">, holding a nested <ul> of links to every heading in the page, in order, nested by level.

  • Raw HTML is passed through as CommonMark says. A notebook's editors are trusted, so it isn't filtered. (A renderer showing pages to the public, like a website, may filter it.)

Metadata (2.2) isn't markdown: renderers strip it before rendering. Links follow 2.3. Anything else (footnotes, task lists, maths...) isn't part of the format yet, so a page that uses it renders as CommonMark says, usually as plain text. New extensions are added to this list, never just to one renderer.


3. Transport and authentication

3.1 HTTP

The protocol runs over HTTP/1.1. In production, the server SHOULD sit behind a TLS-terminating reverse proxy (nginx, Caddy...), because credentials are sent with every request. All protocol URLs start with /api/. The protocol version is reported by GET /api/ (4.1) rather than being part of the URL.

The server also hosts some things for people rather than for the protocol. These aren't part of the protocol, but the URLs are reserved here so they never clash with it:

URL What it serves
/api/... The protocol (section 4).
/docs/... The documentation site: a notebook of markdown, rendered as 2.11 says. Public: no login needed.
/downloads/... The downloads page, and the app and CLI files it links to. Public: no login needed.
/assets/... Files the server's own pages share with the web client, such as bulma.min.css. Public.
anything else The web client's static files (or, without one, a home page linking to the docs and downloads).

Plain text is used wherever possible, so everything can be tried with curl:

  • Text bodies are text/plain; charset=utf-8, lines end with \n, and fields within a line are separated by a single tab.
  • File bodies are sent and received as raw bytes, application/octet-stream.
  • A POST or PUT with no body MUST still send Content-Length: 0 (with curl, -d ''), as HTTP/1.1 asks. Servers MAY refuse one without it (411).
  • Paths in URLs are percent-encoded UTF-8, segment by segment (/ between segments is literal). Paths in query strings are percent-encoded whole, / included.
  • Versions use HTTP entity tags: ETag: "HASH". If-Match: "HASH" means "only if it's currently this version". If-None-Match: * means "only if it doesn't exist". For a page or section, the hash is its page or section hash (2.10).

3.2 Errors

Every error is an HTTP status code with a one-line human-readable text body, e.g. 404 / No such file: food/chili.page/chili.jpg.

Status Meaning
400 Malformed request or invalid name (2.1).
401 Authentication needed, or the credentials are wrong. Sent with WWW-Authenticate: Bearer realm="mdNotebook" (3.3).
403 Authenticated, but not allowed (e.g. writing to a read-only notebook, a guest reading a hidden path, editing in the bin, DELETE outside the bin, an author that isn't you).
404 Notebook, section, page or file doesn't exist.
409 Breaks a notebook rule or clashes with what's on disk: destination already exists, parent section missing, case-only clash (2.1), a page and section with the same name (2.1), would create an orphan (2.3), the page already has a draft, restoring an attached file without its page (2.8).
411 A POST or PUT without Content-Length (3.1).
412 If-Match / If-None-Match failed: it isn't the version you expected. During sync this means "the server changed underneath you".
413 File larger than the server's configured limit.
429 Too many failed logins: try again later (3.3). Sent with Retry-After in seconds.
428 A request didn't include the If-Match or If-None-Match it requires.
500 Server error. Details are logged on the server only.
503 A service the server needs (e.g. LDAP) can't be reached. Try again later.

3.3 Authentication

There are two ways to authenticate. Both are checked on every request; the server keeps no sessions. A request with no Authorization header is a guest request.

  • Tokens (the apps). A device logs in once with a username and password (POST /api/login, 4.14) and gets back a token: a long random secret standing for "this user, on this device". It then sends Authorization: Bearer TOKEN with every request, and never sends or stores the password again. Clients MUST use tokens.
  • Basic (curl and scripts). Authorization: Basic base64(user:password) on every request, so the protocol can still be tried with curl -u.

Checking a password (at login, or on a Basic request) uses local users (listed in the server's configuration, 7) and/or an LDAP directory:

  • The username MUST match a real local or LDAP account with the correct password, or the request fails with 401. A guest request is never refused at this stage; permissions decide what a guest can do (3.4).
  • Local users each have a username, a password and a list of groups.
  • LDAP: the server binds with a service account, searches for the user with a configured filter, then binds again as the account it found, with the supplied password, to check it. The user's groups are read from a configured attribute of that account (e.g. memberOf), optionally reduced to just each group DN's CN.
  • If neither local nor LDAP authentication is enabled, everyone, guests included, has edit access to everything. The server SHOULD log a loud warning when that happens. Logging in and Basic requests then accept any password, so the apps work the same way, and the username given is who the caller is (e.g. for author, 2.2). A token the server doesn't know is still refused (401).

The server MAY cache a successful password check in memory for a short time (auth.cacheSeconds, default 5 minutes), so it doesn't bind to LDAP on every Basic request. Passwords are never stored.

Tokens.

  • A token is 32 random bytes from a cryptographic random number generator, written as lowercase hex.
  • The server stores only each token's SHA-256, never the token itself, with the username, the device name, when it was created and when it was last used. A token's id is the first 16 characters of that hash. They're kept in one file, tokens.json, in the server's state directory (stateDirectory, 7), which is separate from the configuration and the notebooks. It's written atomically (temp file, then rename). "Last used" is updated in memory and written at most once an hour, and at shutdown.
  • Expiry: a token never expires while it's in use, because a device may be offline for weeks. One unused for auth.tokens.expireUnusedDays (default 180) is removed.
  • Is the user still allowed? A token request is refused (401) if the user no longer exists: a local user removed from the configuration, or an LDAP account the service account can no longer find. For LDAP, the server looks the user up (and re-reads their groups) with the service account at most every auth.cacheSeconds. If LDAP can't be reached, requests from LDAP users fail with 503 until it can.
  • Logging out removes the token (POST /api/logout). A user can list their logged-in devices and log any of them out (GET /api/devices, POST /api/devices/revoke), e.g. a lost phone. Changing a password doesn't log devices out by itself. An administrator can log everyone out by deleting tokens.json while the server is stopped.

401 responses carry WWW-Authenticate: Bearer realm="mdNotebook", never Basic. Browsers only show their own login box for Basic, so the web client can show its own login page, and log out. (curl doesn't need the challenge: curl -u sends Basic credentials straight away.) A client that gets 401 with a token asks the user to log in again.

Slowing down password guessing. The server counts failed password checks (Basic requests and POST /api/login; a wrong token isn't a guess at a password), in memory only, both per username and per client address (the reverse proxy's X-Forwarded-For, if configured as trusted). After auth.lockout.maxFailures (default 5) failures within auth.lockout.minutes (default 15), it answers every password check for that username or from that address with 429 and Retry-After, without checking the password, until that many minutes have passed since the last failure. Requests with a valid token aren't affected, so someone guessing a password can't lock the user's devices out. A successful login clears the username's count. Every lockout is logged as a warning.

3.4 Permissions

Each notebook gives each user one of: none, read, or edit. Edit includes read.

Each notebook has a read rule and an edit rule, and each rule has:

  • a default of allow or deny;
  • a list of users and a list of groups that are exceptions to that default (if the default is allow, listed users and groups are denied; if it's deny, they're allowed);
  • for read only, allowGuest, which lets guests read the notebook without logging in.

A user is allowed edit if the edit rule allows them, otherwise read if the read rule allows them, otherwise none. A user who can edit can always read, whatever the read rule says. Guests can only ever get read, and only through allowGuest.

  • none: the notebook isn't listed, and every request for it returns 404 (so you can't tell it exists).
  • read: can list and fetch non-hidden paths. Hidden paths are left out of the manifest.
  • edit: everything.

4. Requests

{nb} is the notebook name. {path} is a path (2.1).

Every request that changes a notebook is checked against section 2 before anything is changed (see "The server enforces the protocol" at the top), and is done in one step under the notebook's write lock. A request that would break a rule changes nothing. Requests that change a notebook need edit permission.

Request Does
GET /api/ Server information (4.1).
GET /api/notebooks List notebooks (4.2).
GET .../manifest Every section and file, for sync (4.3).
GET .../section?path= One section's subsections and pages, for browsing online (4.4).
GET .../files/{path} Read a file (4.5).
PUT .../files/{path} Create or replace a file in a page, a draft or the bin (4.6).
PUT .../sections/{path} Create a section (4.7).
POST .../move, POST .../copy Move or copy a section, a page or an attached file (4.8).
POST .../delete Move a section, page, attached file, draft or conflict copy to the bin (4.9).
POST .../restore Move something out of the bin (4.10).
POST .../startDraft, POST .../publish Start or publish a draft (4.11).
POST .../conflict, POST .../keep Create a conflict copy, or keep one (4.12).
DELETE .../files/{path} Permanently delete something in the bin (4.13).
POST /api/login, POST /api/logout Get a token for this device, or log it out (4.14).
GET /api/devices, POST /api/devices/revoke List your logged-in devices, or log one out (4.15).

... is /api/notebooks/{nb}.

4.1 GET /api/ - server information

No authentication needed. Clients use it to check that they're talking to an mdNotebook server and which features it has.

mdNotebook	1
maxFileBytes	104857600
download	android	1.2.0	/downloads/mdNotebook-1.2.0-android.apk
download	linux-x64	1.2.0	/downloads/mdNotebook-1.2.0-linux-x64.AppImage
download	cli-linux-x64	1.2.0	/downloads/mdn-1.2.0-linux-x64.tar.gz

Each line is a key followed by its values. Clients MUST ignore keys they don't know.

  • mdNotebook: the protocol version. This document describes version 1. A client MUST refuse to sync with a server reporting a higher major version than it understands, and tell the user to update.
  • maxFileBytes: the largest file the server accepts.
  • download (repeated, may be absent): the newest version of each app the server offers, as platform, version (major.minor.patch) and URL. These come from the downloads directory. Clients use them for update checks (8).

4.2 GET /api/notebooks - list notebooks

One line per notebook the caller can at least read: name, permission (read/edit), kind, display title.

and-e.co.uk	edit	notebook	&E
myDiary	edit	diary	My Diary

kind is notebook or diary (see 8). Clients MUST treat a kind they don't know as notebook.

Clients also use this request to check that their token still works.

4.3 GET /api/notebooks/{nb}/manifest - list everything

One line per section and per file, sorted by path (ordinal, byte order). The root isn't listed. Page directories aren't listed on their own: they're the .page segments in the file paths.

F	a9b0...41	2210	aboutMe.page/page.md
S	av
F	3f1c...e9	1834	av/ffmpeg-changePidsInTransportStream.page/page.md
S	food
F	77de...02	88231	food/chiliConCarne.page/.draft/chili.jpg
F	5e0b...7c	1104	food/chiliConCarne.page/.draft/page.md
F	77de...02	88231	food/chiliConCarne.page/chili.jpg
F	c1aa...9f	1022	food/chiliConCarne.page/page.md
  • S<TAB>path is a section (directories in the bin are listed as S lines too, so deleted empty sections show). F<TAB>hash<TAB>size<TAB>path is a file.
  • Hidden paths (drafts, conflict copies, the bin) are only listed for editors (2.5).
  • The response has an ETag that changes whenever anything in the manifest changes. It's worked out from the manifest's content (so it's the same however many times the server restarts). A client sending If-None-Match with the last ETag gets 304 Not Modified with no body if nothing has changed. This makes polling every 30 seconds cheap.
  • Orphans (2.3), ignored hidden paths (2.5), symlinks and anything that isn't a plain file or directory are left out.
  • The server MAY keep hashes in memory, keyed on path, size and modified time, so it doesn't re-hash files on every request. It MUST NOT store them on disk.

4.4 GET /api/notebooks/{nb}/section?path={path} - one section

For a client that browses without a full local copy (the web client). The section's subsections and pages, sorted by name:

S	desserts
P	index.page	p	Food
P	chiliConCarne.page	pdc	Chili Con Carne
P	katsuCurry.page	d	Katsu Curry
  • S<TAB>name is a subsection. P<TAB>name<TAB>flags<TAB>title is a page.
  • Flags: p it's published (has page.md), d it has a draft, c it has conflict copies. d and c are only shown to editors.
  • The title comes from page.md's title, or the draft's for an unpublished page, or is empty.
  • path is empty for the root.

4.5 GET /api/notebooks/{nb}/files/{path} - read a file

200 with the file's bytes and ETag: "HASH". 404 if it doesn't exist, is an orphan or is ignored.

4.6 PUT /api/notebooks/{nb}/files/{path} - create or replace a file

The body is the file's complete new contents. Exactly one of these headers is required (428 without):

  • If-None-Match: * creates the file. It fails with 412 if the file exists.
  • If-Match: "HASH" replaces the file. It fails with 412 if the file's current hash differs.

Where a file can be written:

  • A page's page.md. Creating it creates the page directory if it doesn't exist (its section must exist, 409). author is checked (2.2).
  • An attached file of a page, or a file in a page's .draft. The page (or the draft) must already have its page.md (409), except that creating .draft/page.md creates the draft (and the page directory, for a new page).
  • The bin, with If-None-Match: * only (sync needs this, 5.5). If-Match under .bin is refused (403), because the bin is read-only. The path must be inside a deletion (.bin/{deletion}/..., with {deletion} a valid yyyyMMddHHmmss, 409 otherwise). Missing directories on the way are created, because the layout rules don't apply in the bin.
  • A conflict copy, with If-None-Match: * only, and only once it's been created with POST .../conflict (4.12).

Anything else is refused: a file directly in a section or inside a page's subdirectory is an orphan (409), and hidden paths the protocol gives no meaning to (2.5) are never changed (403). Sending both headers, or an If-None-Match other than *, is 400.

A page.md (the page's, the draft's or a conflict copy's) must be valid UTF-8 with \n line endings (400 for invalid UTF-8 or a \r\n). For the page's own page.md, author must be the caller's username (2.2, 403); with no logins enabled (3.3), a caller who gave no username can't write one.

The write is atomic (temp file, then rename). Returns 201 (created) or 200 (replaced), with the new ETag. Removing a file from a page or a draft is a POST .../delete (4.9).

The client SHOULD send MDN-Hash: HASH with the hash of the body. If it's present and the body doesn't match, the server rejects the request with 400 (truncated upload).

4.7 PUT /api/notebooks/{nb}/sections/{path} - create a section

Creates the section. Its parent section must exist (409). Returns 201, or 200 if it already exists. A name ending .page, or a directory inside a page, is refused (409). Under .bin (a deleted empty section), the path must be inside a deletion and missing directories are created, as for files (4.6).

4.8 POST .../move?from={path}&to={path} and POST .../copy?from={path}&to={path}

from is a section, a page or an attached file. to is the full new path, which mustn't exist (409), and whose parent section (or page, for an attached file) must exist (409). Returns 201.

from Move Copy
A section The whole section, everything in it. The whole section, but without any drafts or conflict copies (an unpublished page isn't copied at all).
A page The whole page directory, draft and conflict copies included. The page's page.md and attached files, without its draft or conflict copies. A page with no page.md can't be copied (409).
An attached file Renames it within its page only (409 for another page). To the same page under a new name, or to another page.

Moves and copies don't need If-Match: they don't destroy anything, and they take whatever is there. Moving or copying into or out of .bin isn't allowed here (403): use delete and restore. page.md isn't an attached file, so it can't be moved or copied on its own (409), and to must be the same kind of thing as from (a section, a NAME.page, or a file in a page; 409). Renaming only the case of a name (Chili.jpg to chili.jpg) is allowed.

4.9 POST .../delete?path={path}&bin={deletion} - move to the bin

path is a section, a page, an attached file, a page's .draft (discard), or a conflict copy. It moves to .bin/{deletion}/{path}. {deletion} is the deletion's name (yyyyMMddHHmmss, UTC), chosen by the client (2.8). It must be a new deletion (409 if it exists). Returns 201.

If-Match is required: the section hash or page hash (2.10), or the file's hash. For a draft or a conflict copy, the hash is worked out the same way as a page hash, over just its own files. So deleting something that has changed since the client last saw it fails with 412, and an edit made elsewhere is never binned by surprise.

page.md (the page's or the draft's) can't be deleted on its own: delete the page, or discard the draft (409). A never-published page's draft is the whole page, so it can't be discarded either: delete the page (409). An attached file in a draft can be deleted like one in the page.

4.10 POST .../restore?from={path}&to={path} - move out of the bin

from is anything inside a deletion: a section, a page, an attached file, a draft or a conflict copy. to is where it goes, normally its original path, which mustn't exist (409). Missing sections on the way to to are created. An attached file needs its page to exist, and a draft needs a page without a draft (409, 2.8). to must be the same kind of thing as from was (409). The bin has no layout rules, so what's restored is checked against them where it's going: nothing may become an orphan or a hidden path mdNotebook doesn't use, and every page and draft it brings must have its page.md (409). Directories left empty in the deletion are removed, and the deletion too if it's left empty. Returns 201.

4.11 POST .../startDraft?page={path} and POST .../publish?page={path}&bin={deletion}

startDraft copies the page's page.md and attached files into a new .draft (2.6). The page must have page.md and no draft (409). If-Match (the page hash) is required. Returns 201.

publish publishes the page's draft (2.6). If-Match (the page hash, which covers the draft) is required. The draft's page.md must have author set to the caller (403). Attached files the draft drops go to .bin/{deletion}, which must be new (409) if anything is dropped; if nothing is, no deletion is made. Returns 200.

4.12 POST .../conflict?page={path}&name={name} and POST .../keep?path={path}&bin={deletion}

conflict creates a conflict copy (2.7) during sync. name is the new directory's name (.conflict-... or .draftConflict-...). The body lists the version's files, one per line, HASH<TAB>NAME. The server creates the directory and copies into it every listed file it already has with the same hash in that page (so large unchanged files aren't uploaded again), then answers with the names still needed, one per line. The client uploads those with PUT and If-None-Match: *. Returns 201. name must be .conflict-yyyyMMddHHmmss-DEVICE or .draftConflict-yyyyMMddHHmmss-DEVICE (400) and mustn't exist (409). The list must include page.md (a conflict copy is a whole version, 409).

keep resolves a clash by keeping the conflict copy at path (2.7). A .conflict- copy replaces the page's page.md and attached files (the draft isn't touched). A .draftConflict- copy replaces the draft. The version it replaces moves to .bin/{deletion}, and so do the page's other conflict copies of the same kind (.conflict- or .draftConflict-), so that clash is fully resolved (2.7). The conflict copy must have its page.md (409: upload its files first). If-Match is the page hash. Returns 200. To keep the current version instead, delete the conflict copy (4.9).

4.13 DELETE /api/notebooks/{nb}/files/{path} - permanently delete from the bin

path is anything under .bin: a file, a page, a section or a whole deletion. If-Match is required: the file's hash, or the page or section hash (2.10, computed over just that path). Returns 204. It's destroyed. Refused anywhere outside the bin (403). Directories it leaves empty in its deletion are removed, and the deletion too if it's left empty.

4.14 POST /api/login and POST /api/logout

login needs no Authorization header. The body is key<TAB>value lines (a value may contain tabs, but not newlines):

username	andrew
password	correct horse battery staple
device	pixel8

device is a name for the user to recognise the device by (up to 64 characters). If the password is right, it answers 200 with:

token	9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
id	5e884898da280471

The password check is the same as for Basic (3.3), and wrong passwords count towards the lockout (429). Every login makes a new token, so logging in again on the same device should be preceded by a logout.

logout removes the token the request was made with. Returns 204. A Basic request has no token to remove (400).

4.15 GET /api/devices and POST /api/devices/revoke?id={id}

devices lists the caller's own tokens, newest first: id, device name, created, last used (both yyyyMMddHHmmss, UTC), and * for the token this request was made with (- otherwise).

5e884898da280471	pixel8	20261117093000	20261117101500	*
a665a45920422f9d	laptop	20261101120000	20261116183000	-

revoke removes one of the caller's tokens by id (404 if it isn't theirs). ?id=others removes all of them except the one in use. Returns 204.


5. The sync algorithm

This section is normative for clients. The server takes no part beyond answering requests.

5.1 What the client keeps

For each notebook, the client keeps:

  • The local copy: a directory laid out exactly like the server's.
  • The base: every file's hash, and every section, as of the last successful sync, plus the manifest ETag.
  • The journal: the actions done locally that the server hasn't confirmed yet (5.4).

The base and journal are stored outside the local copy, in the client's own data directory.

5.2 When

  • Straight after every local change while the app is open and online: Publish, Save as draft, and every other action (move, delete, restore...). So changes reach the server at once. It's a full sync, so the server's changes are pulled at the same time. (Autosave isn't a change: it stays on the device, see 8.)
  • While the app is open: every foregroundSyncSeconds (default 30) since the last sync finished. Every sync, whatever started it, restarts this countdown, so an immediate sync is never followed by a needless one moments later.
  • While the app is closed or in the background: every backgroundSyncMinutes (default 30).
  • When the device comes back online (the platform reports a network change, or a sync that failed for lack of a connection succeeds), straight away.
  • Offline, changes are only made locally and their actions go in the journal (5.4), and failed syncs are retried on the normal schedule. Nothing is lost by syncing late.
  • Both intervals are client settings. A notebook syncs one at a time, and the client MUST stop a second sync of the same notebook from starting while one is running (on desktop this includes the GUI and the background CLI, using a lock file). A change made during a sync triggers one more sync as soon as it finishes; several changes made during a sync still trigger only one.

5.3 Steps

  1. Fetch the remote manifest with If-None-Match. If it's 304, the remote is unchanged since the last fetch.
  2. Replay the journal (5.4), in order. Fetch the manifest again afterwards if anything was sent.
  3. Scan the local copy into a local manifest. Hashes MAY be cached by path, size and modified time.
  4. Compare base, local and remote, one unit at a time. A unit is: a section; a page's published files (page.md and attached files); a page's draft; a conflict copy; a file in the bin. For each, B = base, L = local, R = remote, each being its set of files and hashes (or "absent"):
Case Action
L = R Nothing to do (set base to L).
L = B, R ≠ B Pull: download what changed and remove what's gone.
R = B, L ≠ B Push: upload what changed (PUT with If-Match the base hash, or If-None-Match: * for a new file). Files gone locally are deleted (4.9), into the same deletion they're in locally if they're in the local bin. A unit gone completely is deleted as a whole.
L ≠ B, R ≠ B, L ≠ R Clash, see 5.5.
  1. Apply in this order: create sections (shallowest first), then pages and drafts, then the bin, then remove sections that went (deepest first).
  2. Record each unit's new base as soon as it's done, so a sync interrupted halfway (lost signal on a train) resumes cleanly next time.
  3. If any request returns 412, finish the rest and then sync again straight away (at most 3 times in a row). Something changed on the server during the sync.

Before downloading a file, a client SHOULD look for a local file with the same hash and copy that instead. So when another device moves a section of photos, or deletes a page into the bin, nothing is downloaded again.

Read-only notebooks only ever pull. Any local change is reverted by pulling.

5.4 The journal

Structural actions are sent to the server as actions, not worked out from differences, because the difference between two states can't always tell a move from a delete and a create, or a publish from an edit.

  • Journaled actions: create a section, move, copy, delete, restore, start a draft, publish, keep a conflict copy, and permanently delete from the bin. Editing content (saving a draft, writing a page or attached file) isn't journaled: step 4 finds it by comparing hashes.
  • When the user does one, the client does it to its local copy straight away (online or offline) and appends it to the journal with the request it will send. Preconditions (If-Match) are taken from the base, the version the server had at the last sync, not from the local copy. Deletions are named when the action happens, so the local bin and the server's bin agree.
  • Replaying: each entry is sent in order. When the server confirms it, the client applies the same action to its base and removes the entry. Then step 4 compares as usual, and pushes any edits made after or alongside the action. For example, a page moved and then edited offline is first moved on the server, then its edits are pushed to the new path.
  • Publish needs the draft on the server first. Before sending it, the client uploads the files of the version being published to the server's draft, taking them from its local page by hash, if they aren't already there. (The journal entry records the version's file names and hashes.) If the server's draft isn't the base version (another device changed it), the publish isn't sent: see the next point.
  • If an entry fails (412, 404 or 409: someone else got there first), or its content can't be found locally, the client drops it and logs it. Step 4 then deals with the difference using the state rules, which never lose anything. The worst case is a page in two places, or something coming back from the bin, never lost work.
  • Lost responses. If a confirmed action's answer is lost (signal gone), resending it fails, and the client drops it. Step 4 then finds the server already matches the local copy, so nothing more happens.
  • A client MAY merge journal entries before sending them, as long as the result is the same (e.g. a page moved twice becomes one move).

5.5 Clashes

The rule is never lose anything:

Local Remote Result
page edited page edited (differently) The server's version stays. The local version is uploaded whole as .conflict-TIME-DEVICE (4.12), then the server's version is pulled.
draft edited draft edited (differently) The same, as .draftConflict-TIME-DEVICE.
created created (differently) As edited.
deleted edited The edit wins: the client pulls it. The local bin copy is still uploaded to the bin.
edited deleted The edit wins: the client uploads it again (If-None-Match: *).

"Deleted" means moved to the bin (2.8), so the deleted version is never lost either. Bin files are only ever created, never changed, so the bin can't clash.


6. Hooks (server behaviour)

A notebook can run a command after it changes, e.g. to commit to git and rebuild a website.

  • The server keeps a list of changes since the last run, in memory only. Changes to hidden paths aren't recorded (drafts, conflict copies, permanent deletes in the bin), with these exceptions, because they change the notebook's content: deleting into the bin (delete), restoring out of it (restore), publishing a draft (publish) and keeping a page's conflict copy (keep).
  • The hook runs once the notebook has had no changes for quietSeconds (default 60). A sync can send several requests in quick succession, and this waits for it to finish rather than running halfway through. Changes that aren't recorded (drafts...) still count as changes here: they never start the hook, but they hold it back until the sync is over.
  • Runs for the same notebook never overlap. Different notebooks run independently. The working directory is the notebook's directory. Output and exit code are logged on the server only.
  • A run that takes longer than timeoutMinutes (default 30) is killed, with everything it started, and logged as an error. Otherwise a hung hook (e.g. git push waiting for a password) would stop that notebook's hook from ever running again. Changes made meanwhile run the hook again as usual.
  • If runAtStartup is true, the hook runs once when the server starts. This catches changes that were made but never hooked because the server stopped. Hooks SHOULD be written to work out what changed themselves (e.g. git add -A), and use {changes} only for the description.
  • A crash loses no content, only the in-memory list: changes since the last run are hooked at the next start (with runAtStartup) or the next change, without being described in {changes}. A hook killed part-way may leave things behind, such as git's .git/index.lock. Hooks SHOULD cope with that (e.g. remove a stale index.lock before running git).
  • Each token's value is shell-quoted before it's substituted: wrapped in single quotes, with any ' inside written as '\'', so the shell always sees it as one literal word. Write tokens bare in the command, not inside quotes of your own.
Token Value
{notebook} Notebook name
{notebookDirectory} Absolute path of the notebook's directory
{timestamp} yyyy-MM-dd HH:mm:ss, server local time
{changes} Human-readable summary, e.g. publish aboutMe.page (andrew); move a.page -> b/a.page (andrew). One shell word. Each change is one of write PATH, create section PATH, move FROM -> TO, copy FROM -> TO, delete PATH, restore PATH (where it went), publish PAGE and keep PATH, followed by the user in brackets. For a startup run it's changes while the server was stopped, never empty, because some commands (git commit -m) refuse an empty message.
{changedPaths} Every path touched, each quoted, separated by spaces (none for a startup run)
{users} Users who made the changes, comma-separated, one shell word

Example:

git add -A && git commit -m {changes} && git push && /opt/mySiteGenerator/build.sh {notebookDirectory}

7. Server configuration

Configuration is one JSONC file (JSON with comments and trailing commas allowed). A sketch:

{
	// Address HttpListener listens on. Put a TLS reverse proxy in front of it.
	"listen": "http://+:8180/",
	// The server's own state: tokens.json (3.3). Keep it apart from the configuration and the
	// notebooks (in Docker, its own volume), and back it up: losing it logs every device out.
	"stateDirectory": "/var/lib/mdnotebook",
	// If set, static files for the web client are served from here at "/".
	"webClientDirectory": "./web",
	// The documentation site at /docs/: a notebook, rendered by the server on request. Empty (the default)
	// means the docs that come with the server.
	"docsDirectory": "",
	// The downloads page at /downloads/: app and CLI files, listed by their file names.
	"downloadsDirectory": "./downloads",
	"maxFileBytes": 104857600,
	// Authentication (3.3). If neither local nor LDAP is enabled, everyone can edit everything.
	"auth": {
		"local": {
			"enabled": true,
			// Passwords are stored in plain text, so keep this file private.
			"users": [ { "username": "andrew", "password": "changeme", "groups": ["admins"] } ]
		},
		"ldap": {
			"enabled": false,
			"serverHost": "ldap.example.com",
			"serverPort": 389,
			"useStartTls": true,
			// Service account used to search for users.
			"bindDn": "cn=mdnotebook,ou=services,dc=example,dc=com",
			"bindPassword": "secret",
			"baseDn": "ou=people,dc=example,dc=com",
			// {username} is replaced with the (escaped) username being checked.
			"userSearchFilter": "(uid={username})",
			// Attribute of the user's account that lists their groups.
			"groupMembershipAttribute": "memberOf",
			// true: use just the CN of each group DN ("cn=webEditors,ou=groups,..." -> "webEditors").
			"extractCnFromGroupDn": true
		},
		// How long a successful login is remembered, in memory only.
		"cacheSeconds": 300,
		// Slow down password guessing (3.3): this many failures within this many minutes locks out the
		// username or address for that many minutes.
		"lockout": { "maxFailures": 5, "minutes": 15 },
		// Logged-in devices (3.3). A token unused for this many days is removed.
		"tokens": { "expireUnusedDays": 180 },
		// Reverse proxies (addresses or CIDR ranges) whose X-Forwarded-For header is trusted for the client's
		// address. In Docker, the proxy's network, e.g. "172.18.0.0/16".
		"trustedProxies": [ "127.0.0.1" ]
	},
	"notebooks": [
		{
			"name": "and-e.co.uk",
			"title": "&E",
			"directory": "/data/notebooks/and-e.co.uk/md",
			// "notebook" (default) or "diary". Sent to clients in GET /api/notebooks (see 8).
			"kind": "notebook",
			// The bin (2.8). "directory" defaults to ".bin" inside the notebook directory. It may be anywhere;
			// if it's a subdirectory of the notebook it's hidden from the notebook and presented as ".bin".
			"bin": {
				"directory": "/data/notebooks/and-e.co.uk/bin",
				"keepDays": 90
			},
			// Permissions (3.4). Users and groups listed are exceptions to the default.
			"auth": {
				"read": { "default": "deny", "allowGuest": false, "usersList": [], "groupsList": ["webEditors"] },
				"edit": { "default": "deny", "usersList": ["andrew"], "groupsList": [] }
			},
			"hook": {
				"enabled": true,
				"quietSeconds": 60,
				// A run taking longer than this is killed (6).
				"timeoutMinutes": 30,
				"runAtStartup": true,
				"command": "git add -A && git commit -m {changes} && git push"
			}
		}
	]
}

8. Client behaviour (non-normative)

These aren't needed for two implementations to work together, but every mdNotebook client should behave this way.

  • Autosave. While editing, the client saves the editor's state every few seconds (only if it changed) to its own data directory, not to the notebook, so autosaves don't sync and can't clash. After a crash it offers to restore. Autosave is cleared on Save as draft, Publish or Discard.
  • Never a file manager. Sections show their subsections and pages, by title, with the index page first. Attached files are only listed from their page (2.4). Hidden paths are never shown as files. Drafts and conflicts show as badges on their page.
  • Empty sections are shown, but marked as empty (e.g. with an icon), so the user can see at a glance that they might be worth deleting. A section is empty if it has no pages or subsections.
  • Rendering is local, using the same markdown library everywhere (Markdig, configured for exactly the dialect in 2.11), so the preview's structure is the same on every device. The rendered page goes inside Bulma's .content class, styled with the platform's native look by default, or the app's own plain look (Bulma) if the user chooses that on the client's Settings screen (Look: Native / mdNotebook, a per-device setting, not synced). Links are ordinary relative links (2.3).
  • Conflicts. The page view flags a page with conflict copies, lists each version (the current one and each conflict copy, by device and time) and previews any of them. For the chosen version it offers two buttons:
    • Keep: keeps that version and sends the others to the bin, straight away.
    • Keep and edit: the same, then opens the kept version in the editor: as a new draft for a page conflict (or the existing draft, if the page has one), or the draft itself for a draft conflict.
  • Moving attached files. A page's attached files can be renamed, copied to another page, or moved with "Move to page..." (a copy, then the original to the bin).
  • Logging in. The client logs in once per device (4.14), naming the device after the machine (e.g. the phone's model or the computer's host name, which the user can change). It keeps only the token, in the platform's secure store where there is one, never the password. Settings has Log out and a Devices screen listing the user's logged-in devices, each with a "Log out" button.
  • Name clashes. When a new page, a copy, a move or a restore would land on a name that's already taken, the client adds _2, _3... before .page (e.g. chiliConCarne_2.page), or asks the user.
  • Diaries. In a notebook whose kind is diary, the client offers New entry for today. It creates a new page (a draft) at yyyy/MM/yyyyMMdd-titleInCamelCase.page (e.g. 2026/11/20261113-trainToEdinburgh.page), using the device's local date and creating the year and month sections if they don't exist. Entries always go at the notebook root, never in another section. A diary may still have other sections (e.g. trips/). These are listed by title, separately from the dated entries. Dated entries are listed newest first. Separate diaries should be separate notebooks. Other notebooks are listed by title, with index.page first.
  • Update checks. On startup and once a day, the client reads GET /api/ and compares the download version for its own platform with its own version. If the server has a newer one, it shows a small, dismissible "Update available" notice linking to the downloads page. Clients never download or install updates by themselves. (Android won't update a side-loaded app automatically, so without this you'd never find out.)

9. Why not ...? (design notes)

  • A raw text protocol over TCP, like IMAP? It's pleasant to read, but browsers can't open raw TCP sockets, so the web client couldn't use it. It would also need its own TLS handling and framing for binary files, and is more likely to be blocked on hotel/train Wi-Fi than HTTPS. HTTP with plain-text bodies keeps the curl-ability without those problems.
  • WebDAV? It does most of this, but it's large (XML property queries, locking), clients vary wildly, and it doesn't have the hidden-path permission rule or anything built for offline sync.
  • A server that only knows files (draft 0.5)? It kept the server tiny, but it couldn't enforce the rules: moving a page was several file moves, with orphans in between, and a lost connection could leave a publish half done. Now each action on a section or page is one request, done in one step.
  • Sync only by comparing states, with no journal? Comparing alone has to guess: a page moved and then edited offline looks like a delete and a create, and a publish can't always be told from an edit. The journal sends what the user actually did. Content is still compared by hash, so a failed or lost action falls back to rules that never lose anything.
  • Basic auth only, with no tokens? It keeps the server stateless, but every device would store the real password and send it every 30 seconds, a lost phone could only be locked out by changing the password, and browsers would show their own login box in the web client. Tokens cost one file of state on the server, in its own directory.
  • Signed tokens that need no server-side list (JWT)? They can't be revoked one device at a time without a list anyway, and expiring them would log out a device that's been offline for a while.
  • Server-side last-sync state per client? Ruled out by "store nothing but content". Content hashes, the client-side base and the client's journal do the same job.
  • Pages as NAME.md with attached files named NAME.md.SUFFIX (drafts up to 0.7)? It worked, but links to attached files only worked in mdNotebook (which rewrote them), not in any other markdown tool, and a page was several files to keep together. A page directory makes every link an ordinary relative link, and makes moving a page one rename.
  • Conflict copies holding only the files that clashed? Then each version would have to be pieced together from the conflict copy and the current page, and a deleted file couldn't be shown. A complete copy means each version is exactly what it says, and keeping one is a swap.

Appendix A. Worked examples

A.1 First sync of a new device

POST /api/login   (username, password, device pixel8)               -> token 9f86...0a08
GET /api/notebooks                                                -> and-e.co.uk	edit	notebook	&E
GET /api/notebooks/and-e.co.uk/manifest                           -> 200, ETag "m1", 40 lines
GET /api/notebooks/and-e.co.uk/files/aboutMe.page/page.md         -> 200 ... (for each file)

Every request after the login sends Authorization: Bearer 9f86...0a08. Base and local are empty, and the journal is empty, so every remote unit is "L = B, R ≠ B", which means pull everything.

A.2 Editing a page on a plane

Offline, the user edits "About Me", adds a photo and publishes. Locally, the client started a draft (copying the page into aboutMe.page/.draft), saved the edits into it, then published it, so aboutMe.page now has the new page.md (h2, base h1) and beach.jpg (h3). The journal holds:

startDraft  aboutMe.page   If-Match: base page hash p1
publish     aboutMe.page   version: page.md h2, beach.jpg h3

Landing, the next sync replays the journal, uploading the draft's new files before publishing:

POST /api/notebooks/and-e.co.uk/startDraft?page=aboutMe.page                 If-Match: "p1"   -> 201
PUT  /api/notebooks/and-e.co.uk/files/aboutMe.page/.draft/page.md             If-Match: "h1"   MDN-Hash: h2
PUT  /api/notebooks/and-e.co.uk/files/aboutMe.page/.draft/beach.jpg           If-None-Match: *   MDN-Hash: h3
POST /api/notebooks/and-e.co.uk/publish?page=aboutMe.page&bin=20261113093000  If-Match: "p2"   -> 200

Then the comparison finds local and remote the same. The hook records publish aboutMe.page (andrew).

A.3 The same page edited on two devices

The laptop publishes "About Me" as page.md = h2. The phone (offline, base h1) has published it as h3, and removed myCV.pdf. When the phone syncs, its journaled startDraft and publish fail (412: the page has changed) and are dropped. The comparison then finds the page's files changed on both sides, differently: a clash. The phone uploads its whole version as a conflict copy, then pulls the laptop's:

POST /api/notebooks/and-e.co.uk/conflict?page=aboutMe.page&name=.conflict-20261113093000-pixel8
     body: h3	page.md
           h4	pictureOfMe.jpg                                      -> 201, body: page.md
PUT  /api/notebooks/and-e.co.uk/files/aboutMe.page/.conflict-20261113093000-pixel8/page.md   If-None-Match: *
GET  /api/notebooks/and-e.co.uk/files/aboutMe.page/page.md                                    -> h2

The server already had pictureOfMe.jpg, so only page.md is uploaded. The conflict copy has no myCV.pdf, because the phone's version doesn't. Both devices now show "About Me" with a conflict badge. On the laptop, the user previews both versions, chooses the phone's and presses Keep and edit:

POST /api/notebooks/and-e.co.uk/keep?path=aboutMe.page/.conflict-20261113093000-pixel8&bin=20261113101500   If-Match: "p5"
POST /api/notebooks/and-e.co.uk/startDraft?page=aboutMe.page                                                If-Match: "p6"

The laptop's version is in the bin, and the phone's version is open in the editor as a draft.

A.4 Renaming a page with a photo

Locally, holiday.page (with beach.jpg) is renamed to spain2026.page. One journal entry, one request, and nothing is uploaded:

POST /api/notebooks/myDiary/move?from=holiday.page&to=spain2026.page   -> 201

The page's links don't change, because they're relative to the page directory.

A.5 Deleting a page, then restoring it

On the phone, the user deletes "Chili Con Carne". The client moves food/chiliConCarne.page into .bin/20261113093000/ in its local copy, and journals:

POST /api/notebooks/and-e.co.uk/delete?path=food/chiliConCarne.page&bin=20261113093000   If-Match: "p1"

The hook records delete food/chiliConCarne.page (andrew). The laptop syncs: the page is gone from food, and the same files are in the bin, so it moves them locally instead of downloading them, and shows the page in its Bin view with 90 days left. Restoring it on the laptop is one request:

POST /api/notebooks/and-e.co.uk/restore?from=.bin/20261113093000/food/chiliConCarne.page&to=food/chiliConCarne.page

If nobody restores it, the server removes .bin/20261113093000 after 90 days, and every device drops it on its next sync.