Organize documentation structure

Understand the optional Dimensions → Views → Content model and how to plan a maintainable documentation structure in Documentation.AI.

Why organization matters

Good content is not enough if people cannot find it.

In Documentation.AI, navigation is a first-class concern for both human readers and AI agents. A clear organizing model helps you:

• Avoid duplicated sections and hard-to-maintain sidebars
• Plan for product growth, versions, and languages
• Keep navigation consistent across Web Editor and code-based workflows
• Give AI features a predictable map of your docs

This page introduces the core organizing model and points you to the detailed guides for dimensions, views, groups, pages, and API-specific structure.

If you work primarily from the code editor, also review Code Editor to see how the same concepts map to documentation.json.

The core model: Dimensions → Views → Content

Documentation.AI uses a three-layer navigation architecture:

Dimensions

Optional context

Views

Layout & navigation

Content

Pages, groups, API

At a high level:

1. Dimensions (optional) define where the reader is (for example, product, version, language).
2. Views define how navigation is arranged in that context (tabs and dropdowns).
3. Content defines what the reader can read (pages, groups, API references).

You can:

• Use Views + Content only, with no Dimensions, for simple sites.
• Add one or more Dimensions when you need parallel variants of the docs that readers can switch between globally.

Dimensions: define context (optional outer layer)

Dimensions are top-level context selectors that split docs into parallel variants and define where a reader is.

Use dimensions when you need parallel sets of docs that share structure but differ in content. For example:

• Product A vs. Product B
• Stable vs. Beta versions
• English vs. Spanish

Key rules:

• Dimensions are always the outermost layer in your structure.
• A project can have zero, one, or multiple dimensions, but most sites work best with one or two.
• Dimensions can map directly to content, or to views that then organize content:

Dimensions → Views → Content or Dimensions → Content.

See Dimensions for examples and design patterns.

Views: define navigation and layout

Views control how content is organized and navigated within a dimension context, or at the root when you do not use dimensions.

Views answer:

• Which high-level areas are visible at once?
• Do I switch between areas via tabs or a dropdown?
• How does the sidebar change when I change the view?

Supported view types:

• Tabs: horizontal tabs for mutually exclusive areas (for example, Guides vs. API).
• Dropdowns: a select-style control for modes or profiles (for example, Cloud vs. Self-hosted).

Content: groups, pages, and API reference

The content layer is what readers actually consume:

• Pages: MDX-backed units with unique path values (slugs).

See Pages for how paths work and how to move or rename pages safely.

• Groups: sidebar sections that collect related pages (and nested groups).

See Groups for grouping strategies and rules.

• API-backed sections: OpenAPI- or schema-driven API references and playgrounds.

See Organize API Reference and OpenAPI / JSON Schema Import.

You shape content structure using parent/child relationships (groups that contain pages, nested groups, or API sections) while views determine when and where that structure appears.

Content pages on containers

Any container node, groups, tabs, dropdowns, products, versions, or languages, can optionally have its own content page. This turns a purely structural node into a navigable page with its own URL.

Use content pages to create landing pages, section overviews, or hub pages that use Collection components to display child pages automatically. When a container has a content page, its label becomes a clickable link in breadcrumbs and navigation.

Key structure rules to remember

Dimensions and views

• Dimensions are optional but always outermost

If you use dimensions, the order is always: Dimensions → Views (optional) → Content.

• Views never contain dimensions

You cannot add dimensions inside a tab or dropdown; a view always lives inside a dimension context or at the root.

The one-child rule for containers (views)

Views obey a strict one-child rule:

• Tabs can contain exactly one child type:

• Pages or

  • Groups or
  • Dropdowns

• Dropdowns can contain exactly one child type:

• Pages or

  • Groups or
  • Tabs or
  • Dropdowns

You cannot mix different child types at the same level inside a single tabs or dropdowns container.

Groups and pages

• Groups are sidebar sections

• Once you introduce groups at a level, treat that level as “grouped”.

  • Groups can contain pages, nested groups, and API/OpenAPI-backed sections.

