Quillet
Menu
Menu

Documents, keys and folders

4 min read

A document is one locale of one piece of content in one environment, it is addressed by a slash-separated key such as docs/guides/intro, and a folder is nothing more than the shared start of the keys under it.

Why folders follow from keys

Many CMSs store a tree of records: a folder row, a child row, a parent pointer. Quillet stores keys instead and lets the folders follow from them. The key docs/guides/intro implies the folders docs/ and docs/guides/, and neither one is written anywhere.

Keys earn that place in three ways. A key is the address a site asks for, so the name you see in the dashboard is the name your code reads, and a page needs no second path model. A key also maps one to one onto a file path, which lets a repository hold a folder of content as files and push it without translation. And because a folder's settings are a document too, they are versioned, published, compared and pushed by the same machinery as everything else. Neither the CLI nor a promotion has a second kind of record to reconcile.

What a document is and what a folder holds

Documents

A document's identity is four things taken together: the project, the environment, the key and the locale. landing/hero in en-US and landing/hero in de-DE are two documents that share a key. Every document has one of three types: Structured (JSON), Markdown or Plain text.

A key is made of lowercase segments separated by slashes, with no leading slash. It may be at most 512 characters long and 16 folders deep. Each segment may hold letters, digits, dots, dashes and underscores.

Folder settings in _index

A folder's settings live in a reserved document called _index inside it, such as landing/_index. Every setting is optional:

Setting What it does
title The folder's name in the dashboard and in listings
order Its place among its siblings
description A line for the dashboard and for a site's navigation
defaultType The type a new document here starts as
searchable Whether documents below it are indexed for delivery search
syncSource Which channel may write here: cli, dashboard or any
defaultSchema The component every structured document below it is bound to

Settings inherit down the tree. A document takes each value from the nearest _index above it that sets that field, and a setting on the document itself wins over all of them. Siblings sort by order. Anything without an order sorts after everything that has one, and ties sort by name, so a folder nobody arranged never jumps to the front.

A folder that holds only its _index is an empty folder. Two folders are reserved: _schemas/ holds components, and _singletons/ holds one-of-a-kind documents such as site settings.

Who may write a folder

syncSource is a guard that the server enforces. A folder marked dashboard refuses writes from a CLI key. A folder marked cli works the other way round: it refuses changes made as a person, whether in the dashboard or with a personal token, and accepts a CLI key only. With it, a repository can own landing/ while people write blog/ in the dashboard, and neither side can overwrite the other.

How to

Dashboard

  1. In the Content tab, press New, then Document.
  2. Enter the key landing/_index, keep the type Structured and press Create document.
  3. Replace the body with {"title": "Landing", "order": 1} and press Save. The folder in the tree is now called Landing.
  4. Press Publish. A site's listing reads the published _index, so the title reaches readers only now.

API

List the folder through delivery:

curl -s -u '<keyId>:<secret>' \
  'http://localhost:3000/d/v1/<project>/<env>/list?prefix=landing/'

In the answer, folder is the prefix's own published _index, as a title, a description and an order. items are the documents below it, without their bodies.

Limits

  • A key is the document's address. Renaming a document is therefore a copy and a delete, and it is refused while another document references it.
  • Folders are never stored, so a folder with no documents and no _index does not exist.
  • You may not use _index as a segment of your own keys.
  • The dashboard does not yet show which channel a folder's syncSource lets in. To see it, open the folder's _index.
  • When a folder binds a document to a component, the document's Schema select reads Inherited from folder and names the component, but not the folder that set it.

Last updated