Quillet
Menu
Menu

Why Quillet exists

4 min read

Quillet keeps your content out of your code, makes publishing an act of its own, lets a translation inherit what it does not say, and shows a draft on your real site before anyone else sees it.

Why your words should not live in your code

Most sites start with their words inside the code. A heading lives in a template, a price in a component, a translation in a file beside it. That works until the person who owns the words is not the person who can deploy. From then on, every typo is a ticket, and every change of copy waits for a release.

Quillet moves those words to a place where a content manager can change them and an engineer can still read them as data. It was built against four problems: content coupled to code, publishing by deploy, translations kept as copies, and previews that do not show the real site. Each one is answered by a part of the system, and the sections below take them in that order.

How Quillet answers each of the four problems

Content coupled to code

Content lives in the CMS, per project, per environment and per locale, and a site reads it through the delivery API. The database is the only source of truth. A repository can still manage some folders with the command line, because UI strings and landing copy often move with a deployment. A blog in the same project can be written only in the dashboard. Both kinds of content sit in the same store, carry the same history and are served the same way. A document made in the dashboard is not second-class for having no file on disk.

Publishing by deploy

When copy ships with the code, publishing it means deploying. In Quillet, saving and publishing are two separate acts. A save that changes the content appends a version, and what a site serves changes only when someone publishes. A publish needs no deploy, and a deploy publishes nothing.

Translations as copies

A translation that is a full copy of its source drifts. Every copy has to be edited when the source changes, and a field missing from one copy shows up as a blank on the page. In Quillet, a structured translation holds only the fields it translates. Every other field is read from the project's default locale, field by field, and the answer tells the site which fields those were.

Previews that lie

A preview the CMS draws is not your site. It has your words, but not your layout, your fonts or your code. Quillet offers two previews and gives them different names, so you can tell which one you are looking at. Content preview draws a document from its component, inside the dashboard. On website opens the current draft on your own site through a short-lived token, and your own code renders it.

How to

You can see three of the four answers on one document, and the fourth with one request.

Dashboard

  1. Open a document, change one sentence and press Save. The pill in the page bar reads Changed since published: you have a new version, and the site still serves the old one.
  2. Press History. Every version is listed with who wrote it.
  3. Choose a second locale in the page bar's locale switcher. If the translation exists, each field it does not hold is marked Inherited from en-US.
  4. Press Preview, then On website. Your site opens on the draft. If the item is unavailable, nobody has set a website preview URL for this environment yet.

API

Ask the delivery API for a document in a locale it is only partly translated into:

curl -s -u '<keyId>:<secret>' \
  'http://localhost:3000/d/v1/<project>/<env>/content/<key>?locale=<locale>'

In the answer, _meta.fallbacks lists the fields that came from the default locale. _meta.version is the published version, not the latest save.

Limits

  • Quillet does not render your site. It serves JSON, Markdown and plain text, and the site that draws them is yours.
  • A website preview needs a route on your site that turns the token into a page. Until an owner sets the environment's Website preview URL, only Content preview works.
  • A preview token opens one document's draft in one locale, for fifteen minutes. With the site's delivery key it also lists every draft in that environment, by key, title and tags, though it opens no other draft's text.
  • Field-by-field fallback applies to structured documents. A Markdown or plain-text translation falls back as a whole document, and a list falls back as a whole list.
  • There is no scheduling, approval step or named release. A publish happens when someone publishes.

Last updated