Documentation Structure

Build Your Documentation

Everything you need to write, organize, and publish documentation with Starlight and Astro.

Docs Page

Create standalone docs pages with MDX frontmatter.

Docs Post Collections

Organize docs into folders with auto-generated sidebars.

Why Structure Matters

A documentation site is only as good as its structure. When files are scattered randomly, visitors get lost. When they are organized well, readers find answers in seconds.

This page explains how to structure your src/content/docs/ folder so that:

Every section has a clear purpose
The sidebar renders fast and automatically
Readers always know where they are
Adding new content is predictable

The Base Rule

Every folder inside src/content/docs/ becomes a documentation section. Inside each folder, you place:

One index.mdx — the intro / landing page for that section
Multiple .md or .mdx files — the actual content pages

src/content/docs/
├── getstart/
│   ├── index.mdx          ← intro page for /getstart/
│   ├── download.md        ← /getstart/download/
│   ├── installation.md    ← /getstart/installation/
│   └── configuration.md   ← /getstart/configuration/
├── cms/
│   ├── index.mdx          ← intro page for /cms/
│   ├── decap.md           ← /cms/decap/
│   └── tina.md            ← /cms/tina/
└── hosting/
    ├── index.mdx          ← intro page for /deploy-hosting/
    ├── cloudflare.md      ← /deploy-hosting/cloudflare/
    └── netlify.md         ← /deploy-hosting/netlify/

The index.mdx is special: it becomes the folder’s root URL. Everything else is a child page.

The `index.mdx` File

index.mdx is the intro page for the folder. It has two jobs:

Welcome the reader
Point them to the right sub-page

A minimal index.mdx:

---
title: Get Started
description: Introduction to Astro Docus and how to use this section.
tableOfContents: false
next: false
---

## Welcome

This section walks you through installing, configuring, and running Astro Docus.

Use the cards below to jump to the page you need.

Optional — Add a card grid

If you want the intro page to display a visual grid of sub-pages, add the card grid from docs/data/index-page.md:

---
title: Get Started
description: Introduction to Astro Docus.
tableOfContents: false
next: false
---
import Data from '../../../data/index_page/getstart.json';
import '../../../styles/index_page.css';
import { Picture } from 'astro:assets';

## {frontmatter.description}

<div class="grid-container">
  { Data.resources.map(({ title, image, text, link }) => (
    <div class="grid-item">
      <a href={link}>
        <Picture src={image} alt={title} formats={['avif', 'webp']} width="80" height="80" class="img-fluid" decoding="async" />
      </a>
      <h3><a href={link}>{title}</a></h3>
      <p>{text}</p>
    </div>
  ))}
</div>

Both .md and .mdx work for index, but .mdx is recommended if you want to embed components or widgets.

Naming Content Files

The filename becomes the URL. Keep names short, lowercase, and hyphenated.

Filename	URL
`installation.md`	`/getstart/installation/`
`folder-structure.md`	`/getstart/folder-structure/`
`headless-cms.md`	`/getstart/headless-cms/`

Avoid

Spaces (folder structure.md)
Uppercase (Installation.md)
Special characters (setup&config.md)
Very long names (how-to-install-astro-docus-on-windows-11.md)

Auto-Ordering with Number Prefixes

When you use autogenerate in the sidebar, files are sorted alphabetically. That means configuration.md will appear before installation.md, which may not match your intended reading order.

To force a specific order, add a numeric prefix:

01-download.md
02-installation.md
03-configuration.md
04-folder-structure.md

The prefix sorts them correctly. The number is stripped from the URL:

File	URL
`01-download.md`	`/getstart/download/`
`02-installation.md`	`/getstart/installation/`

Tip: Use 01-, 02-, 03- for top-level reading order. Reserve 10-, 20-, 30- for chapters, so you can insert new pages in between without renumbering everything.

Example of a scalable scheme:

01-introduction.md
02-installation.md
10-configuration.md
11-configuration-advanced.md
20-deployment.md
21-deployment-cloudflare.md
21-deployment-netlify.md
30-troubleshooting.md

This leaves gaps for future additions.

Registering Sections in astro.config.mjs

Every folder you want in the sidebar must be registered in astro.config.mjs. There are two ways:

List each page by hand:

