From 3a3022b24c29d9bd58d6fb97a4923a65df7d9bf8 Mon Sep 17 00:00:00 2001 From: Rob Luton Date: Fri, 25 Sep 2026 09:59:25 -0500 Subject: [PATCH 1/2] preview base url docs --- content/guides/01.data-model/1.collections.md | 2 + content/guides/02.content/5.live-preview.md | 44 ++++++++++++++++++- 2 files changed, 45 insertions(+), 1 deletion(-) diff --git a/content/guides/01.data-model/1.collections.md b/content/guides/01.data-model/1.collections.md index bbe267a3..59ca58aa 100644 --- a/content/guides/01.data-model/1.collections.md +++ b/content/guides/01.data-model/1.collections.md @@ -97,6 +97,8 @@ Live preview is used on the [item page](/guides/content/editor) and allows for y Use item field values to construct the live preview URL, including unique identifiers and the content version, so you can preview draft content before publishing it. +Start the URL with the `{{$preview_base_url}}` variable to take the host from the [Preview Base URL](/guides/content/live-preview#set-a-preview-base-url) project setting instead of the schema. Each environment can then use its own host. + ::callout{icon="i-lucide-graduation-cap" color="secondary" to="/guides/content/live-preview"} Read the Live Preview guide. :: diff --git a/content/guides/02.content/5.live-preview.md b/content/guides/02.content/5.live-preview.md index a968cd53..459edef3 100644 --- a/content/guides/02.content/5.live-preview.md +++ b/content/guides/02.content/5.live-preview.md @@ -29,7 +29,49 @@ For more information, see the [Live Preview Reference Tutorials](#reference-tuto Navigate to Settings -> Data Model and select the collection you wish to configure. In the "Preview URL" section, specify the Preview URL for your project by selecting the field you wish to use to identify your object in your application from the dropdown and entering a URL in this format: `http://your-website-url/` -### Using Live Preview with Your Application +If your project runs on more than one environment, use a [Preview Base URL](#set-a-preview-base-url) instead of a hardcoded host. + +## Set a Preview Base URL + +The Preview URL is part of your collection's configuration, so it is included in schema snapshots. If the URL contains a hardcoded host, promoting the schema from development to staging to production copies that host into every environment. + +The **Preview Base URL** project setting solves this. You store only the path in the collection's Preview URL, and each Directus instance supplies its own host. + +1. Navigate to **Settings** > **Project** and find the **Live Preview** section. +2. Enter your website's base URL in **Preview Base URL**, for example `https://staging.example.com`, and save. +3. Navigate to **Settings** > **Data Model** and select your collection. +4. In the **Preview URL** field, select **Preview Base URL** from the variable dropdown, or type `{{$preview_base_url}}`. +5. Add the rest of the path after the variable, for example `{{$preview_base_url}}/blog/{{slug}}`. + +When you open the preview, Directus replaces `{{$preview_base_url}}` with the value from project settings. With the example above, the item with the slug `my-post` previews at `https://staging.example.com/blog/my-post`. + +You can combine the variable with others, such as `{{$version}}`: + +```text +{{$preview_base_url}}/blog/{{slug}}?preview=true&version={{$version}} +``` + +::callout{icon="i-lucide-info"} +**Variable Dropdown** +The **Preview Base URL** variable only appears in the Preview URL dropdown after you save a value in project settings. +:: + +### Use Live Preview Across Environments + +Now that the host lives in project settings, you can promote the same schema to every environment: + +1. On each Directus instance (for example development, staging, and production), set **Preview Base URL** to that environment's website URL. +2. Configure the collection's Preview URL once, using `{{$preview_base_url}}` followed by the path. +3. Promote the schema with the [Schema API](/api/schema) or [Environment Sync](/guides/environment-sync). The Preview URL carries only the path, so each instance resolves it against its own base URL. + +Each environment still needs its own `CONTENT_SECURITY_POLICY_DIRECTIVES__FRAME_SRC` value that matches its base URL, as described in the [pre-requisites](#live-preview-pre-requisites). + +::callout{icon="i-lucide-triangle-alert" color="warning"} +**Environment Sync and Project Settings** +Environment Sync includes the `settings` resource by default, and `preview_base_url` is part of that record. Pushing settings overwrites the target's Preview Base URL with the source's value. Exclude settings with `--no-settings`, or set the value again on the target after pushing. See [Configuration resources](/guides/environment-sync/reference#configuration-resources). +:: + +## Using Live Preview with Your Application Once configured, Directus will send a request to your application for a page with the specified URL format. For example, if you've configured the URL to be `https://mysite.com/posts/{id}`, and load the preview for the item with an `id` of `42`, then your application will receive a request to `https://mysite.com/posts/42`. You may choose to add `preview=true` to indicate to your client that it needs to treat this as a live preview. You may also choose to add an access token with the ability to view items as an additional URL query parameter. From d6585912a6e59c3d046ba15aa8e8b2d569613737 Mon Sep 17 00:00:00 2001 From: Rob Luton Date: Fri, 25 Sep 2026 10:10:46 -0500 Subject: [PATCH 2/2] add note about the trailing slash --- content/guides/02.content/5.live-preview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/guides/02.content/5.live-preview.md b/content/guides/02.content/5.live-preview.md index 459edef3..3a8f1787 100644 --- a/content/guides/02.content/5.live-preview.md +++ b/content/guides/02.content/5.live-preview.md @@ -38,7 +38,7 @@ The Preview URL is part of your collection's configuration, so it is included in The **Preview Base URL** project setting solves this. You store only the path in the collection's Preview URL, and each Directus instance supplies its own host. 1. Navigate to **Settings** > **Project** and find the **Live Preview** section. -2. Enter your website's base URL in **Preview Base URL**, for example `https://staging.example.com`, and save. +2. Enter your website's base URL in **Preview Base URL**, for example `https://staging.example.com`, and save. A trailing slash is ignored. 3. Navigate to **Settings** > **Data Model** and select your collection. 4. In the **Preview URL** field, select **Preview Base URL** from the variable dropdown, or type `{{$preview_base_url}}`. 5. Add the rest of the path after the variable, for example `{{$preview_base_url}}/blog/{{slug}}`.