Creating a Documentation Set

Creating a documentation set takes about a minute of clicking and about five minutes of thought. The clicking is one dialog with three fields. The thought is everything after it: five settings the set will not render without and where each one comes from, and an order of operations where doing step four before step three quietly gives every page in the set the wrong URL.

This page is that order, start to finish. Everything here is available on every plan, including Free — the built-in layouts, themes, code themes and fonts used in this flow are ungated, and only typing a custom theme, code theme or font name is a Starter feature, which Themes, Fonts and Code Themes covers.

1. Create the page type

Go to Settings → Page Types and use the create control in the header. The Create Page Type dialog asks for three things:

• Name — the display name across the CMS, and the name Leed will give the set’s menu. Documentation in the example below.
• Path — the URL root of the whole set. It auto-fills from the name, slugified, and stops auto-filling the moment you type in it yourself. Everything you type here is slugified as you type.
• Type of Page — Documentation, API Documentation or Posts. Pick Documentation for hand-written docs, API Documentation for a set generated from an OpenAPI specification.

The path may nest. docs/api/1.2.0 is a legal page type path and is how versioned API sets are kept apart — each version is its own page type at its own nested root. It may not collide with another page type’s root.

2. What Leed does for you automatically

For a Documentation or API Documentation type, four things happen without you asking:

• A left menu is created and bound. It is named after the page type, created before the page type record itself, and written straight into documentationConfiguration.menus.left. It appears empty in the Design workspace’s Documentation section immediately. Through the API or an AI client you can instead bind a menu that already exists, by passing its id in documentationConfiguration.menus.left when you create the page type; it may not be another set’s menu or one of the menus bound in the company’s own documentation configuration — its top, left or bottom menu.
• A search index is created and bound, named after the set and covering only its pages, so the set is searchable from its first publish.
• The layout is fixed to the system file leed-documentation.hbs, and Leed deliberately does not scaffold a layout file for it in your repository. That is not an omission — the documentation layout is resolved inside the site builder, and a file of that name in your repository would do nothing.
• The page type is marked dirty, so it shows a must-publish indicator on the Page Types list right away rather than only once you expand it.

3. The five settings the set will not render without

Expand the set’s row on Settings → Page Types. The panel has two cards: General Details (Name, Slug, Enable Autolinking, the two locks and the required-field controls) and Documentation Configuration Overrides, which is where the set’s reader-facing configuration lives.

Five of those fields are load-bearing. Four of them inherit from the company’s documentation configuration on Settings → General when the page type leaves them unset, so a set renders as long as either level provides a value; a new workspace starts with all four set at company level. The fifth, the left menu, belongs to the set alone and is bound for you when the set is created.

The other fields on the same card — Search Index, Starting Page, Logo (Light), Logo (Dark), Header Button Text, Header Button Link, Top Menu and Bottom Menu — are optional and are covered further down.

What a missing configuration looks like

The failure is unmistakable once you have seen it, and completely opaque before. A published documentation page whose merged configuration has no layoutName renders exactly this and nothing else:

<h1>documentationConfiguration is missing!</h1>

No sidebar, no styling, no content. The cause is always the same — layoutName is absent from both the page type’s published configuration and the company’s. Set Layout on the page type and publish the page type, or set it on Settings → General and publish the company settings to fix every set that inherits it.

How the company default is inherited

Settings → General carries a company-wide documentation configuration, and every documentation set inherits it. On the page type panel, a pick list offers Company default (…) as its first option, naming the value the set would inherit, and a text field shows the company value as its placeholder. Choosing the company default stores nothing on the page type.

Both copies are published. The company’s configuration is written into src/src.11tydata.json when the company settings publish, and the page type’s into src/{page type path}/{last path segment}.11tydata.json when the page type publishes. The site build merges them field by field, and wherever the page type sets a value, the page type wins.

Three practical consequences:

