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:
- 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.
- 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...).
- 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
-
- Terminology
-
- The notebook format
-
- Transport and authentication
-
- Requests
-
- The sync algorithm
-
- Hooks (server behaviour)
-
- Server configuration
-
- Client behaviour (non-normative)
-
- 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:
- Split the title into parts at every
:,-and_. - 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.
- Join the non-empty parts with
-, and add.pagefor 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 ispage.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:  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.mdnor.draft/page.md; - a file in a page whose name starts
page.but isn'tpage.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.mdand 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.mdrequired, no otherpage.*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:
- The client sets
authorto the user's username andeditedto now in the draft'spage.md(andcreated, if it's missing). - Attached files of the page that aren't in the draft move to the bin (2.8), in one deletion.
- Every file in
.draftreplaces (or becomes) the file of the same name in the page, and.draftis removed.
In the example,
myCV.pdfgoes to the bin, and the page is left withpage.md,newCV.pdfandphoto.jpg.- The client sets
Discard draft moves the whole
.draftdirectory 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
.draftof 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:
- Take every file inside it, leaving out conflict copies (and, for a section, leaving out
.bin). For a page this includes its draft. - For each, write the line
HASH<TAB>RELATIVEPATH\n, whereRELATIVEPATHis relative to the page or section (e.g.page.md,.draft/photo.jpg,chili.page/page.md). For a section, also write-<TAB>RELATIVEPATH/\nfor each subsection, so empty sections count. - 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#anchorlinks work. The id is made from the heading's text:- Normalise to Unicode NFKD and drop every non-ASCII character.
- Drop every character that isn't a letter, digit,
_,-or whitespace, trim, and lower-case it. - Replace each run of whitespace and
-with a single-. - 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
POSTorPUTwith no body MUST still sendContent-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 sendsAuthorization: Bearer TOKENwith 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 withcurl -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'sCN. - 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 everyauth.cacheSeconds. If LDAP can't be reached, requests from LDAP users fail with503until 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 deletingtokens.jsonwhile 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
defaultofallowordeny; - 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'sdeny, they're allowed); - for
readonly,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 version1. 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>pathis a section (directories in the bin are listed asSlines too, so deleted empty sections show).F<TAB>hash<TAB>size<TAB>pathis a file.- Hidden paths (drafts, conflict copies, the bin) are only listed for editors (2.5).
- The response has an
ETagthat 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 sendingIf-None-Matchwith the last ETag gets304 Not Modifiedwith 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>nameis a subsection.P<TAB>name<TAB>flags<TAB>titleis a page.- Flags:
pit's published (haspage.md),dit has a draft,cit has conflict copies.dandcare only shown to editors. - The title comes from
page.md'stitle, or the draft's for an unpublished page, or is empty. pathis 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 with412if the file exists.If-Match: "HASH"replaces the file. It fails with412if 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).authoris 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 itspage.md(409), except that creating.draft/page.mdcreates the draft (and the page directory, for a new page). - The bin, with
If-None-Match: *only (sync needs this, 5.5).If-Matchunder.binis refused (403), because the bin is read-only. The path must be inside a deletion (.bin/{deletion}/..., with{deletion}a validyyyyMMddHHmmss,409otherwise). 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 withPOST .../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
- Fetch the remote manifest with
If-None-Match. If it's304, the remote is unchanged since the last fetch. - Replay the journal (5.4), in order. Fetch the manifest again afterwards if anything was sent.
- Scan the local copy into a local manifest. Hashes MAY be cached by path, size and modified time.
- Compare base, local and remote, one unit at a time. A unit is: a section; a page's published
files (
page.mdand 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. |
- Apply in this order: create sections (shallowest first), then pages and drafts, then the bin, then remove sections that went (deepest first).
- 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.
- 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,404or409: 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 pushwaiting for a password) would stop that notebook's hook from ever running again. Changes made meanwhile run the hook again as usual. - If
runAtStartupis 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 staleindex.lockbefore 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
.contentclass, 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) atyyyy/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, withindex.pagefirst. - Update checks. On startup and once a day, the client reads
GET /api/and compares thedownloadversion 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.mdwith attached files namedNAME.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.