Organization

The shape of resources/docs is the shape of your navigation. Directories become sidebar groups and files become pages within them. Labels, icons, and ordering are controlled right where the content lives, not in a central config file.

Directories are groups

Put pages in a directory and they appear together under a group heading in the sidebar:

resources/docs/
  index.md                     → /docs
  getting-started/
    installation.md            → /docs/getting-started/installation
    configuration.md           → /docs/getting-started/configuration
  billing/
    index.md                   → /docs/billing
    payment-methods.md         → /docs/billing/payment-methods

If that's all you do, the group's label is derived from the directory name.

_group.yml

Drop a _group.yml file in a directory to customize its group:

label: Getting Started
order: 1
icon: rocket

• label: the heading shown in the sidebar.

• order: an integer that sorts this group against its siblings. Lower comes first.

• icon: a bundled icon name shown beside the label.

• description: a one-line summary of the group, shown on generated section cards. When omitted, the directory's index page description is used instead.

• locked: when true, every repository page and partial in this directory (and below it) is locked against web admin edits. A page can't opt back out with locked: false, so reviewers only need to check one file to trust the whole section.

• section: when true on a top-level directory, promotes that group into its own documentation area.

Icons come from the bundled Heroicons outline set, with names like rocket, pencil-square, cog-6-tooth, book-open, sparkles, lock-closed, and shield-check. An unknown name renders no icon and docent:check warns you, so typos surface before you ship.

Top-level sections

For a larger help center, promote a top-level directory into a section:

label: API Guides
order: 2
icon: code-bracket
section: true

Docent adds the section to the top navigation and shows only that area's pages in the sidebar. URLs don't change. Root pages and ordinary top-level groups stay in the default Documentation section; rename it with navigation.default_section in your site's config entry.

Sections split one site's sidebar into areas that share a URL prefix, a theme, and a search index. When two audiences need genuinely separate documentation, with different routes, middleware, or branding, reach for multiple sites instead.

Sections follow the same visibility rules as pages. If a viewer can't open any page in a section, they won't see its switcher. Search still covers every area, while previous and next links stay inside the current section. In the compact help widget, sections appear as ordinary top-level groups instead of tabs.

Ordering

Two order keys work together: front matter order sorts pages within a group, and _group.yml order sorts groups against each other. Anything without an explicit order sorts after ordered items, then alphabetically. This site sets order: 1, 2, 3 on its three groups so they read Getting Started, Writing Docs, Web Admin.

Nesting

Directories nest, and so do groups. A directory inside a directory becomes a nested group in the sidebar, and each level can carry its own _group.yml. Nested groups collapse: a chevron expands them, and the group holding the current page opens on its own. Keep the tree shallow where you can; one or two levels reads best.

Give a nested directory an index.md and its group header becomes navigable: clicking the label opens that landing page — expanding the group with it — while the chevron beside it still toggles without leaving the page. The landing page doesn't repeat as a row inside its own group; the header is its link, and it reads first in the group for previous/next links and the agent-facing feeds. Without an index.md, the header is a plain toggle. There's nothing to configure — the directory's own files decide.

Top-level groups don't collapse; their heading always shows its pages, so an index.md there is pinned as the group's first page instead.

Moving a page

When a page moves or gets a better slug, leave a redirect stub at the old location so saved links, search engines, and older application releases keep working:

---
title: Old Quickstart
redirect: getting-started/quickstart
---

The stub answers its old URL with a permanent redirect, keeps the query string, and works in the reader, the help widget, and agent-facing Markdown alike. It never appears in navigation, search, llms.txt, or Assistant answers — the new page owns every surface.

Redirects respect access rules: a viewer who can't open the destination gets the same not-found response as for any unknown page, so a stub never reveals where gated content went. Targets must be Docent slugs; external URLs are rejected. php artisan docent:check reports broken targets, chains, cycles, and stubs that collide with a real page.

Now write some content with the authoring toolkit.