• A change on Settings → General reaches the site when the company settings are published, and then applies to every set that does not override that field.
• Tab Groups, the OpenAPI snippet languages and the syntax highlighter are company-wide only. A page type never stores them.
• Hand-writing a documentationConfiguration block into src/src.11tydata.json does not survive. The CMS writes that file from the company record and replaces it whole, so the next settings publish overwrites your block.

Set shared values once, on Settings → General, and set a value on the page type only where this set should differ from the rest of your documentation.

4. The rest of the configuration

The same card carries the fields the five-value list does not cover.

One more field belongs to the same documentationConfiguration object and has no control on this panel: Tab Groups, which is company-wide only and edited on Settings → General. What the header button and tab groups produce for a reader is covered in Documentation Header, Footer and Logos and Tab Groups for Consistent Examples.

Every other field on the panel — the two locks, aliases, the redirect index, required fields — behaves the same for a documentation set as for any other page type, and is documented at Configuring a Page Type.

5. Every formatting feature is already available

A page type carries a per-type allow-list of advanced markdown blocks — alerts, tables, tabs, collapsibles, diagrams, math, icons and iframes — but only a Posts page type enforces it. For a Documentation or API Documentation type the toggles are not shown on the panel and the flags are not checked: every block is available in the editor, and AI and MCP writes containing any of them are accepted.

So there is nothing to switch on before anyone authors a body. If an alert or a table is refused, check that the page belongs to the documentation page type rather than to a posts type. What the switch does on a posts type is shown in What Each Page Type Lets You Format.

6. Required fields

A documentation page type ships with one required field, and it blocks publishing rather than saving.

Attempting to publish a documentation page with an empty summary returns:

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

If you are building a large set, check the set’s own required fields before you author anything. A field that is required and unset blocks every page in the set at once, not one page at a time, and discovering it at launch means editing every page rather than one setting.

7. The order of operations that works

Each of these steps depends on the previous one, and the failure mode of getting them out of order is silent — the pages exist, they publish, and their URLs are wrong.

flowchart TD
  A["Create the page type"] --> B["Menu and search index auto-created and bound"]
  B --> C["Check Layout, Theme, Code Theme and Font"]
  C --> E["Save the empty folder skeleton"]
  E --> F["Reserve the pages"]
  F --> G["Author the bodies"]
  G --> H["Arrange the menu: nest pages into folders"]
  H --> I["Publish: page type, then menu, then pages"]
  F -. "pages created before the folders exist land at top level with a flat URL" .-> E

Two of those steps are the ones people skip.

Save the folder skeleton first. Folder names become URL segments, so the folders have to exist before pages are placed in them. A page created while the set has no folders is appended at the top level of the menu and gets a flat URL — /docs/my-page/ rather than /docs/getting-started/my-page/. Folders Set Your URLs is the page to read before you name a single folder.

Move pages in the menu, never by editing a path. There is no path field on a page, and a path sent to the page-create endpoint is ignored by design for a menu-bound documentation set — precisely so a page’s URL can never contradict its position in the navigation. The docs left menu is the only writer of folder placement, and moving an item in it physically moves the affected pages.

The menu Leed created for you is empty; Left Navigation Menu is where you give it shape. Nothing you have set on this page is live until all three artifacts are published in order, which is Publishing a Documentation Set.

Optional at creation time, useful immediately after

Starting Page. This is the set’s landing page. It is the breadcrumb home target, and once the page type sets it, a reader who requests the set root — /docs/ — is sent there with a temporary (302) redirect, unless a page already renders at the root or an alias claims that path. Only the page type’s own Starting Page drives the redirect; one inherited from the company default does not. Give the landing page a slug of its own and set it here once it exists.

The search index. The set already has one, created and bound when the page type was created. Search for Your Documentation covers what the prebuilt index gives you and what the AI-powered alternative adds.

If a documentation set is your first goal in Leed, Quick Start: Publish Your First Page gets one page live first, which makes the publish step here recognizable rather than novel.