Project Structure and Content Management

Overview

A well-organized project structure makes documentation easy to maintain and scale. This section covers how to organize content, manage assets, and use Astro’s Content Collections for type-safe documentation.

Q&A

Q: How should I organize my documentation content?

A: Starlight follows a directory-based routing system. Each .md file in src/content/docs/ becomes a page:

src/content/docs/
├── index.md                    # Homepage (/)
├── getting-started/
│   ├── index.md               # /getting-started/
│   ├── installation.md        # /getting-started/installation/
│   └── configuration.md       # /getting-started/configuration/
├── guides/
│   ├── index.md               # /guides/
│   ├── first-project.md       # /guides/first-project/
│   └── deployment.md          # /guides/deployment/
└── reference/
    ├── index.md               # /reference/
    ├── api.md                 # /reference/api/
    └── cli.md                 # /reference/cli/

Organizational principles:

Group related pages into directories (chapters, topics, categories)
Each directory has an index.md as a landing page with links to sub-pages
Use numbered prefixes in source files for ordering, but let the sidebar config control display order
Keep file names short and descriptive (they become URL slugs)

Q: What is the frontmatter schema?

A: Every Markdown file needs YAML frontmatter at the top. Starlight’s built-in schema requires:

---
title: Page Title              # Required: page title
description: Brief description  # Optional: SEO meta description
---

Additional frontmatter options:

---
title: Page Title
description: Brief description
tableOfContents: false          # Disable table of contents
head:                           # Custom <head> tags
  - tag: meta
    attrs:
      name: robots
      content: noindex
---

Q: How do I include images and other assets?

A: Static assets go in the public/ directory:

public/
├── images/
│   ├── architecture-diagram.png
│   └── screenshot-setup.png
├── favicon.svg
└── logo.svg

Reference them in Markdown with absolute paths:

![Setup Screenshot](/images/screenshot-setup.png)

For images that should be optimized (responsive, lazy-loaded), use Astro’s <Image> component in MDX files.

Q: How do Content Collections work?

A: Content Collections provide type-safe content loading. The configuration is in src/content.config.ts:

import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';
import { docsSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({
    loader: glob({
      base: 'src/content/docs',
      pattern: '**/[^_]*.md',
    }),
    schema: docsSchema(),
  }),
};

Benefits:

Type checking: Build fails if frontmatter doesn’t match the schema
Auto-generated types: TypeScript gets autocomplete for content fields
Consistent structure: All pages follow the same schema

Q: How do I add code blocks with syntax highlighting?

A: Starlight includes Shiki for syntax highlighting. Use triple backticks with a language identifier:

```javascript
const response = await fetch('/api/devices');
const devices = await response.json();
```

```yaml
mqtt:
  broker: mqtt://localhost:1883
  topic: sensors/temperature
```

```bash
npm run build
```

Supported features:

Line highlighting: Add {1,3} after the language to highlight specific lines
Diff highlighting: Use diff language with + and - prefixes
File names: Add title="filename.js" to show a file name header
Line numbers: Enabled by default in Starlight

Q: How do I add admonitions (tips, warnings, notes)?

A: Starlight supports GitHub-flavored admonitions:

> [!NOTE]
> This is a note for additional context.

> [!TIP]
> This is a helpful tip.

> [!CAUTION]
> This is a critical warning.

> [!DANGER]
> This action is irreversible.

These render as styled callout boxes in the documentation.

Building a commercial IoT product?

We provide ESP32 ODM design-to-manufacturing services. From prototype to production — the team behind this tutorial can build it with you.

Talk to us →