Draft publishing workflow documentation

content/guides/01.data-model/1.collections.md

@@ -35,7 +35,7 @@ The primary key field contains a unique value for each item in the collection. T
 
 The primary key type defines the strategy for creating unique primary keys. Once selected, this cannot be modified.
 
-Additionally, Directus can create some common fields, including a status field, sort, as well as fields related to who and when items are created or edited. Directus supports the following types of IDs:
+Additionally, Directus can create some common fields, including an archived field, sort, as well as fields related to who and when items are created or edited. Directus supports the following types of IDs:
 
 - **Auto-Incremented Integer**: IDs increment from `1` to `2^31-1` (`2,147,483,647`).
 - **Auto-Incremented Big Integer**: IDs increment from `1` to `2^63-1` (`9,223,372,036,854,775,807`). This is only available if using MySQL and PostgreSQL as your database.
@@ -66,7 +66,7 @@ Once a collection is created, there are a number of configuration options availa
 
 Content versioning is used by :product-link{product="editor"} and allows teams to create and manage different versions of their content. There are several reasons to use content versioning, including drafting content without publishing it, and more ways to collaborate with others.
 
-This feature can be enabled for specific collections, and will be available for all items. Once enabled, item versions can be created, and later have some or all fields promoted to the main version, typically used for publishing.
+This feature can be enabled for specific collections, and will be available for all items. Once enabled, item versions can be created, and later have some or all fields published to the main version.
 
 ::callout{icon="material-symbols:menu-book-outline" color="primary" to="/guides/content/content-versioning"}
 Read the content versioning user guide.
@@ -76,7 +76,7 @@ Read the content versioning user guide.
 
 Live preview is used by :product-link{product="editor"} and allows for your application to be shown in a pane next to your content, which can be used for previewing content before publishing.
 
-You can use item field values to construct the URL used by the live preview, including unique identifiers and content version, allowing for previewing content versions before promoting them to the main version.
+You can use item field values to construct the URL used by the live preview, including unique identifiers and content version, allowing for previewing content versions before publishing them to the main version.
 
 ::callout{icon="material-symbols:school-outline" color="secondary" to="/tutorials/getting-started"}
 Read tutorials on implementing live preview.
@@ -124,6 +124,8 @@ When you duplicate an item, any related items are not copied. You must create ne
 
 Archived items still exist in your collections, but are filtered within the Data Studio. If not selected as an optional field when creating a collection, you will need to create a new field.
 
+When creating a collection via the wizard, the optional `archived` field is a **boolean** type. The archive value is `true` and the unarchive value is `false`. If you create an archive field manually, you can use any string or boolean field.
+
 To configure an archive field, set the following four input fields as desired.
 
 - **Archive Field**: selects the archive field.

content/guides/02.content/1.explore.md

@@ -40,6 +40,26 @@ The following dynamic variables are built into Directus to add extra functionali
 
 :video-embed{video-id="a0f37f8b-c789-4421-b6c4-e4f681028d66"}
 
