Organize with sections and collections

A Clayo project has a small, predictable hierarchy. Understanding it makes it much easier to tell your agent exactly where things should go.

The hierarchy

• Sections are the top-level grouping, shown as tabs in your docs site header. Typical sections: Guides, Reference, API.
• Collections group articles inside a section. They appear in the left sidebar.
• Subcollections are collections nested inside a collection, one level deep at most.
• Articles live in exactly one collection.

So a visitor's mental model is: pick a tab, scan the sidebar, open an article.

Sections

Each section has a URL slug. Visiting /sections/guides on your docs site redirects to the first article in that section, so section links always land somewhere useful.

Renaming a section keeps its slug, which means links shared before the rename keep working. If you want the slug to change too, ask your agent explicitly.

Collections

Collections exist to keep the sidebar scannable; they have no public page of their own. On the docs site they render as expandable groups, and the group containing the current article opens automatically.

One level of nesting is allowed: a collection can hold subcollections, but a collection that has subcollections cannot itself be nested deeper. If you find yourself wanting a third level, that is usually a sign the section should be split instead.

Ordering

Everything is ordered: sections across the tab strip, collections within the sidebar, articles within a collection. Nothing is alphabetical unless you make it so. Reordering is a one-line request:

Put "Getting started" first in the sidebar.
Move "Webhooks" into the API reference collection.
Reorder the tabs so Guides comes before Reference.

Moving articles

An article moves between collections without changing its URL, since article URLs are flat (/articles/your-slug). Reorganizing your docs never breaks links. See Links, slugs, and redirects.

Planning your structure

A few patterns that hold up well:

• Start with two sections: Guides and Reference. Task-oriented walkthroughs in one, exhaustive lookup material in the other. Most products do not need a third until much later.
• Name collections after what people are trying to do, not after your internal team structure. "Getting started", "Billing", "Integrations" beat "Platform" and "Misc".
• Three to eight articles per collection reads well in the sidebar. One lonely article suggests merging; fifteen suggests splitting or a subcollection.
• Let structure emerge from content. It is easy to reorganize later, and nothing breaks when you do, so do not spend your first day designing a taxonomy.

Your agent can restructure wholesale when the time comes:

Split the "Guides" section into "Guides" and "Administration",
move the team and billing collections to Administration,
and keep everything else where it is.

For the underlying tools (create, rename, move, reorder, delete), see Structure tools.