Writing a document
By the end of this you will have written a document, know exactly what landed in the git repository, and understand how folders come to exist without anybody creating one.
Write it
From /documents, choose New document. A document needs a title and a body.
The body is GitHub-flavoured Markdown: headings, lists, tables, task lists, code
fences, links.
Save it. That is one git commit.
What landed in the repository
A file, named from the title:
bewertung/grundsaetze.md
Open it in a clone and it is exactly what you wrote, with a small block of YAML in front:
---
id: 01KZB223QDQP0F7MBN1Q9Z24H2
title: Grundsätze der Bewertung
createdAt: 2026-03-04T09:12:44.000Z
updatedAt: 2026-03-04T09:12:44.000Z
---
Every fact about a document lives in the file.
Three things follow from that, and they are the reason the format is worth knowing:
- The
idis the document's identity, not its path. Rename the file by hand in the repository and it is still the same document. Path is location. - Nothing important lives only in the database. PostgreSQL holds a projection — the index that makes listing and search fast — and it can be rebuilt from the repository at any time. Anything a rebuild would lose was a mistake to store.
- Front matter is not optional. A file whose front matter is missing or malformed is reported as an error rather than quietly repaired. This is a source of truth, and guessing at what a broken file meant is how one loses data.
Folders come to exist
There is no "create folder" anywhere, and that is not an omission. A folder exists because a document is in it.
Creating a document from inside a folder puts it there by default. Give a
document the path bewertung/grundsaetze and the folder bewertung exists from
that moment; delete the last document under it and it stops existing. A folder
page lists what is directly inside it, not a flattened view of everything
beneath.
Each path segment follows the same rule as a document name: lowercase, no
spaces, no slashes, and never . or ... A path is assembled from validated
segments rather than parsed from a string, so there is no path to traverse out
of.
Two documents may share a name in different folders. Uniqueness is on the whole path.
Uploading a file
Images, PDFs, and anything else go in through Upload a file, and are
addressed where they sit — /documents/bewertung/diagram.png. A document
alongside can reference one relatively:
Relative on purpose: the same reference resolves in the web app and in a clone. An absolute URL would break the moment somebody read the file outside the product.
The bytes are stored outside the git repository; git holds a small
diagram.png.asset pointer recording the file's name, size, type, and checksum.
Git cannot forget a binary once committed, and an upload is far more likely than
a typed document to contain somebody else's personal data — so removing an
upload really removes the bytes. Getting your content
out covers what that means for clones and
backups.
Two people, one document
Editing is safe but not simultaneous. A save based on a version that has since moved on is refused, and nothing is written — you are shown that the document changed since you opened it. Reload, reapply, save.
The alternative would be taking the last write and silently discarding the other, which looks like it worked and is not.
What "done" looks like
The document opens at its own address, the folder that contains it has a page,
and git log in the workspace repository shows your commit. The commit is
authored under a pseudonymous user id rather than your name — git history cannot
be rewritten without invalidating every clone a customer holds, so no personal
data goes into it.
Next: finding things.