Content model

Every piece of content in Quillet is a document with a key, a type, a body and five metadata fields, and folders hand their settings down through a document called _index.

Why one record holds content and its settings

A content model has to say what a piece of content is called, what shape its body has, and which rules apply to a whole group of pieces at once. Quillet answers all of that with one record. A document's key is its address, and the key implies the folder it sits in. Its type says whether the body is structured JSON, Markdown or plain text. Its metadata carries what a listing needs, so a listing never has to read the body.

A folder's settings are themselves a document, _index, so they are versioned, published, pulled into a repository and pushed back exactly like the content they describe. There is no second store of configuration to keep in step. When something moves, no tree of records needs rebuilding.

What a document, its metadata and a folder carry

A document is a key, with one body per locale. The key is a path such as guides/internal/onboarding, made of lowercase letters, numbers, dots, dashes and underscores, in which each segment starts with a letter or a number; the whole key is at most 512 characters and 16 folders deep. The folders guides/ and guides/internal/ exist because the key says so; nothing stores them separately. Documents, keys and folders gives the reason for that design.

A document's type is chosen when the document is created, and it never changes:

A save that names another type is refused with "This document is json. Delete it and create a new one to change its type."

The metadata sits beside the body, not inside it. A listing can show it without reading the body, and a Markdown file stays plain Markdown:

A save can also carry a message of up to 500 characters, which is stored with the version rather than on the document.

Folder settings live in <folder>/_index, a json document whose body may hold any of these keys:

A document inherits each setting field by field, from the deepest _index above it that sets that field. In the example below, guides/_index sets defaultType and guides/internal/_index sets searchable: false, so guides/internal/ has both. A key the CMS does not recognise, such as a note to the next editor, stays in the body and is ignored as a setting, while a recognised key with the wrong kind of value is treated as if it were absent.

syncSource is enforced on every save, delete and publish. A folder marked dashboard refuses an API key with 403 "Folder cli-only/ accepts changes only from the dashboard.", and a folder marked cli refuses changes made as a person. A project owner, acting as a person rather than through a key, can still change the _index itself, so a mistyped policy is never permanent.

Two folders are reserved. _schemas/ holds components, and _singletons/ holds the one instance of each singleton component. Delivery serves _singletons/ and never serves _schemas/.

How to

export QUILLET_API_URL=<cms-url> QUILLET_PROJECT=<project> QUILLET_ENV=<environment>
export QUILLET_MANAGEMENT_KEY=<keyId>:<secret>
E="$QUILLET_API_URL/api/v1/projects/$QUILLET_PROJECT/envs/$QUILLET_ENV"

curl -s -X PUT "$E/documents/guides/_index" -u "$QUILLET_MANAGEMENT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"type":"json","content":{"title":"Guides","description":"How-to guides.","order":2,"defaultType":"md"}}'

curl -s -X PUT "$E/documents/guides/internal/_index" -u "$QUILLET_MANAGEMENT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"type":"json","content":{"title":"Internal","searchable":false}}'

curl -s -X PUT "$E/documents/guides/internal/onboarding" -u "$QUILLET_MANAGEMENT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"type":"md","title":"Onboarding","order":1,"tags":["staff","how-to"],"message":"First draft",
       "content":"# Onboarding\n\nWhere things are, and who to ask."}'

{"key":"guides/internal/onboarding","locale":"en-US","type":"md","title":"Onboarding","order":1,
 "tags":["staff","how-to"],"searchable":false,"searchableSource":"folder","schema":null,…,"version":1,…}

curl -s -X POST "$E/publish" -u "$QUILLET_MANAGEMENT_KEY" -H 'Content-Type: application/json' \
  -d '{"documents":[{"key":"guides/_index"},{"key":"guides/internal/_index"},{"key":"guides/internal/onboarding"}]}'

export QUILLET_API_URL=<cms-url> QUILLET_PROJECT=<project> QUILLET_ENV=<environment>
export QUILLET_MANAGEMENT_KEY=<keyId>:<secret>

printf '# Onboarding\n\nWhere things are, and who to ask.\n' > onboarding.md
npx quillet content put guides/internal/onboarding --file onboarding.md --title "Onboarding" --tags staff,how-to --message "First draft"
npx quillet content get guides/internal/onboarding --meta
npx quillet content list guides/ --include-index

Limits

• A document's type cannot change. To change it, delete the document and create it again under the new type.
• Only json documents can have a component; a schema on Markdown or text is refused with "Only json documents can have a schema."
• The five metadata fields are the whole list. Anything else a document needs to say belongs in its body, and for a structured document that means a field in its component.
• A key is lowercase only and cannot be renamed in place: a rename in the dashboard is a copy and a delete, and it is refused while other documents use the old key.
• defaultType is only a suggestion to the dashboard. Every API and CLI write still states its type, and a write without one is refused.
• An _index that binds documents to a component cannot drop its defaultSchema or be deleted while those documents exist; the API answers 409 "This folder binds documents to a component." with the documents it means.
• The content index has no view of documents whose body no longer fits their component; a component's Instances tab shows them one component at a time. Components and the builder says what is checked and when.

Related

• Documents, keys and folders
• Components and the builder
• Writing a document
• Sync a repository
• Management API