Publishing a Documentation Set

A documentation set is not one thing you publish. It is three: the page type that carries the set’s configuration, the menu that decides every page’s URL and every sidebar row, and the pages themselves. Each publishes through a different control, and each is invisible on your site until it does. This page is the order they go in, what each one actually commits, and the checks that catch the failures that look like nothing happened.

Three artifacts, three publishes, one order

Publish the page type first, the menu second, the pages last.

The order is not a convention. The page type’s configuration file is what tells the site builder that this folder is a documentation set at all — without a published layoutName the layout has nothing to resolve and every page in the set renders a single line of text reading documentationConfiguration is missing!. The menu is what turns folder ancestry into URLs, so a page published before its menu is committed to a path the menu has not agreed to yet. Publish the container, then the shape, then the contents.

flowchart TD
  A["1 · Page type<br/>Pending changes → Page type: Documentation<br/>commits the set's configuration file"]
  B["2 · Menu<br/>Pending changes → Menu: Documentation<br/>commits the nav, and every URL it implies"]
  C["3 · Pages<br/>each page's own publish, or Schedule Set Publish<br/>commits each page's markdown at its computed path"]
  A --> B --> C
  A -. skipped .-> A1["Every page in the set renders one line:<br/>documentationConfiguration is missing!"]
  B -. skipped .-> B1["No sidebar, no breadcrumbs,<br/>no previous / next"]
  C -. skipped .-> C1["The page is absent from the sidebar,<br/>and every link to it renders as plain text"]

Once the set is live, the order stops mattering for routine edits: a typo fix is one page publish and nothing else. It matters again the moment you move a page between folders, rename a folder, or change the set’s theme — because those are menu and page-type changes, not page changes.

Finding them in Pending Changes

Open Deploy from the rail. Alongside the Preview site card sits Pending changes: everything you have edited in the CMS that has not reached your site yet. Tick the rows you want and the button reads Publish 3 to live site — it names the count so you cannot publish more than you meant to. With nothing ticked it reads Select changes to publish.

Two things about this list surprise people:

• Only what changed is listed. A menu you did not touch has no row. If you expected a Menu: row and there is none, the menu is already published — look for your problem somewhere else.
• Pages are not in it. Pages publish from the page itself, or from the set-wide schedule control below. The Pending changes card is for the configuration around your content: page types, menus, labels, forms, team members and workspace settings.

The rows a documentation set produces are Page type: <name>, Menu: <name> and — when you have changed anything under Settings → General — Settings (General). A search index you create for the set is bound to it through the page type’s configuration, so publishing the page type carries the binding; Search for Your Documentation covers the rest of that setup.

The selection mechanics, what one deployment actually does, and who is allowed to press the button are all owned by Publishing Changes. This page is deliberately only about the order and the verification.

Publishing pages

A documentation page publishes the same way every other page does — from the page, with a date, through the schedule. Publishing and Scheduling a Page is the full set of rules. Two things are specific to documentation.

An empty summary blocks the publish

The documentation page type requires a Summary, and nothing else. It is the only required field on a documentation page out of the box, and it is required because it is what the sidebar tooltips, the search results and the page’s own metadata are built from.

Try to publish without one and the CMS opens a Missing Required Fields dialog: “Before publishing, please provide the following in the page settings panel: Summary.” Through the API or an MCP tool the same check is a 400:

{ "error": "Missing required fields", "missingFields": ["summary"] }

Fix it in the page’s settings panel — the Summary field, which also has a generate button if you would rather start from a draft. The check is per page type, so if you have turned on Feature Image or Keywords for your documentation type, those appear in the same list.

Publishing a whole set at once

Writing a set means finishing twenty pages before any of them should go live. Publishing them one at a time is twenty publishes and twenty deployments.

Open Design → Documentation, expand your set, and use the schedule control in the set’s own toolbar — the row that also holds Add Folder, Add Page and expand-all. It opens Schedule Set Publish.

The dialog lists every page in the set that is currently in revision, picks a shared publish time, and runs a dry run before you commit to anything: each page gets a green Will schedule badge, or a red badge carrying the reason it will not go. The reasons are specific rather than generic — Missing required fields: summary, Page is PUBLISHED and cannot be scheduled — revise it first, Missing page:publish permission. Nothing is mutated until you press Schedule, and a page that fails never blocks the rest of the batch.

If the set’s own settings are also unpublished, the dialog says so — “This set also has unpublished settings — they publish in the same commit as these pages, so the set’s navigation and layout go live with its content.” There is no second action to hunt for.

What each publish commits

Every publish is a commit to your site repository followed by a build. What lands in the repository differs by artifact:

A page that has been published before and whose menu position has changed commits as a move: the file is renamed to its new path and the old URL is left behind as a redirect. That is why a folder rename is a page publish and not only a menu publish — Folders Set Your URLs walks through the staged-move mechanism.

What a committed page file looks like, and why you never write its front matter

Every page commits as a block of JSON between --- fences, followed by the page body in Leed Markdown. Leed generates that block from the page record — title, pageTypeId, pageId, publishedAt, modifiedAt, summary and the rest — on every publish.

Two consequences are worth carrying:

• publishedAt is stamped by the publish and modifiedAt by your last edit. That is exactly why an empty summary blocks the publish rather than shipping an empty key: the file is generated, so there is no moment at which a human could fill the gap in.
• There is no front-matter key that sets a page’s URL. The menu does that, and hand-editing a committed page file is pointless because the next publish of that page rewrites it whole.

The complete field list, including the keys a documentation page never uses, is at Front Matter Reference.

Verifying

Run these in order after the build finishes. Each failure has one likely cause, and they are easy to confuse with each other.

The single most useful of these is the third one. A sidebar row showing a slug is the only failure on this list that is completely invisible inside the CMS, because the menu tree displays an item’s title when it has one and its name only when it does not — and the published nav does the opposite. Left Navigation Menu covers the rename and the render rules together.

When nothing appears at all

Everything above assumes the deployment succeeded. If the content is right and the site is simply stale, the problem is the build rather than the publish: When a Deployment Fails separates a retryable infrastructure failure from a content error you have to fix and republish, and shows where the build log is.

One distinction that catches developers: the publishes on this page commit to your repository’s main branch and go straight to your live site. Repository-side work — template edits, a leed site push — commits to the preview branch and needs promoting before anyone sees it. Preview Site vs Live Site is the map of which is which.