Skip to content

Manage releases

A release is a frozen snapshot of your content at a point in time. Use releases to line documentation up with product versions, to keep a record you can compare against later, and to see exactly what changed between two versions.

Before you begin

This feature requires the Enterprise capability tier (the Business ). During the beta, every project is on the free Solo tier, so this feature is locked by default: go to Settings ▸ Billing and request Enterprise access to unlock it.

  • Every topic being snapshotted, and every component those topics reference, must be free of draft paragraphs and unresolved suggestions. A component nothing references does not block a release. See Clear the release gate.

  • A release freezes the content on your main line of work. Work sitting on a branch enters a release by being merged first.

Release lifecycle

Status

Meaning

Draft

In preparation: maps can be added or removed, and the release can be deleted

Published

Frozen: a snapshot of every topic in the included maps has been captured. The list groups these under Published; the release's own page badges it Finalized

Archived

Historical: no longer active, kept for reference and comparison

Snapshot everything now

The fastest route, and the one to use when a release matches "the docs as they are today":

  1. Open Publishing in the sidebar and choose Releases.

  2. Click Snapshot current. The project needs at least one map, or the snapshot is refused.

  3. Enter a name, for example v1.0, and optionally release notes describing what changed.

  4. Click Snapshot.

This creates the release, includes every top-level map, and freezes the content in one step. The result is immediately final: snapshotted releases can be compared but not edited.

Build a release map by map

Use this route when a release should cover only some of your maps:

  1. Go to Publishing > Releases and click New release.

  2. Enter a name and optional release notes, then click Create. The new release appears under Draft in the list. Click it to open it.

  3. Click Add map and pick a map. Repeat for each map you want included.

  4. Click Publish, then confirm in the Publish release? dialog.

Publishing captures a frozen snapshot of every topic in the included maps. Later edits to those topics do not change the snapshot. The Publish button stays disabled while the release has no maps in it.

Publishing a release is a one-time action. The snapshot cannot be edited afterwards. To capture a newer state, create another release.

A release is frozen, but your published web sites are not: they keep serving your current content from a cache. Publishing a release changes nothing on them.

Changes to content reach your published site within 24 hours as its cache refreshes. To push updates live right away, click Update on the affected .

Clear the release gate

Unfinished content blocks a release the same way it blocks publishing a site. If any topic still carries a draft paragraph or an unresolved track-changes suggestion, or any component it references does, the Releases page shows a banner: N unfinished blocks must be resolved before this project can be snapshotted as a release. Under it is one link per offending block, up to 8, then a count of the rest. Snapshot current is disabled, and its tooltip gives the count as N unfinished blocks must be resolved first.

Publishing a draft release runs the same check when you confirm. If anything is unfinished, the release is refused and the message names the blocking paragraphs, for example Cannot release: 2 draft paragraphs. Getting started — block 3: draft paragraph (…).

Resolve each block in the editor, then try again. The banner's links take you straight to the paragraph. The refusal message names the same paragraphs but is plain text, so find them from the banner rather than from the message.

The banner counts unfinished blocks across every top-level map in the project, while Publish on a draft release checks only the maps that release contains. A draft release can therefore publish while the banner is still showing.

Archive a release

  1. Open a published release.

  2. Click Archive and confirm.

Archived releases stay available for reference and comparison but are no longer treated as active. You can also archive from the kebab menu on the Releases list.

Compare two releases

  1. Open a published or archived release.

  2. Scroll to Compare releases and pick another release in Compare with.

The comparison lists three groups:

  • Added: topics the release you have open contains, but the one you picked in Compare with does not

  • Removed: topics the release you picked in Compare with contains, but the one you have open dropped

  • Changed: topics in both, with block-level diffs you can expand, and a "Title changed" marker where the title moved

The comparison reads from the point of view of the release you have open: it is the current side, and the one you pick in Compare with is the baseline. So open the newer release, pick the older one, and Added lists what the newer release gained. In the block-level diffs, added lines are the open release's text.

Compare the previous release with the current one to draft release notes. The Changed group gives you the exact paragraphs that moved, so the notes describe real edits rather than a guess.

See also

See also

Was this page helpful?