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: the same, under /blog/.
  • 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 can have /galleries/, a consultancy can have /services/, and a project can have /concepts/ and /reference/. Each is just a section name on standalone pages.

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.

What a section gives you

  • A landing page. Each section gets a generated page listing everything in it. For example, /recipes/ lists all the recipe pages. The heading comes from the section name (“recipes” becomes “Recipes”).
  • Navigation. Sections appear in your site’s navigation automatically, alongside Blog and Docs, without any 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 simply title-cased, which is wrong for names like API. There are two ways to set a display name with the casing you want:

  • When creating a section in the page editor, just 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.
  • In the Pages list, every section folder has an edit icon that opens a small dialog to rename the section or give 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: type a tag as iOS in the page editor and it is stored as ios but displays as iOS everywhere — on post tag chips, tag lists, and the tag’s landing page.

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 other internal names. If a name is rejected, pick another. Sections inside /docs/ and /blog/ have no such restriction, since they are already namespaced.
  • An api section is allowed, with one exception inside it: the slug v1, since /api/v1/ is used by the platform on every site.
  • A standalone page’s slug cannot match an existing section name (and vice versa), since both would claim the same URL.
  • The same slug can repeat across different sections: /docs/guides/overview and /docs/tutorials/overview are separate pages.