{
  label: 'Get Started',
  items: [
    { label: 'Introduction', link: '/getstart/' },
    { label: 'Download', link: '/getstart/download/' },
    { label: 'Installation', link: '/getstart/installation/' },
    { label: 'Configuration', link: '/getstart/configuration/' },
  ],
},

Pros: Full control over order and labels. Cons: Must update every time you add a file.

Let Astro read the folder:

{
  label: 'Page & Data',
  autogenerate: { directory: 'data' },
},
{
  label: 'Documentation Page',
  autogenerate: { directory: 'documentation' },
},

Pros: New files appear automatically. No config changes. Cons: Order is alphabetical unless you use number prefixes.

Combining both

You can mix them. Use autogenerate for large reference folders and manual entries for curated guides:

sidebar: [
  {
    label: 'Get Started',
    items: [
      { label: 'Introduction', link: '/getstart/' },
      { label: 'Installation', link: '/getstart/installation/' },
    ],
  },
  {
    label: 'Page & Data',
    autogenerate: { directory: 'data' },
  },
  {
    label: 'Documentation Page',
    autogenerate: { directory: 'documentation' },
  },
  {
    label: 'Headless CMS',
    autogenerate: { directory: 'cms' },
  },
  {
    label: 'Hosting',
    autogenerate: { directory: 'hosting' },
  },
]

A Recommended Folder Layout

For a medium-sized documentation site, this layout balances structure and simplicity:

src/content/docs/
├── index.mdx                 ← home / welcome
├── getstart/                 ← onboarding
│   ├── index.mdx
│   ├── 01-download.md
│   ├── 02-installation.md
│   ├── 03-configuration.md
│   └── 04-folder-structure.md
├── data/                     ← JSON data documentation
│   ├── index.mdx
│   ├── 01-home.md
│   ├── 02-plan-pricing.md
│   ├── 03-configuration.md
│   └── 04-index-page.md
├── documentation/            ← writing docs
│   ├── index.mdx
│   ├── 01-static-docs.md
│   ├── 02-static-pages.md
│   └── 03-components.md
├── cms/                      ← headless CMS guides
│   ├── index.mdx
│   ├── 01-decap.md
│   ├── 02-tina.md
│   └── 03-cloudcannon.md
└── hosting/                  ← deployment guides
    ├── index.mdx
    ├── 01-cloudflare.md
    ├── 02-netlify.md
    └── 03-vercel.md

Each folder:

Has an index.mdx as its intro
Uses numbered prefixes for reading order
Is registered in astro.config.mjs via autogenerate

Tips & Tricks

1. Keep sections focused

Each folder should cover one topic. If a folder has more than 10–15 files, split it into subfolders.

2. Use `index.mdx` for navigation

Don’t write full content in index.mdx. Treat it as a hub that points to sub-pages. Readers land there, then branch out.

3. Prefer `autogenerate` for reference, manual for tutorials

Tutorials need precise order — list them manually. Reference material can be alphabetical — autogenerate it.

4. Use number prefixes for tutorials

01-introduction.md
02-installation.md
03-configuration.md

This gives you both autogenerate convenience and tutorial-style ordering.

5. Group by reader intent, not by file type

Bad:

md-files/
astro-files/
json-files/

Good:

getstart/         ← I want to start
customization/    ← I want to change something
deployment/       ← I want to publish
troubleshooting/  ← something broke

6. Keep frontmatter consistent

Every file should have title and description. Consistency makes search, SEO, and previews reliable.

7. Link between pages

Use relative or absolute links generously:

See the [Installation guide](/getstart/installation/) for setup steps.

Well-connected docs feel smaller and friendlier.

Three levels maximum:

Section
  └── Page
        └── Sub-page  ← stop here

Deeper trees overwhelm readers.

9. Use `_` prefix to hide a file

Astro treats files starting with _ as partials — they are not routed. Useful for snippets:

_draft.md      ← not published
_notes.md      ← not published

10. Keep a changelog page

Add changelog.mdx at the root of docs/. Every time you update the docs, add an entry.

Example — Building a New Section

Let’s build a Deployment section from scratch.

Step 1 — Create the folder

src/content/docs/deployment/

Step 2 — Add the intro page

src/content/docs/deployment/index.mdx:

