Preview drafts

Run the site against the CMS drafts so that editors can see unpublished changes on the real design. Covers the token, the preview server, the Preview button and the limits.

A snapshot site shows only published content at a pinned commit. Editors also want to see a draft on the real site before they publish it. The preview server does that. It is a development server that reads the CMS’s drafts through its API instead of the lake clone. An editor presses Preview on in a document and lands on the page of the site that shows it.

Preview is not a mode of the site. It ignores lake.lock, it never changes it, and nothing from a preview can be deployed.

What you do

Create a token that can read drafts.
Put the API address and the token in the site’s .env.
Start the preview server.
Tell the CMS where the preview server is.

Step 1: create a preview token

In the CMS, open Workspace settings, then AI and API access, and press New token. Choose the access Published content and drafts. This is the preview scope. Give it a name such as “Draft preview”. Press Create token and copy the secret. It is shown only once.

Warning

A preview token can read unpublished work. Use it only on computers or hosts that are not public. Keep it out of Git. See Workspace tokens.

The same token can have Can report AI usage as well. A token for developers can then do everything the site needs.

Step 2: add it to .env

In the site’s .env, which Git ignores:

MDLAKE_API_URL=https://cms.example.com/api/lake/acme
MDLAKE_TOKEN=mdl_...

MDLAKE_API_URL is the workspace’s read API, https://<cms>/api/lake/<workspace slug>. The workspace settings show it in the connection guide. The token is read from the environment or .env only. It is sent in the Authorization header, removed from every error message, and never written to dist/, to pages or to logs.

Step 3: start the preview server

In your own terminal:

PowerShell

npm run preview:cms

That runs mdlake preview. You can call it directly and set the port:

PowerShell

npx mdlake preview --port 4400

Option	Default	Meaning
`--port`	`4400`	The port. If it is in use, the command stops and says so, because the CMS stores one address.
`--host`	`localhost`	The host to bind.

The command prints the address to give the CMS:

Preview of https://cms.example.com/api/lake/acme
  http://localhost:4400/   (set this as the site's previewUrl in the CMS; the Preview button adds ?mdlakeDoc=<id>)

It starts astro dev in preview mode with MDLAKE_PREVIEW=1 and --ignore-lock. It runs next to a normal npm run dev of the same site, because they use different ports. If MDLAKE_API_URL or MDLAKE_TOKEN is missing, the command stops and says which.

Every page carries this banner and is marked noindex:

Preview: drafts from the CMS — not deployable

The server asks the CMS for changes every 5 seconds and loads only the documents whose summary changed, using ETags. An editor’s change is on the page without a restart. Set MDLAKE_PREVIEW_POLL (in milliseconds) to change the interval.

Step 4: set the Preview address

In the CMS, open Workspace settings and find Sites. Press Add site if the list is empty. Fill in:

Field	Value
Name	The site’s name. It appears on the button.
Preview address	`http://localhost:4400`, or the address of the computer that runs the preview. It must be `https`, or `http://localhost` while you develop.
Live address (optional)	The production address.

Press Save. A workspace can list up to 10 sites.

From now on every document has a Preview on Site name button. With more than one site it is a menu, Preview on…. The button opens <Preview address>?mdlakeDoc=<document id> in a new tab. See Previews for the editor’s view.

How a document finds its page

?mdlakeDoc=<id> can be put on any URL of the preview server.

If a page of the site shows the document, following src/pages.config.ts, the server redirects there.
If no page shows it, the server opens /_mdlake/doc/<id>/, a plain page with the document and the note “This document isn’t used on this site. It is shown here as the CMS has it.”
An unknown ID is a 404.

Limits and rules

Never deploy it. astro build refuses to run while MDLAKE_PREVIEW is set. For a static preview on a host that only editors can reach, build with astro build --preview-deploy (or MDLAKE_PREVIEW_DEPLOY=1). The layout then carries a small script that does the ?mdlakeDoc redirect.
Signed links expire. Unpublished images are served with signed links that last 15 minutes in a static --preview-deploy build. Prefer the dev server.
Remote assets skip the image pipeline in a preview, because unpublished ones have short-lived links.
Drafts only reach people who see the server. localhost works for you. For other editors, run the preview on a machine they can reach, and use https.
Production builds need no token. They read the lake from Git.

What can go wrong

Symptom	Cause and fix
`mdlake preview needs MDLAKE_API_URL and MDLAKE_TOKEN`	One or both are missing in `.env` and the environment.
`Port 4400 is in use`	Stop what runs there, or pick another port with `--port` and set the same address as Preview address.
The button is not there	The workspace has no site in Sites.
The page shows “This document isn’t used on this site”	The document is not on any page of the plan. That is correct for a document the site does not show.
No drafts show up	Check that the token’s access is Published content and drafts. A token with Published content is for builds and AI tools. The CMS answers a request for drafts from such a token with `403` and “The published scope cannot read drafts.”, and the preview server stops with a message that reading drafts needs a token with the preview scope.
`astro build` stops with a message about `MDLAKE_PREVIEW`	Unset the variable for production builds.

What’s next

Refresh content to take published content into the site.
Previews for what editors do with the button.