Publishing
How drafts become published content - the Publish and Unpublish buttons, what gets written to the lake, how to see what is waiting, how media is published with a document, and what to do when a publish fails. For editors.
On this page
Everything you write is a draft. Nobody outside the CMS sees a draft, not even a developer with a read token. Publishing is the step that makes your work part of the lake, the Git repository that sites are built from. This page explains what publishing does and shows you how to publish, unpublish and keep track of what is waiting.
Before you start
- You have a document with a real title and a summary. Neither is checked when you publish, but a document called Untitled or without a summary is poor material for a site.
- You know that publishing is a decision. The first time you publish in a workspace, a dialog titled Before you publish says: “Published content can be used on public websites built from this workspace. Drafts stay private.” Choose Got it to go on. The CMS remembers your answer for you and this workspace, on all your devices.
What publishing does
When you publish a document, the CMS:
- Saves your latest changes first, so what goes out is what you see.
- Writes the document as a Markdown file in the workspace’s Git repository, at the path given by its folder and file name.
- Publishes the media the document uses (see Publish media).
- Updates the manifest,
_manifest.json, the list of everything that is published. - Makes one commit for all of it. The commit message is
Publish: <title>, and it is made in your name.
If a GitHub mirror is connected, the CMS pushes the commit to GitHub afterwards (Connect GitHub). A slow or broken GitHub never stops a publish.
Nothing is committed unless every step worked. A failed publish leaves the lake as it was.
Note
Publishing does not update any website by itself. A site is built from a locked commit of the lake. A developer decides when it takes your new commit (Refresh content). After you publish, tell the developer if the change is urgent.
Draft or published
Every document is in one of these states. You see it in three places: a dot in the document tree, a dot in the lists on the home page, and above the document, on the right.
| State | Dot | Above the document |
|---|---|---|
| Draft: never published, or unpublished | Hollow | A Publish button |
| Published, and nothing has changed since | Filled in the accent colour | A check mark and Published, with no button |
| Published, with changes waiting | Amber | A Publish button |
The tree dot has the tooltip Unpublished changes when it is amber.
A published document that you edit keeps its published version. Sites keep seeing the old text until you publish again. Your edits are saved as a draft, and the draft is what you see in the editor.
Publish a document
- Open the document.
- Choose Publish above the page, on the right.
- If the media in the document have changes of their own that are not yet published, a dialog asks about them. See Publish media.
Expected result: the status says Publishing…, then a check mark and Published replace the button. The dot turns solid. The Publish button comes back as soon as you change something.
The button is disabled while a publish is running and while the document is read-only because someone else is editing it.
Publish from the home page
On the home page, Unpublished changes lists documents and files with changes waiting, with the count in the heading. Each row has a Publish button, so you can go through the list without opening each document. A row says “Ada is editing” and its button is disabled if someone else has the document open.
Publish media
Images and files have their own drafts. You change alt text, a caption, tags or the focal point on the draft, and sites see the change only when the file is published.
Media is published in three ways:
- With a document. When you publish a document that uses a file, the file goes with it. If the file has never been published, it always goes out. If it has unpublished changes since an earlier publish, the dialog Publish this document asks: “2 images in this document have unpublished changes. Publish them too?” with a list of the files and a box Publish them too (ticked). Untick it to publish the document with the earlier versions of the files. The dialog then says “The document goes out with the versions published before. The changes stay as drafts.” Choose Publish.
- By itself. In the media library, select a file and choose Publish in the pane under the preview. The pane shows where the file stands: Not published, Unpublished changes, Publishing… or Published, with a line that tells what Publish does now. For several files, select them and choose Publish 3 in the toolbar (The media library). The home page rows work the same way.
- Always in the lake. A file set to Always (sites can use it directly), or in a folder named Brand, or tagged
brand, goes to the lake when it is published, even if no document uses it (The media library).
An image must have alt text before it can be published. In a bulk publish, an image without alt text is skipped, and the message says so: “Published 4 files. 1 image needs alt text first.”
Files have status messages of their own:
| Message | Meaning |
|---|---|
| Published 3 files. | Done. |
| Nothing to publish: everything is up to date. | The files had no changes. |
| 1 image needs alt text first. | Add alt text, then publish again. |
| 2 files could not be found. | The files were removed or are in the trash. |
Unpublish a document
Unpublishing takes a document out of the lake without deleting it.
- Open the document.
- Choose the More actions button (three dots) above the page, on the right, then Unpublish.
- Read the dialog Unpublish this document?: “The file is removed from the content repository, so sites no longer show it after their next build. The draft stays here and you can publish it again.” Choose Unpublish.
Expected result: Unpublished. appears, the document becomes a draft and its dot is hollow.
The unpublish is a commit too (Unpublish: <title>). It removes the document file and its manifest entry. Git still keeps the history.
Important
Unpublishing a document leaves its media published. The commit does not touch the picture files or their assets/<id>.json files, because other documents may use the same media. To take a file off the lake too, unpublish or trash the media separately (Publish media, Media library).
The menu item is greyed out when the document is not published.
Moving a published document to the trash unpublishes it as well (Trash).
Moving and renaming
- Renaming a document never changes its file name after the first publish, so the published path stays put.
- Moving a document to another folder is a change that waits for the next Publish.
- Moving or renaming a folder that holds published documents republishes them at once, in one commit, with the content they had when last published. The CMS asks first (Folders and tags).
What reaches the site
| What you do | What the lake has | When a site shows it |
|---|---|---|
| Edit a draft | Nothing changes | Never, until published |
| Publish | A new commit | After a developer refreshes the site’s lock and the site is built |
| Unpublish | A commit that removes the document file. Its media stays | After the same refresh and build |
| Move a published folder | One commit that moves the files | After the same refresh and build |
| Reorder published documents or folders | One small commit that changes only the items whose place changed (Reorder) | After the same refresh and build |
Links between documents are written as IDs, so they survive all of these. A link to a document that is still a draft works only once that document is published. The editor warns you with “Linked to a draft: the link works once it’s published”.
To see your draft on a site before you publish, use a preview (Previews).
If something goes wrong
A failed publish shows its reason in red next to the button, and the document stays as it was.
| What you see | What to do |
|---|---|
| “Fix the problems above, then publish again.” | The editor could not save. Fix the problem shown in the fields, such as an empty title, then publish again. |
| “‘guides/fleet-services.md’ is still used by another published document. Publish or unpublish that document first, or move this one.” | Another published document has the same folder and file name. Move one of the two to another folder, or unpublish the other. |
| “The document uses media that no longer exists: … Remove those references or upload the files again.” | The message lists the IDs. Each one is a file that is gone, in the trash, or an image that has no alt text and cannot be published without it. Remove it from the text, restore it, or add the alt text. |
| “The content repository could not be updated. Try again, and contact an administrator if it keeps failing.” | A problem on the server. Try once more. If it persists, tell an admin. |
| “The document no longer exists.” | The document was removed while you published. Look in the Trash. |
| Publish is greyed out | A publish is running, or someone else is editing. |
| There is no Publish button | The document is published and nothing has changed since. The button comes back when you change something. |
| “Could not start the publish.” | Check your connection and press Publish again. |
Pressing Publish twice while the first request is waiting does not make two commits.