---
title: Deployment
description: Deploy your Astro Docus site to any static host.
tableOfContents: false
next: false
---

## Deployment Guides

Choose your hosting provider:

- [Cloudflare Pages](/deployment/cloudflare/)
- [Netlify](/deployment/netlify/)
- [Vercel](/deployment/vercel/)

Step 3 — Add content pages

src/content/docs/deployment/01-cloudflare.md:

---
title: Cloudflare Pages
description: Deploy Astro Docus to Cloudflare Pages.
---

## Cloudflare Pages

1. Push your project to GitHub.
2. Connect the repo to Cloudflare Pages.
3. Build command: `npm run build`
4. Output directory: `dist`

Repeat for 02-netlify.md, 03-vercel.md.

Step 4 — Register the section

In astro.config.mjs:

{
  label: 'Deployment',
  autogenerate: { directory: 'deployment' },
},

Step 5 — Preview

Run npm run dev. Visit /deployment/. The sidebar now shows the new section with all three pages in numeric order.

Rules to Remember

One folder = one section.
Every folder needs an index.mdx — it’s the intro page.
Filename = URL. Keep names short, lowercase, hyphenated.
Number prefixes control order in autogenerated sidebars.
Register each folder in astro.config.mjs.
Maximum 3 levels deep.
Group by intent, not by file type.
Keep frontmatter consistent across all pages.
Use _ prefix to hide drafts.
Link between pages to build a web, not a tree.

Quick Recap

src/content/docs/
├── index.mdx                    ← home / welcome
├── <section>/
│   ├── index.mdx                ← section intro
│   ├── 01-first-page.md
│   ├── 02-second-page.md
│   └── 03-third-page.md
└── <another-section>/
    └── index.mdx

astro.config.mjs:

sidebar: [
  { label: 'Section', autogenerate: { directory: 'section' } },
  { label: 'Another', autogenerate: { directory: 'another-section' } },
]

Golden rules:

Intro page in every folder
Numbered prefixes for order
Shallow trees for clarity
Intent-based groups for readers
Auto-generate for speed, manual for precision

A well-structured documentation site is invisible — readers never notice the structure, they just find what they need. That’s the goal.

Documentation Structure

Build Your Documentation

Docs Page

Docs Post Collections

Why Structure Matters

The Base Rule

The `index.mdx` File

Optional — Add a card grid

Naming Content Files

Avoid

Auto-Ordering with Number Prefixes

Registering Sections in astro.config.mjs

Manual sidebar

Auto-generated sidebar

Combining both

A Recommended Folder Layout

Tips & Tricks

1. Keep sections focused

2. Use `index.mdx` for navigation

3. Prefer `autogenerate` for reference, manual for tutorials

4. Use number prefixes for tutorials

5. Group by reader intent, not by file type

6. Keep frontmatter consistent

7. Link between pages

8. Keep the sidebar shallow

9. Use `_` prefix to hide a file

10. Keep a changelog page

Example — Building a New Section

Step 1 — Create the folder

Step 2 — Add the intro page

Step 3 — Add content pages

Step 4 — Register the section

Step 5 — Preview

Rules to Remember

Quick Recap

Documentation Structure

Build Your Documentation

Docs Page

Docs Post Collections

Why Structure Matters

The Base Rule

The index.mdx File

Optional — Add a card grid

Naming Content Files

Avoid

Auto-Ordering with Number Prefixes

Registering Sections in astro.config.mjs

Manual sidebar

Auto-generated sidebar

Combining both

A Recommended Folder Layout

Tips & Tricks

1. Keep sections focused

2. Use index.mdx for navigation

3. Prefer autogenerate for reference, manual for tutorials

4. Use number prefixes for tutorials

5. Group by reader intent, not by file type

6. Keep frontmatter consistent

7. Link between pages

8. Keep the sidebar shallow

9. Use _ prefix to hide a file

10. Keep a changelog page

Example — Building a New Section

Step 1 — Create the folder

Step 2 — Add the intro page

Step 3 — Add content pages

Step 4 — Register the section

Step 5 — Preview

Rules to Remember

Quick Recap

The `index.mdx` File

2. Use `index.mdx` for navigation

3. Prefer `autogenerate` for reference, manual for tutorials

9. Use `_` prefix to hide a file