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 that look already-configured and are not, a set of editor features that ship switched off, 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, three 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.
• 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. Without them the set does not render as documentation at all.

The other fields on the same card — Search Index, Starting Page, Logo (Light), Logo (Dark), 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 the configuration that was actually published — and the fix is to set Layout on the page type and publish the page type. Setting it at company level does not fix it; see the next section for why.

Why the page type, and not the company default

Settings → General carries a company-wide documentation configuration, and the page type panel shows those values grayed with a (company default) annotation. It is tempting to read that as inheritance. It is not — it is a preview.

The company copy is never published. The record the site builder reads is written from a fixed set of company fields that does not include documentationConfiguration at all, so the company value has no path to your site. Meanwhile the page type’s copy round-trips reliably: on every page type publish, Leed writes the whole object to src/{page type path}/{last path segment}.11tydata.json, and that file is what the build reads.

Two practical consequences:

• A field that shows (company default) and is not explicitly set on the page type publishes as absent. That is why an apparently-configured set can render the missing-configuration page.
• Hand-writing a documentationConfiguration block into the site-wide src/src.11tydata.json does not survive. Every writer of that file parses it and replaces it whole, so the next settings save, batch publish or billing change deletes your block.

The page type is the only durable home for a set’s configuration. Set the values there.

4. The rest of the configuration

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

Two more fields belong to the same documentationConfiguration object and have no control on this panel: the Header Button (its text and URL) and Tab Groups. The CMS edits both on Settings → General, where they are stored on the workspace — and, for the reason given just above, the workspace copy is shown to you rather than published. Writing either onto a specific set is an API operation against the page type today. What each one produces 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. Turn on the formatting features the set will use

A page type carries a per-type allow-list of advanced markdown blocks. For a new page type exactly one of them is on.

Turn on what the set will actually use before anyone authors a body. The rejection is not cosmetic: a disabled feature makes an AI or MCP write of that markdown fail outright, naming the offending feature, and a set built by an AI client against a default page type will fail on its first alert. The editor side of the same switch 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 auto-created and bound"]
  B --> C["Set Layout, Theme, Code Theme, Font, Left Menu"]
  C --> D["Enable the editor features the set will use"]
  D --> E["Save the empty folder skeleton"]
  E --> F["Reserve the pages"]
  F --> G["Author the bodies"]
  G --> H["One menu save: rename every leaf, nest 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 by saving 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 saving it physically moves the affected pages.

The menu Leed created for you is empty; Left Navigation Menu is where you give it shape, and it is also where the leaf-rename trap that catches every first set is explained. 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 breadcrumb home target, and it is the one page in a set that legitimately lives at the set root. Set it once the set’s landing page exists. Note that the set root is a single, unique URL — if something else on your site already occupies /docs/, the landing page needs its own slug and a redirect instead.

The search index. Creating a search index bound to the set is a separate flow, and the server writes the binding back onto the page type for you. 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.