# 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](/content/docs/organize/dimensions/index.html), [views](/content/docs/organize/views/index.html), [groups](/content/docs/organize/groups/index.html), [pages](/content/docs/organize/pages/index.html), and API-specific structure.

If you work primarily from the code editor, also review [Code Editor](/content/docs/write-and-publish/code-editor/index.html) 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](/content/docs/organize/dimensions/index.html) 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](/content/docs/organize/pages/index.html) for how paths work and how to move or rename pages safely.
- **Groups**: sidebar sections that collect related pages (and nested groups).

See [Groups](/content/docs/organize/groups/index.html) for grouping strategies and rules.
- **API-backed sections**: OpenAPI- or schema-driven API references and playgrounds.

See [Organize API Reference](/content/docs/api-documentation-and-playground/organize-api-reference/index.html) and [OpenAPI / JSON Schema Import](/content/docs/api-documentation-and-playground/openapi-import/index.html).

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](/content/docs/components/collection-list/index.html) 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.