How documents are organized
v0.0.1
Mishka Document stores documentation as records, not files. A document holds versions, a version holds a tree of pages, and a page holds notes. This model lets one site publish the documentation of many products, each in several releases and languages, with a review before anything reaches a reader. This page explains the parts and how a reader's request finds its way through them.
The parts
The admin and the API call a document a workspace and a page a section. This documentation uses document and page, and names the admin label where it matters.
| Part | What it is | Where you work with it |
|---|---|---|
| Document | A name, a slug, an optional address, a status and a language. It belongs to one site. | The cards on the Documents screen |
| Version | A release of a document, with a semantic version number and a status. | The Workspace Versions screen |
| Page | A title, a slug and a text, filed under a parent in a tree. | The sections screen of a version |
| Note | A titled block drawn after a page's text. | The Notes icon of a page |
| Group | A page that is only a heading over the pages filed under it. | The Group switch on a page |
| Front page | The page a version draws at its document's own address. | The Front page switch on a page |
| Draft | A proposed page or note that applies itself when both reviews approve. | The Section Drafts and Note Drafts screens |
| Tag | A label assigned to pages. | The Document Tags screen |
| Issue | A problem report about a page or a note, with comments. | The Issues screen |
| Event log | A record of which action ran on which record, when, and who ran it. It keeps no copy of the data. | The Event Logs screen |
The Mishka Chelekom documentation is one document, read at /chelekom/docs. It has the versions 0.0.9 and 0.0.10. Its front page is Get Started, Navigations is a group with a page of its own, and Breadcrumb is a page under that group whose headings are notes.
Signed-in readers can also bookmark a page and follow a document. Those records, and the issues, drafts and tags, are served by the JSON:API. See JSON:API routes.
How a request becomes a page
- The address names a document. A document with an address is read there and nowhere else. One without an address is read under
/docsby its slug. - The URL picks a version. The version in
?v=wins, then the version marked latest, then the newest published one. Only Alpha, Beta, Rc and Stable versions can be picked. - The rest of the URL names a page. A page's address is the slugs of the pages it is filed under, then its own. With nothing after the document's address, the version's front page is drawn, or the list of pages if the version has none.
- The blocks draw it. One block draws the page and its notes, one the contents, one the headings of the page, and one the switcher for versions.
Pages are read as the reader. A page whose lock the reader does not meet is left out, and so is a page waiting for review. A draft version never appears.
Addresses
Three kinds of page leave their slug out of the address, so the address reflects what a reader sees and not how the pages are stored.
- The front page has an empty part of the address, so it is drawn at the document's address.
- A group has no address. The pages under it are addressed as if it were not there.
- A group with a page of its own is read at its slug, and the pages under it still leave that slug out.
A slug is unique among the pages that share a parent, so /chelekom/docs/tabs and /chelekom/docs/headless/tabs can be two pages. Because groups and the front page leave slugs out, the admin also checks that no two pages of a version end at one address.
Versions and lineage
Cloning a version copies its pages, notes and tags into a new draft version. Each copy keeps the id that links a page to its earlier forms across versions, so the version switcher can lead a reader from a page to the same page in another version. A clone also records its source. Deleting the source deletes its clones, unless you make a clone independent first.
Languages
A document and a page each carry a language and a language group. Translations of one document share a group, and so do translations of one page. A slug names one edition per site, so a block is told which language to read. The site's header lists the languages. The document extension's page frame plugin maps the page being read to its translations by group, else by slug, and links to the slugs that edition really has. A page with no translation in a language does not offer it. The doc-switcher block shows versions only. See Page frame: languages and the section bar and Changing language without a reload.
Sites
Every record belongs to one site, and a site account sees only its own. A master account, one that belongs to no site, can work across sites, and signs in at /auth?master_user=true. See the documentation. Access is by two permission areas: the workspace area for documents and versions, and the section area for pages, notes, drafts, tags and issues. See Permission names.