Quillet
Menu
Menu

What Quillet is

6 min read

Quillet is a headless CMS that keeps every save as a version, changes nothing for readers until someone publishes, fills a missing translation from another locale, and serves what is published through a cached read API.

Why the words live apart from the code

A website's words change more often than its code, and different people change them. Put the words in the code, and a typo fix waits for the next deploy while a translation becomes a copy that drifts away from the original. Put them in a CMS that publishes on save, and the opposite goes wrong: a half-finished edit goes live by accident. Quillet keeps the words apart from the code and makes going live a separate, deliberate act. Content managers write, save and publish in a dashboard, and the site reads only what has been published, through a key that can do nothing else.

What one server holds and how a project fits

Quillet is one server, shipped as one Docker image. On a single port it holds three things: the dashboard where people work, a management API at /api/v1 for writing, publishing and administration, and a delivery API at /d/v1 that serves published content to sites. Two packages talk to it from outside: the JavaScript SDK reads published content into a site, and the command line keeps content in a repository and automates the rest.

Everything that writes goes through /api/v1 with a credential of its own; a site reads only /d/v1, with a key that can do nothing else.

Inside a project, the parts fit together like this:

  • Everything is a document. Each document has a key such as docs/intro and one of three types: structured JSON, Markdown or plain text. Folders are not stored on their own; the slashes in a key imply them, and a folder's settings live in a document called _index inside it.
  • Every save adds a version and keeps the earlier ones. History shows who saved each version, and any version can be restored as a new draft.
  • Saving changes the draft. Publishing makes one version live, and the site sees nothing until then. Before you publish, the dashboard tells you what else changes with it: the other live documents that use this one.
  • A project has a default locale and any other locales you add. When a structured translation does not supply a field, that field is taken from the default locale, one field at a time, and the answer says which fields it filled that way. A Markdown or text document with no translation is served whole in the default locale.
  • A component is a shape for structured content, built in the dashboard and stored as JSON Schema. A save that does not fit its component is refused. A page is a document whose component describes a page, and the dashboard can preview a page before it goes live.
  • A project starts with one environment, prod, and can have more, such as staging. Each environment holds its own copy of the content, and promotion moves chosen changes from one environment to another.
  • A site reads with a delivery key, which sees published content in one environment and nothing else. Answers carry ETag and Cache-Control headers. When a document is published, the CMS clears its own cache of that document in every locale, of the documents that reference it, two levels up, and of the environment's listings.
  • Files are uploaded once per project and can be used in any environment. Each file is public or private, and images can be asked for at set widths.

How to

These docs are written for two kinds of reader, and most sections serve one of them. Both start here, and both share the Concepts section.

If you write and publish content, you are a content manager, and you never need a terminal. Read these in order:

  1. Read A content manager's first day. It covers signing in, the dashboard, and editing, previewing and publishing one document.
  2. Keep Working in the dashboard for the tasks that come later: pages, media, translations, history, and finding what is unfinished.
  3. Look words up in the glossary whenever one is new to you.

If you install the CMS or build the site that reads it, you are an engineer. Start with these:

  1. Do the quick start. By the end, the CMS runs on your machine and one page is published and rendered from your own code.
  2. Then go to Install and configure for a real server, Modelling content for components and pages, and the JavaScript SDK for your site.
  3. The command line, the APIs and webhooks and Operating a project cover automation and the day-to-day running of a project.

Both of you will want Concepts when something behaves in a way you did not expect. Each page there gives the reason behind one part of Quillet and the trade-off that part made.

Every guide follows the same shape: first why the feature exists, then what it does, then how to use it, its limits, and related pages. Where a task can be done in more than one place, How to has a tab for each, with the dashboard first.

Limits

  • Quillet does not draw your site. It stores and serves content, and your own code turns that content into pages, with the SDK or with plain HTTP.
  • You run it yourself. It needs a MongoDB replica set (a single node will do), Redis, and a disk volume or an S3-compatible bucket for files.
  • The only SDK is for JavaScript and TypeScript. From any other language, read the delivery API over HTTP.
  • The dashboard's own labels and messages are in English. Your content can be in any locale the project lists.
  • Search content in the dashboard finds a document by its title or key, not by what it says. Searching the text of drafts is not built, and the delivery API's search covers published content only.

Last updated