Every page record has two parts that matter here: the page itself (what Build Studio edits and saves) and, once it is published, a live copy made at that moment. What a visitor sees depends on one site setting, Published pages only (site.data.publishedPagesOnly), and that setting changes what every button below does.
For making the page, see Build a website page. For which page answers at which URL, see How a site's addresses route.
Site serves drafts (publishedPagesOnly off, the default) | Published pages only | |
|---|---|---|
| A page never published | Live at its URL from its first save | 404 |
| A save after publishing | Shows at once | Not shown; the live copy still shows |
| Publish | Records this version as published. Nothing changes for visitors. | Makes this version what visitors see |
| Unpublish | Nothing changes for visitors: the page still answers at its URL | The page is a 404 |
Preview (/__preview/page/…) | The latest save | Only the live copy. A page never published is a 404 there too. |
The shared header and footer (root) and a parent page | Around every page | Not shown on any page (see the warning) |
| The home page | Shows | A 404 until it is published |
| The sitemap | Lists the pages | Lists the published pages |
Tested on a local site (the published-only column with the setting switched on for under a second, then back), except the sitemap row, which is read from the code (appengine site/site.service.ts 1646).
On a site with Published pages only, published pages render without the site's header and footer, and without their parent page. The engine adds root and the parent only to records of type page, and a live copy is stored as type published (appengine repositories/repository.enrichment.service.ts 63–87, repository.crud.service.ts 1731). Tested: the header is missing. Don't switch the setting on for a site that relies on root until this is fixed.
Ask first
- Which page, on which site? By its URL or name.
- Does the site show drafts? Read it in step 1 before saying what a button will do. On a site that serves drafts, "take it off the site" needs a delete or a rename, not Unpublish.
- Publish: the version on the canvas, or what is saved? Build Studio's Publish saves the canvas first.
- Restore: which version? By the date and time of the save, from the list in step 5.
- Delete: are you sure, and what points at it? The home page setting, child pages, a site feature, links on other pages and in emails.
Steps
1. Site Config: read the site and the page
repo_find on site with { "data.name": "<site>" }, then repo_find_one by its id. Note data.publishedPagesOnly (missing or false = drafts are served; a new site starts false) and data.homePage. In Build Studio it is Site Config (the gear beside the site in the toolbar's site switcher) › Pages › Published pages only, "Visitors never see a draft, even with its link."
Read the page with repo_find_one on page. Its status, as Build Studio shows it on the toolbar badge and in page lists (Build Studio publish-status.tsx 17–35):
state | publishedDate | Badge | Means |
|---|---|---|---|
published | set | Published | The live copy is this version |
draft | set | Unpublished changes | Saved since the last publish; the live copy is older |
draft | empty | Not published | No live copy |
Every save makes the page draft (appengine repository.crud.service.ts 1506), so the badge moves from Published to Unpublished changes on the next save. The live copy itself: repo_find_one on published with the page's id (same id as the page; 404 when there is none).
Hands on: the site's publishedPagesOnly, the page id, its badge.
Check: the badge in Build Studio (/app/build-studio/<page name>) matches the table.
2. Build Studio: preview it
- Preview (the projector button) switches the canvas to preview mode in Build Studio. It doesn't go through the site, so variants, the header and footer and page code from the server don't apply.
- Open in a new tab (the arrow-out button, "Full functionality with external loading") opens
https://<site host>/__preview/page/<site name>/<page name>?email=<your email>&preview=true&external=true. The extra parameters do nothing on the site. The address takes the page's name, slug or id.
/__preview/page/<site>/<page> renders the page through the site's own pipeline, with its header, footer, variants and page code, at any address the page could have.
- A preview link is public. It needs no sign-in (tested without one). Don't send it around for a page that must stay private.
- On a site with Published pages only, the preview shows the live copy, never the unsaved or unpublished version, and a page never published is a 404. Check a draft there in the canvas preview instead.
There is no working QR code preview: Build Studio has a QR component for it, but nothing opens it and it points at a placeholder address (preview-qr.tsx 21).
Hands on: the preview URL. Check: it shows the version you expect (the latest save, or on a published-only site the live copy).
3. Build Studio: publish
In Build Studio: Publish on the toolbar (or the Publish button beside a page in the Build Studio home lists). The toolbar button saves the canvas, asks whether the org reviews publishing (step 4), then publishes. It is greyed out on a page never saved.
Through the API: call_appengine POST /repository/publish/page/<page id>, no body.
| Answer | Means |
|---|---|
"published" | A new live copy was made from the page as it is saved now |
"already published" | Nothing changed since the last publish; nothing was done |
400 page <id> not found | Wrong id |
What happens (appengine repository.crud.service.ts 1709–1735): the old live copy is deleted; the page is saved once more, so its version goes up by one and a history entry is kept; it is marked published with today's publishedDate; a full copy of it becomes the live copy, under the page's own id. A publish counts as "nothing changed" only when the version and the data, post, style and requiredRole all match the live copy.
Publishing from the API skips the publishing review. When the org reviews publishing, ask first (step 4) and publish only on allowed.
Stop: publishing puts this version in front of visitors on a published-only site. Show the person the page, its preview URL and its address, and wait for yes.
Hands on: the answer, and the page's new version and publishedDate.
Check: the badge says Published; repo_find_one on published with the page id has the content you published; on a published-only site the page's URL shows it.
4. Approvals: publishing review, when the org has it on
An org can make every publish of a page, post, product or form wait for a reviewer. It is the workflow publish-approval ("Publishing approval"), created switched off (appengine workflow/workflow-setup.service.ts 278–296).
Ask before publishing: call_appengine POST /approval/ask with
{ "target": { "kind": "record", "operation": "publish", "datatype": "page", "id": "<page id>" } }decision | Do |
|---|---|
allowed | No review here. Publish (step 3). Tested with the workflow off. |
pending | A request went to the reviewers (by default anyone with the ContentAdmin, Publisher or Owner role; the Owner is reminded after 2 days). Don't publish; tell the person who it waits on (approvers). |
already-pending | A request for this page is already open. Don't make another. |
Who reviews, and switching the review on, is on Approvals: publishing review and access requests.
When a reviewer approves it (in their Approvals tray), the engine publishes the page as it is saved at that moment, not as it was when the request was made (approval/approval.service.ts 437–442). Edits made while it waits go live with it.
Build Studio's Publish button asks the same question and opens the request for you (so do posts and CRM forms; product screens don't ask). The page's own Workflow tab (request approval / approve) is a different thing: approving there doesn't publish.
Hands on: the decision, and the request's taskId when pending.
Check: pending: the request is in the Approvals tray; allowed: go on to step 3.
5. Build Studio: unpublish
In Build Studio: Unpublish next to the badge (click it twice), shown whenever the page has been published. In the Build Studio home lists the button shows only on pages whose badge is Published. In Page settings › History, the purple live-copy row has a red unpublish button that acts on one click.
Through the API: call_appengine POST /repository/unpublish/page/<page id>. It answers "unpublished" every time, even when there was no live copy.
What happens (repository.crud.service.ts 1742–1757): the live copy is deleted, and the page becomes draft with no publishedDate (badge Not published). Its content is kept.
On a site that serves drafts, Unpublish takes nothing off the site. The page still answers at its URL with its latest save (tested: 200). Build Studio's tooltip says "Take this page off the live site" either way. To really take a page down there, delete it (step 7), or rename its slug and name if it must stay.
Stop: on a published-only site the page becomes a 404, and links to it break. Name the URL and wait for yes.
Hands on: the answer.
Check: repo_find_one on published with the page id is a 404; the site's URL is a 404 (published-only) or still the page (drafts served), as you told the person.
6. Build Studio: go back to an earlier version
Page settings › History lists the versions (GET /repository/history/page/<page id>):
- First, when there is one, the live copy (purple, type
published). - Then up to 10 versions (type
history), newest first. Each is the page as it was saved at that version, the current one included. A version is kept on every save that changes the page'sdata(pages keep history by default); a change made withupdate-partialkeeps none. - View … at this point shows that version's data, and also loads it into the canvas. To go back, use Restore, not View and then Save.
Restore (the arrow, click twice) or call_appengine POST /repository/history/restore with
{ "datatype": "page", "id": "<page id>", "historyId": "<the version's _id>" }What happens (appengine history/history.service.ts 219–239): the page's data, post, style and workflow become that version's; version goes up by one; Build Studio reopens the page. Tested:
- The live copy is not touched. On a published-only site visitors still see the old live copy. Publish again (step 3) to put the restored version live.
- The status is not changed. Restoring on a page whose badge says Published leaves it saying Published, though the page now differs from the live copy. Always publish after restoring on a published-only site.
- The restored version is not added to History until the next save. The version you left is still in the list, so you can go back again.
- The live copy's row can't be restored (400
History <id> not found); restore ahistoryrow.
On a site that serves drafts, the restored version is live as soon as it is restored.
Stop: on a site that serves drafts this changes the live page at once. Say which version (date and time) and wait for yes.
Hands on: the historyId restored and the page's new version.
Check: the canvas and the site show the restored content; on a published-only site, publish and check again.
7. Build Studio: delete a page
In Build Studio: the page switcher (the page name on the toolbar) › the bin icon, shown only beside the page you have open › Delete page. Through the API: call_appengine DELETE /repository/delete/page/<page id> with confirmed: true (or repo_delete on page, confirmed: true), only after the person says yes.
What happens (appengine repository.crud.service.ts 1785–1850): the page's live copy and all its History are deleted, a copy goes to Trash, and the page is gone (its URL is a 404; tested).
Before deleting, check what points at it:
| If the page is | Then |
|---|---|
The site's home page (data.homePage) | / becomes a 404. Point Home page at another page first. |
Another page's data.parent | That page loses its wrapper |
| A feature's page in Site Features | The feature still answers at that address, framed by account-layout instead |
root or account-layout | Every page or every feature page loses its header, footer or frame |
Bring it back: Database › Trash (/app/trash) › Restore, or call_appengine POST /repository/trash-restore with ["<page id>"]. The page comes back with the same id and content, but without its History and without its live copy, and with the status it had, so a page deleted while Published comes back saying Published with nothing live. Publish it again (step 3). Build Studio's delete dialog says "This cannot be undone"; it can, from Trash, except the History.
Stop: deleting is asked for by name. Say what points at the page and wait for yes.
Hands on: the deleted page's id (to restore from Trash if needed). Check: the URL is a 404; the page is in Trash.
Switching Published pages only on or off
Only on a clear yes, after reading the warning at the top: call_appengine POST /repository/update-partial/site/<site id> with { "data.publishedPagesOnly": true }. Use the dot-path key: a data object there replaces the site's whole data. Before switching it on, publish the home page and every page that should stay visible; each one not published becomes a 404 at once. Check / and two pages on the site straight after.
When it's done
Tell the person: what was done to which page, its badge now, what visitors see at its URL now (and why, from the site's setting), any review request and who it waits on, and for a restore or delete, how to undo it.
What it can't do yet
- Header, footer and parent pages on a published-only site (warning at the top).
- Unpublish on a site that serves drafts doesn't take the page down.
- A draft can't be previewed on the site of a published-only site; preview links show the live copy.
- Preview links are public, and there is no QR code preview.
- Restore doesn't update the badge and doesn't publish; a page restored from Trash keeps its old status with no live copy.
- No scheduled publishing for pages (Page settings has no Schedule tab; posts in Content Studio can be scheduled).
- The publishing review is enforced only by Build Studio's buttons; the API publish route doesn't check it.
- History keeps 10 versions and is deleted with the page.
Don'ts
- Don't tell the person Unpublish took a page off a site that serves drafts.
- Don't publish through the API on an org with publishing review without asking
approval/askfirst. - Don't switch on Published pages only without publishing the home page and checking the header.
- Don't restore the live-copy row; restore a version, then publish.
- Don't delete the home page,
root,account-layoutor a parent page without moving what depends on it. - Don't send a site record's
dataas an object toupdate-partial; use dot-paths. - Don't share a preview link for a page that must stay private.