Skip to content
mdlake

Previews

How to see a draft on the real website before you publish it - the Preview on button, what the preview page shows, how the preview site is set up by an admin and a developer, and what to check when the button is missing or the draft does not appear.

On this page

The editor shows your text, but not how the website will look. A preview opens your draft on the site itself, with its layout and design, without publishing anything. This page shows editors how to open a preview, and tells admins and developers what must be in place for it to work.

Before you start

  • Someone has set up a preview for your workspace. If a document shows no preview button, none is set up. See Set up a preview.
  • You know that a preview shows the saved draft. Publishing is separate (Publishing).

Open a preview

  1. Open the document. Wait until the status line above the page says Saved.
  2. Choose Preview on site name in the top right, next to Publish. If the workspace has more than one site, the button says Preview on… and opens a menu of the sites. Choose one.

Expected result: the site opens in a new browser tab, on the page that shows your document, with your unpublished changes. A banner says “Preview: drafts from the CMS — not deployable”.

Hover over the button for a hint: “Opens the site’s preview build. Drafts appear there once the site’s preview is set up.”

What the preview page shows

  • The page of the site that uses the document. The site decides where a document appears. The preview takes you there.
  • A plain page, if the site does not use the document. The page says “This document isn’t used on this site. It is shown here as the CMS has it.” It shows the title, summary and text in the site’s design.
  • Drafts, not the published version. For a document that has never been published, you see the draft. For a document with unpublished changes, you see the changes.
  • Images that are not published yet. They show in the preview too.

The preview is not a public page. Search engines are told to ignore it. Do not share its address outside your team.

Keep the preview open while you write

The preview site reads the CMS directly, so it does not need a build. Save your change, wait for Saved, then reload the preview tab. Changes appear within a few seconds. You do not need to ask a developer.

Note

The preview does not save for you. If you opened it while the status line said Saving… or Unsaved changes, reload it after the line says Saved.

What a preview does not show

  • What the live site shows today. The preview shows drafts. The live site shows the last build, from a locked commit of the lake (Publishing).
  • Other people’s unsaved typing. It shows saved drafts only.

Set up a preview

A preview needs two things: a preview site that runs somewhere, and its address in the CMS. Each is a different person’s task.

In the CMS (admin)

  1. Open the workspace and choose Workspace settings in the header.

  2. Under Sites, choose Add site. You can add up to 10.

  3. Fill in:

    FieldWhat to enter
    NameThe name editors see on the button, for example “Company site”. Up to 100 characters.
    Preview addressThe address of the preview site. It must start with https://. For development, http://localhost is also accepted. For example http://localhost:4400.
    Live address (optional)The public address of the site. The CMS only stores it.

  4. Use the arrows to put the main site first. Choose Save.

Expected result: “Saved.” appears, and every document in the workspace now shows the Preview on button.

The CMS does not check that the address works. It only uses the address to build a link: the preview address with ?mdlakeDoc= and the document’s ID added, for example https://preview.example.com/?mdlakeDoc=01M5YPMJRG2SN2C75GJWV9DAWF. Any other parts of the address are kept.

On the site (developer)

The preview site is the normal site started in preview mode. It needs a token that is allowed to read drafts. In short:

  1. In the CMS, make a workspace token with the access Published content and drafts (Workspace tokens).

  2. Put MDLAKE_API_URL and MDLAKE_TOKEN in the site’s .env.

  3. Start the preview server:

    Bash
    npx mdlake preview --port 4400
    PowerShell
    npx mdlake preview --port 4400

  4. Enter the address it prints, such as http://localhost:4400, as the Preview address of the site in the CMS.

The full steps, options and hosting of a preview server are in Preview drafts.

Warning

A preview contains unpublished drafts. Never deploy it to the production site. The site build refuses to run in preview mode unless you pass --preview-deploy, which is only for a host that editors alone can reach.

If something goes wrong

What you seeWhat to do
No Preview on buttonNo site is added in Workspace settings. Ask an admin.
The new tab does not loadThe preview server is not running or the address is wrong. Ask the developer. For a local address such as localhost, the preview only works on the computer that runs the server.
The page loads but shows the published textThe site is not in preview mode, or the token is not Published content and drafts. Ask the developer.
The page says “This document isn’t used on this site.”The site has no page for this document. That may be right. Ask a developer if it should have one.
Your latest edit is missingWait for Saved and reload the tab.
“Preview: drafts from the CMS — not deployable” is missing, and the site looks liveYou are on the live site, not a preview. Check the Preview address in Workspace settings.
An unpublished image stops showing after a whileThis happens with a static preview build, whose links to unpublished images expire after 15 minutes. Ask the developer to use the preview server instead.

What’s next