• Avoid mixing grouped and ungrouped content at the same level

• Choose either:

  • A flat list of pages, or
  • Only groups (each group then contains pages or nested groups).

• Pages are the fundamental content units

• The stable identifier is the page path (slug), which becomes part of the URL.

  • Reference path values without the .mdx extension.
  • Prefer moving pages between groups over renaming their paths; if you change a slug, add a redirect.

A practical planning workflow

When you plan or refactor a docs set, work from the outside in.

Decide if you need dimensions

Decide which axes of variation are real, not just labels.

• Start with product, version, and language.
• Only add a dimension if it meaningfully changes content across many pages.
• Most sites are either:
  • No dimensions (single product, single language), or
  • One dimension for versions or deployment models.

Design views for navigation

Within each dimension context (or at the root), decide how people move around.

• Use tabs for big, mutually exclusive areas (for example, "Guides" vs. "API").
• Use dropdowns where the choice feels like a mode or profile (for example, "Cloud" vs. "Self-hosted").
• Apply the one-child rule: each tabs or dropdowns container uses a single child type.

Shape groups, pages, and API sections

Once views are defined, structure the actual docs.

• Create groups for logical sections (for example, "Getting Started", "Advanced Topics").
• At each sidebar level, choose either all pages or all groups (plus their children), not a mix.
• Add API/OpenAPI-backed sections alongside pages in groups when needed.

Validate with real journeys

Before publishing, test with real workflows.

• Trace key user journeys: onboarding, first integration, troubleshooting, API evaluation.
• Ensure each journey has a straightforward path with minimal context switches.
• If journeys require frequent dimension or view changes, simplify your structure.

This outside-in approach keeps your organizing decisions deliberate and prevents ad hoc sidebars over time.

Example structures for common docs types

1. Simple product docs with tabs (no dimensions)

Use this when you have a single product and language, and you want a clear split between narrative guides and API reference.

Structure (conceptual):

Root (no dimensions)
└─ Views: Tabs
   ├─ Tab: Guides
   │  └─ Groups
   │     ├─ Getting Started
   │     │  ├─ Introduction
   │     │  └─ Quickstart
   │     └─ How-to Guides
   └─ Tab: API
      └─ Groups
         ├─ Authentication
         └─ API Reference (OpenAPI-backed)

2. Versioned docs using a version dimension

Use this when you maintain multiple live versions (for example, v1, v2, Beta) that differ meaningfully in content.

Structure (conceptual):

Dimension: Version
├─ Value: v1
│  └─ Views (optional) or Content
│     └─ Groups
│        ├─ Getting Started
│        └─ API Reference (v1)
└─ Value: v2
   └─ Views (optional) or Content
      └─ Groups
         ├─ Getting Started
         └─ API Reference (v2)

3. API-heavy docs with dropdowns and grouped reference

Use this when your primary surface is the API, possibly with multiple products, deployment models, or platforms.

Structure (conceptual):

Root (or inside a Dimension)
└─ Views: Dropdown (for mode)
   ├─ Option: Cloud
   │  └─ Tabs
   │     ├─ Guides
   │     │  └─ Groups
   │     │     ├─ Getting Started
   │     │     └─ Integration Guides
   │     └─ API
   │        └─ Groups
   │           ├─ Authentication
   │           └─ OpenAPI-backed Reference
   └─ Option: Self-hosted
      └─ Tabs (mirrors Cloud, with self-hosted specifics)

Best practices

What usually works well

• Start with context, not sidebars

Decide whether you need dimensions (product, version, language) before tuning view and group structure.

• Favor stable top-level choices

Once you add a tab, dropdown, or dimension value, keep it stable so links and AI references stay valid.

• Keep hierarchies shallow

Aim for 2–3 levels deep: dimension (optional) → view → group → pages or API sections.

• Reuse patterns across dimensions

Mirror the same group and page structure across versions or languages whenever possible.

• Name for search and scanability

Use concise, descriptive titles that work in search results and sidebars.