+## Browsing Draft Versions
+
+When [content versioning](/guides/content/content-versioning) is enabled for a collection, a **Published/Draft** selector appears in the collection page header. Use it to switch between viewing published items and their draft versions.
+
+### Draft Mode Behavior
+
+In draft mode, the collection page shows items that have pending draft changes, including [itemless drafts](/guides/content/content-versioning#creating-new-items-as-drafts) that have not yet been published. Click on any item to open it directly in its draft version.
+
+The following actions are **disabled** while in draft mode:
+
+- Batch editing
+- Archiving items
+- Exporting items
+- Manual sorting
+- Running Flows from the sidebar
+
+### Batch Deleting Drafts
+
+Selecting multiple items in draft mode and deleting them removes the **draft versions only** - the published items remain untouched. This is useful for discarding draft changes in bulk without affecting live content.
+
 ## Layouts
 
 Layouts are customized mechanisms for viewing and interacting with the items in a collection. You can [select a layout](/guides/content/layouts) for displaying your collection. Note that restrictions will apply depending on your collection's [data model](/guides/data-model/collections).

content/guides/02.content/6.content-versioning.md

@@ -10,11 +10,11 @@ use content versioning, including drafting content without publishing it, and mo
 
 ## Concepts
 
-- **Version**: A version of an item that allows you to safely make changes without affecting the main item. Versions can be promoted to become the new main item.
-- **Main**: The published version of your content that is live and visible to users. All new versions are created from the main item.
-- **Draft**: a reserved global version that is automatically available when content versioning is enabled. The draft version provides a dedicated workspace for making changes before publishing to main, and appears empty until edits are saved.
-- **Promote**: when a version is promoted, it becomes the main item that is displayed to users.
-- **Revision**: revisions are individual changes to items made within a version or main item. Directus keeps track of all changes made, so you're able to view the history of modifications and revert to a previous state.
+- **Version**: a version of an item that allows you to safely make changes without affecting the published item. Versions can be published to become the new published item.
+- **Published**: the published version of your content that is live and visible to users. All new versions are created from the published item. This version is identified by the reserved key `published` (the key `main` also works and is kept for backward compatibility).
+- **Draft**: a reserved global version that is automatically available when content versioning is enabled. The draft version provides a dedicated workspace for making changes before publishing, and appears empty until edits are saved.
+- **Publish**: publishing a version makes it the published item that is displayed to users. Use the **Publish** button in the item header to publish the currently viewed version.
+- **Revision**: revisions are individual changes to items made within a version or the published item. Directus keeps track of all changes made, so you're able to view the history of modifications and revert to a previous state.
 
 ::callout{icon="material-symbols:info-outline" to="/guides/content/live-preview"}
 **Using Versions in Live Preview**  
@@ -27,12 +27,27 @@ The version field is a dynamic variable can be added to the live preview URL so
 
 Navigate to **Settings** > **Data Model**, select the collection that you want to enable content versioning for, and scroll down to the content versioning section. Toggle "Enable Versions" and save your data model.
 
+## Editing Versioned Items
+
+When content versioning is enabled for a collection, the published view is **read-only**. Fields are disabled and no Save button is shown. This enforces a draft-first workflow — all edits go through a version before reaching the published item.
+
+To start editing, click the **Edit** button in the item header (or press `⌘E` on Mac / `Ctrl+E` on Windows). Directus automatically switches you to the draft version, where you can make and save changes freely.
+
+::callout{icon="material-symbols:info-outline"}
+**Why read-only?**
+Preventing direct edits to the published item ensures changes go through the versioning workflow. This keeps your published content stable and gives your team a review step before changes go live.
+::
+
 ## Working with the Draft Version
 
 When content versioning is enabled for a collection, a global draft version is automatically available for all items. This reserved version provides a safe workspace for preparing changes before publishing to your live content.
 
 ![Content versioning draft](/img/versioning-draft.png)
 
+### Browsing Drafts from the Collection Page
+
+The [collection explorer](/guides/content/explore#browsing-draft-versions) includes a **Published/Draft** selector in the page header for versioned collections. Switch to draft mode to browse all items with pending draft changes across every layout (tabular, cards, calendar, kanban, and map). Some bulk actions like batch editing, archiving, and exporting are disabled in draft mode.
+
 ### Understanding the Draft Version
 
 The draft version:
@@ -41,6 +56,11 @@ The draft version:
 - Transforms from a virtual placeholder to an actual version when you save changes
 - Uses "**draft**" as a reserved version key that cannot be used for custom versions
 
+::callout{icon="material-symbols:info-outline"}
+**Reserved version keys**
+The keys `published`, `main`, and `draft` are all reserved and cannot be used for custom versions. Attempting to create a version with any of these keys returns a `400` error.
+::
+
 ::callout{icon="material-symbols:warning"}
 **Backward Compatibility**  
 The reserved global "draft" version was introduced in Directus 11.16.0. If you have an existing version with the key `draft` and a custom name other than "Draft", the display name will be standardized to "Draft" (i.e. transformed) to support the new global versioning feature. The version content and functionality remain unchanged.
@@ -50,54 +70,87 @@ The reserved global "draft" version was introduced in Directus 11.16.0. If you h
 
 The Visual Editor integrates seamlessly with the draft version, allowing you to preview and edit changes in context:
 
-1. **Switch versions** using the dropdown in the Visual Editor header to toggle between "Main" and "Draft"
+1. **Switch versions** using the dropdown in the Visual Editor header to toggle between "Published" and "Draft"
 2. **Edit items** that have content in the active version – items are only directly editable when they exist in the selected version
-3. **Preview changes** using the version-aware preview URL before publishing to main
-4. **Fallback behavior** - items without content in the selected version display their main version content (read-only)
+3. **Preview changes** using the version-aware preview URL before publishing
+4. **Fallback behavior** - items without content in the selected version display their published version content (read-only)
+
+
+## Creating New Items as Drafts
+
+In a versioned collection, clicking **"Create Item"** (the `+` button) automatically puts you into draft context. Instead of creating the item immediately, Directus opens the form in the draft version - no published item exists yet.
+
+### Saving an Itemless Draft
 
+Fill in your fields and save as normal. On first save, Directus creates a draft version with no published item backing it. The item does not yet exist in the collection.
+
+You can save as many times as needed. Required fields do not need to be complete at this stage - see [Making Changes to a Version](#making-changes-to-a-version).
+
+### Publishing an Itemless Draft
+
+When you are ready to publish, select **"Publish Version"** from the version dropdown. Because there is no existing item to compare against, Directus skips the comparison modal and creates the item directly.
+
+After publishing, you are redirected to the newly created item in its main version.
+
+::callout{icon="material-symbols:info-outline"}
+**Permissions**
+Publishing an itemless draft creates a new item, so it requires **create** permission on the collection - not edit permission.
+::
 
 ## Creating a New Version
 
 ![Creating a new version in the content module](/img/versions-example.png)
 
-Open an item within your versioned collection. At the top of the item view, you will notice a dropdown with the main Content Version displayed as "main". Select "Create Version" and provide a key and a name for the new version. You can then save your new version.
+Open an item within your versioned collection. At the top of the item view, you will notice a dropdown with the published content version displayed as "Published". Select "Create Version" and provide a key and a name for the new version. You can then save your new version.
 
 ::callout{icon="material-symbols:info-outline"}
 **Version Source**  
-All new versions originate from the main item. This implies that the main item acts as the single source of truth for other versions. The draft version is always available and doesn't need to be manually created.
+All new versions originate from the published item. This implies that the published item acts as the single source of truth for other versions. The draft version is always available and doesn't need to be manually created.
 ::
 
 ## Making Changes to a Version
 
 ![Editing a version](/img/versioning_update.png)
 
-Open the item in the newly created version, and make the desired edits to the item's content.
+Open the item and switch to the version you want to edit using the version dropdown. The published view is read-only — you must be in a version context (draft or any custom version) to make changes.
 
 Upon saving the changes, you'll notice that the main item remains unaffected, while the changes are reflected only in the modified version.
 
-## Comparing and Promoting a Version
+::callout{icon="material-symbols:info-outline"}
+**Required Fields**
+Versions can be saved even if required fields are empty. Validation of required fields is deferred to publish time, so you can save partial drafts without completing all required fields.
+::
+
+## Comparing and Publishing a Version
+
+![Publishing a version, comparing its changes](/img/versions-example-comparison.png)
 
-![Promoting a version, comparing its changes](/img/versions-example-comparison.png)
+Publishing a version makes it the published (current) version of your content.
 
+Publishing a version makes it the published (current) version of your content.
 
-Promoting a version makes it the main (current) version of your content.
+### How to Publish a Version
 
-### How to Promote a Version
+1. Open the version you want to publish
+2. Select the **"Publish Version"** option from the dropdown.
+
+::callout{icon="material-symbols:warning"}
+**Required Field Validation**
+If the version has missing required fields, Directus will display field-level validation errors and a notice banner. The comparison modal will not open until all required fields are filled in.
+::
 
-1. Open the version you want to promote
-2. Select the **"Promote Version"** option from the dropdown. 
 3. In the comparison modal, review the changes:
-   - Fields with differences from the main item are highlighted with color indicators
+   - Fields with differences from the published item are highlighted with color indicators
    - Review each highlighted field to understand what will change
 4. Accept or reject individual changes as needed
-5. Click **"Promote"** to finalize and make this version the new main item
+5. Click **"Publish"** to finalize and make this version the new main item.
 
-Once promoted, this version becomes the active content, and the previous main item is preserved in the version history. 
+Once published, this version becomes the active content, and the previous published item is preserved in the version history.
 
-After promoting a version, you can choose to keep or delete the version. For the global draft version, you'll see options to "Discard Edits" or "Keep Edits" instead of "Delete Version" or "Keep Version".
+After publishing a version, you can choose to keep or delete the version. For the global draft version, you'll see options to "Discard Edits" or "Keep Edits" instead of "Delete Version" or "Keep Version".
 
 ::callout{icon="material-symbols:info-outline"}
-**Programmatically Implement Content Versioning**  
+**Programmatically Implement Content Versioning**
 You have the option to integrate Content Versioning through the API. To learn how to accomplish this, please refer to
 our [API reference documentation](/api/versions).
 ::
@@ -184,7 +237,7 @@ When working with content versioning through the API, it's important to understa
 
 ### Standard Item Response
 
-When fetching items from a collection endpoint `/items/{collection}`, you receive the main version data:
+When fetching items from a collection endpoint `/items/{collection}`, you receive the published version data:
 ```json
 {
   "data": [
@@ -223,4 +276,4 @@ When fetching versions from the `/versions/{version}` endpoint, each version con
 }
 ```
 
-The `delta` object contains only the modified fields, making it easy to see exactly what changed in each version compared to the state of main at the time that version was created.
+The `delta` object contains only the modified fields, making it easy to see exactly what changed in each version compared to the published item at the time that version was created.

content/guides/02.content/8.visual-editor/2.studio-module.md

@@ -27,7 +27,7 @@ The URL field supports a `{{$version}}` template variable. When included, the Vi
 https://your-site.com/preview?version={{$version}}
 ```
 
- - **Resolution**: When no version is selected, `{{$version}}` resolves to `main`. 
+ - **Resolution**: When no version is selected, `{{$version}}` resolves to `published`.
  - **Flexibility**: The variable can be placed in any part of the URL (query parameters, path segments, subdomains, or hash fragments).
 
  #### Implementation Checklist
@@ -37,7 +37,7 @@ https://your-site.com/preview?version={{$version}}
  **1. Frontend Integration**
   - **Template Variable**: You must include `{{$version}}` in the URL field. If omitted, the version selection dropdown will not appear in the Visual Editor toolbar.
   - **Directus Frontend Library**: Your website must be configured using our publicly available [Frontend Library](1.frontend-library.md).
-  - **Version-Aware Fetching**: Your code must detect the version parameter from the URL and pass it to the Directus API (e.g., `/items/posts/42?version=draft`). Without this, the site will continue to display "Main" content regardless of your selection.
+  - **Version-Aware Fetching**: Your code must detect the version parameter from the URL and pass it to the Directus API (e.g., `/items/posts/42?version=draft`). Without this, the site will continue to display "Published" content regardless of your selection.
 
   **2. Environment Configuration**
 
@@ -86,18 +86,18 @@ When a URL includes the `{{$version}}` variable, a version dropdown appears in t
 
 The dropdown lists:
 
-- **Main** — the published version (default)
+- **Published** — the published version (default)
 - **Draft** — the global [draft version](/guides/content/content-versioning#working-with-the-draft-version), always available for collections with versioning enabled
 
-If your website URL contains a version key that doesn't match "main" or "draft" (e.g. from a custom query parameter), it will also appear as a dynamic option in the dropdown.
+If your website URL contains a version key that doesn't match "published", "main", or "draft" (e.g. from a custom query parameter), it will also appear as a dynamic option in the dropdown.
 
 ### Version-Aware Editing
 
-When a version other than main is selected:
+When a version other than "Published" is selected:
 
 - **Only items on collections with versioning enabled** will show editable elements. Items on non-versioned collections are hidden from editing.
 - **Saving an edit** creates or updates the version for that specific item. If the version doesn't exist yet for the item, it's created automatically on save.
-- **Items without content in the selected version** display their main version content as a read-only fallback.
+- **Items without content in the selected version** display their published version content as a read-only fallback.
 
 ::callout{icon="material-symbols:info-outline"}
 The version dropdown requires the user to have **read** permission on `directus_versions`. Editing in a version additionally requires **create** or **update** permission on `directus_versions`.