Pages - Documentation.AI

Pages

Understand how pages work as the building blocks of your docs, how to add them in the Web Editor, and how to keep their slugs and paths stable over time.

Overview

Pages are the fundamental building blocks of your documentation. Each page is:

In the Organize area, you combine pages with groups, views, and dimensions to build a structured docs site. This guide focuses on working with pages in the Web Editor first, then covers how they are referenced in configuration and how to keep their identifiers stable.

Adding a new page in the Web Editor

You add pages from the Web Editor sidebar. What you can do depends on the Dimension and View you have selected, and whether your docs under that selection use Groups.

Select the right Dimension and View

The sidebar supports two structures. What you see depends on whether Groups exist under the selected Dimension + View.

Add a page from the sidebar, if Groups exist

Example: If “Getting Started” is a group, click the + next to “Getting Started” to add a new page inside that group.

When Groups are present, you can add a page only inside a group (not at the root).

Add a page from the sidebar, if no Groups exist

In this structure, pages are created at the root under the selected Dimension + View.

Fill in page details

Confirm the page location

When you create a page in the Web Editor, it updates navigation configuration for you, so you do not need to edit JSON or YAML directly.

Page types you can add from the Pages menu

The Pages heading has a + menu with several content item types. Each one controls how content appears and is organized in your sidebar.

Quick comparison

Page

A Page is a standard documentation entry backed by an MDX file.

Use normal pages for most narrative docs, guides, references, and conceptual content.

Group

A Group is a labeled sidebar section that contains pages.

Use groups when you want to introduce a top-level or mid-level section in the sidebar, such as “Getting Started” or “Organize”.

Page group

A Page Group is a nested container of pages, similar to a folder.

Use page groups when you need a more granular structure inside a larger group, such as organizing several related guides under a product or feature.

OpenAPI reference

An OpenAPI Reference creates generated API documentation from an OpenAPI spec.

Use OpenAPI references when you want your API endpoints and schemas to be maintained from a single OpenAPI document, while still fitting into the same navigation as the rest of your docs. For more details, see OpenAPI / JSON Schema Import and Organize API Reference.

Unpublished page

An Unpublished Page is a page that exists but is not currently visible in navigation.

Use unpublished pages to:

How pages are referenced

Whether you configure navigation in the Web Editor or via code, each page entry uses a small set of core properties.

Core page properties

From the site configuration, pages support:

In the Web Editor, the same concepts appear as:

You do not need to think about JSON or YAML when using the Web Editor; it writes the configuration for you.

All content pages must be authored in MDX. When you reference them in configuration, always use the path without the .mdx extension.

Paths, slugs, and URLs

For internal content:

For external content:

Content pages on containers

In addition to standalone pages, you can attach a content page to any container node in your navigation: groups, page groups, tabs, dropdowns, products, versions, and languages.

A content page on a container gives it its own MDX-backed page with a unique path. This means the container is no longer just structural; it becomes a navigable page that readers can visit directly.

What this enables

How it works

Add a path property to any container entry in your navigation configuration. Here is a tab with its own content page:

{
  "tab": "API Reference",
  "icon": "code",
  "path": "api/overview",
  "groups": [
    {
      "group": "REST API",
      "pages": [
        { "title": "Authentication", "path": "api/authentication" }
      ]
    }
  ]
}

The same pattern works for groups, dropdowns, products, versions, and languages: add a path and the container becomes a navigable page. The path follows the same rules as any page path. In the Web Editor, use the Attach Content Page option in the container's menu.

Content pages on containers support the full set of page display options (badge, show-sidebar, show-toc, content-width, method, tags, and more). See Page Configuration for details.

For container-specific guidance, see Content pages on groups and Content pages on views.

How pages relate to groups, views, and dimensions

Pages are content; groups, views, and dimensions are ways of organizing or slicing that content.

From a maintenance perspective:

Best practices for naming, slugs, and restructuring

A clear, stable page model makes your docs easier to maintain and safer to evolve.

Naming and titles

Slugs and paths as stable identifiers

Treat path as the page’s stable identifier:

When you must change a slug:

  1. Update the path in configuration or via the Web Editor.
  2. Add redirects in Redirects & Rewrites so existing links continue to work.
  3. Communicate the change if external integrations or apps rely on the old URL.

Plan slugs as if they will live for a long time. It is easier to adjust titles and group structure than to rename paths once other systems and users depend on them.

Safe restructuring

When reorganizing navigation:

By treating pages as stable content units, and using groups, views, and dimensions as flexible layers on top, you can evolve your docs structure confidently without breaking URLs or confusing readers.