CapaDrafts and publishing
What a draft is, what publishing changes, and what each kind of key sees.
Every entry keeps its versions. Saving writes a new draft version. Publishing makes a version the live one. Your site only ever sees the live version, unless it reads with a draft key.
The states of an entry
| State | What it means | API status |
|---|---|---|
| Draft | Never published. Only draft keys can read it. | draft |
| Published | The live version is the newest one. | published |
| Published, draft ahead | Live, with newer saved changes that are not live yet. | changed |
| Scheduled | A publish or unpublish is set for a time you chose. | Unchanged until it runs |
The admin's status line shows these, such as Published v7 or Scheduled: publishes Tue 6 Oct, 9:00 AM EDT.
Saving does not publish
Save draft writes a new version and leaves the live one alone. Your site keeps showing what was published until someone publishes again.
Publish saves and publishes in one step. The previous live version stays in the entry's history.
Every role that can edit entries can also publish them: Content, Developer and Admin. A Viewer can do neither. See Members and roles.
What each key sees
The key's environment decides, never a query parameter.
| Key | Sees | status can be |
|---|---|---|
Production (cap_live_, pk_) | Published entries, at their published version | published |
Draft (cap_test_, sk_) | Every entry, at its newest version | published, draft, changed |
A production key never learns that a draft exists. For a published entry with a newer draft, it reads the published data and status: "published". The same goes for the entry's updatedAt and tags: a production key reads them as they were at the last publish, so saving a draft changes nothing it can see.
A draft key reads the newest data and the entry's own updatedAt, which every save moves.
One exception: folders. Moving an entry to another folder applies to every key at once, published or not, because the folder is where the entry is filed in the admin, not part of its content.
Publishing reaches your site in seconds
Publishing purges every cached response that shows the entry, and every list of its model. The next read fetches the new version, usually within a few seconds.
Your own site may cache too. See Caching.
Unpublish
Unpublishing takes the entry off the public API at once. The cached copies are dropped immediately, not refreshed in the background.
The content is kept. The live version turns back into a draft, so you can edit it and publish it again later.
Delete
Deleting an entry removes it and every version of it. In the admin there is no undo.
Capa then removes the deleted entry from every relation that pointed at it, in drafts and in the live version. It never publishes a draft to do so.
Schedule
You can schedule a publish or an unpublish for a date, a time and a time zone. Capa publishes the latest saved draft at that moment, so a typo fixed after scheduling still goes out.
An entry can have one scheduled publish and one scheduled unpublish at a time. Scheduling a second publish replaces the first. See Publishing.
Draft keys are not a sandbox
There is one database. A draft key only changes what you can read. A draft key that holds publish rights publishes to your live site.
For a safe place to experiment, use a separate project.
Related
- Publishing for doing all of this in the admin.
- Keys for production and draft keys.
- Entries reference: drafts.