Sections

A section groups pages under a shared path. Sections work with three content types:

• Docs: a section groups pages under /docs/, so a page appears at /docs/guides/getting-started.
• Blog: sections behave the same way, producing a URL like /blog/essays/on-writing.
• Standalone: the section becomes a top-level path of its own. A standalone page with section recipes and slug pasta is published at /recipes/pasta.

Standalone sections are how you shape your site’s structure beyond the built-in /blog/ and /docs/ paths. A photographer might add /galleries/, a consultancy could gather its offerings under /services/, and a software project can split its documentation into /concepts/ and /reference/. Each one is a section name on a standalone page.

Sub-sections

A standalone section can nest one level. Write the section as two names separated by a slash, and the page publishes one level deeper:

This is the same depth docs and blog reach. They spend their nesting on the /docs/ and /blog/ prefix instead. That is also why docs and blog sections cannot themselves nest: /docs/guides/advanced/setup is one level too deep.

Sub-sections are useful when a section has enough pages to need grouping. An API reference can put each resource in its own sub-section, such as /api/builds/, /api/pages/, and /api/media/, with one page per endpoint underneath. In the navigation the sub-section appears as a collapsible group inside its parent, not as a separate top-level entry.

On the homepage and on section landing pages, a sub-section is listed as a single row linking to it, rather than having its pages listed under the parent’s heading. So a homepage listing for the example above shows the pages that sit directly under /api/, plus a row each for Builds, Pages, and Media. This applies to Docs and Blog sub-sections too.

Both levels get a landing page and can carry their own display name, so /api/ can display as “API” while /api/builds/ displays as “Builds”.

API reference pages

If you publish API documentation, you can mark a page as an endpoint reference by giving it an API endpoint: an HTTP method optionally followed by a path, like GET /sites/{siteId}/pages. The page’s title then carries a colored method badge in the site navigation, so a reference section scans like an API index. With badges carrying the method, titles can be verbs instead of routes: “List pages” rather than “GET /sites/{siteId}/pages”.

In the dashboard, tick API reference page in the page editor’s Metadata section, then enter the endpoint in the field that appears. Unticking the box clears the endpoint. Through the API it is the apiEndpoint field on the page object, and in Markdown published through the GitHub Action or the Obsidian plugin it is api_endpoint in front matter. Pasting such a file into the editor fills the field the same way. The value must start with GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS in any casing, and the method is uppercased on save. The path is free-form text, and can be omitted for a method-only badge. Clearing the field turns a reference page back into a normal one.

A typical reference uses a standalone sub-section per resource with one page per endpoint (/api/pages/, /api/builds/), while concept pages like an overview or authentication guide have no API endpoint and sit alongside.

Setting a section

In the dashboard, the section is a field in the page editor. Through the API or the integrations, set section in front matter or in the request. The GitHub Action also infers sections from directory names.

Section names use lowercase letters, numbers, and hyphens. To nest, join two names with a slash: api/builds.

What a section gives you

• Every section gets a generated landing page listing everything in it. For example, /recipes/ lists all the recipe pages. The heading comes from the section name, so “recipes” becomes “Recipes”.
• Sections appear in your site’s navigation automatically, alongside Blog and Docs, with no configuration. You can reorder or hide navigation entries from the theme settings.

Display names and descriptions

Section names are lowercase in URLs, and by default the displayed name is title-cased, which is wrong for names like API. There are three ways to set a display name with the casing you want:

• When creating a section in the page editor, type it the way it should display. Typing tEst publishes the section at /test and displays it as tEst. Typing an existing section’s name in any casing selects it.
• The same works through the API and the integrations: a section of API/Builds, whether in a request, in front matter, or as directory names with the GitHub Action, publishes at /api/builds/ and sets the display name to API. Casing captured this way only fills in a name where none is set, so syncing content never overwrites a name chosen in the dashboard.
• In the Pages list, every section folder has an icon that opens the section’s actions, where Edit section renames it or gives it a description. The description appears on the section’s landing page. The same dialog opens from the page editor’s section dropdown, where each section has an edit button next to it.

Display names appear in the navigation and on the section’s landing page, and work for Docs and Blog too, if you want to call your blog something else. Edit their folders in the Pages list the same way. Setting display names requires the workspace owner role; members can still create sections, which use the default name until an owner renames them.

Tags work the same way in the page editor, through the API, and through the integrations. Write a tag as iOS and it is stored as ios but displays as iOS wherever it appears, including post tag chips, tag lists, and the tag’s landing page.

Deleting a section

A section exists because pages are filed in it. Emptying a section is most of what removing it takes, and what stays behind is its display name, its description, and its place in the navigation. A section whose last page you deleted still appears in the Pages list with a count of zero, so you can see it is there rather than wonder why the navigation still shows it.

To remove it, open the section’s actions from its folder in the Pages list, the same icon you use to rename it, and choose Delete section. Sub-sections are deleted along with the section they sit in.

Delete is available only while the section holds no pages, sub-sections included. A section names the path its pages publish under, so deleting one that still holds pages would leave every one of them published where it is while stripping the name they publish under. Move those pages to another section or delete them, and the action becomes available. Deleting a section requires the workspace owner role, like renaming one.

The same removal is a DELETE over the API, with the same rule: a section that still holds pages is refused, and sub-sections go with the section they sit in.

Rules

• A few names are reserved for standalone sections because the site itself uses those paths: docs, blog, tags, authors, media, index, and a handful of others. If a name is rejected, pick another. Sections inside /docs/ and /blog/ have no such restriction, since they are already namespaced. Neither do sub-sections: /api/media/ is fine, because only the first name claims a top-level path.
• An api section is allowed, with one exception inside it: /api/v1/ is used by the platform on every site, so neither the slug v1 in section api nor the sub-section api/v1 is accepted.
• A standalone page’s slug cannot match an existing section name (and vice versa), since both would claim the same URL. The same applies one level down: if /api/builds/ is a sub-section, there cannot also be a page at /api/builds.
• Standalone sections nest at most one level. api/builds works; api/builds/deploy does not.
• The same slug can repeat across different sections: /docs/guides/overview and /docs/tutorials/overview are separate pages.