Initializing an Astro + Starlight Project

Overview

This section walks through the exact steps to create a new Astro + Starlight documentation site from scratch. By the end, you’ll have a running local development server with a working documentation site.

Q&A

Q: What do I need before starting?

A: Ensure you have:

Node.js v22+ installed (check with node --version)
npm (comes with Node.js)
A code editor (VS Code recommended, with the Astro extension)

Q: How do I create the project?

A: Use the official Astro CLI to scaffold the project:

# Create a new Astro project with Starlight template
npm create astro@latest my-docs -- --template starlight

# Navigate into the project
cd my-docs

# Install dependencies
npm install

# Start the development server
npm run dev

The CLI will ask a few questions:

TypeScript: Choose “Strict” for type safety
Install dependencies: Yes
Git repository: Yes (initialize a Git repo)

Once running, open http://localhost:4321 to see your new documentation site.

Q: What does the initial project structure look like?

A: After scaffolding, your project contains:

my-docs/
├── src/
│   ├── content/
│   │   └── docs/          # Your documentation content goes here
│   │       ├── index.md   # Homepage
│   │       └── guide.md   # Example guide page
│   └── content.config.ts  # Content collection configuration
├── public/                 # Static assets (images, favicon, etc.)
├── astro.config.mjs       # Astro + Starlight configuration
├── package.json
└── tsconfig.json

Q: How do I configure the basic site settings?

A: Edit astro.config.mjs:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  site: 'https://docs.yourcompany.com',
  integrations: [
    starlight({
      title: 'My Product Docs',
      social: [
        { icon: 'github', label: 'GitHub', href: 'https://github.com/yourcompany' },
      ],
      sidebar: [
        {
          label: 'Guides',
          items: [{ autogenerate: { directory: 'guides' } }],
        },
        {
          label: 'Reference',
          items: [{ autogenerate: { directory: 'reference' } }],
        },
      ],
    }),
  ],
});

Key settings:

site: Your production URL (used for sitemaps and SEO metadata)
title: Displayed in the header and browser tab
sidebar: Defines the navigation structure
autogenerate: Automatically generates sidebar items from a directory of Markdown files

Q: How do I add my first content page?

A: Create a Markdown file in src/content/docs/:

---
title: Getting Started
description: Learn how to set up and configure the product.
---

## Getting Started

Welcome to the documentation! This guide will help you get up and running.

### Installation

Install the software using npm:

\```bash
npm install my-product
\```

### Configuration

Create a configuration file `config.yaml`:

\```yaml
port: 8080
database:
  host: localhost
  port: 5432
\```

### Next Steps

- Read the [API Reference](/reference/api/)
- Check out [example projects](/guides/examples/)

The title in the frontmatter is required. Starlight uses it for the page title, sidebar label, and SEO metadata.

Q: What is the difference between `index.md` and other files?

A: Each directory can have an index.md that serves as the directory’s landing page:

src/content/docs/
├── index.md          # Site homepage (with hero section)
├── guides/
│   ├── index.md      # Guides section landing page
│   ├── setup.md      # /guides/setup/
│   └── examples.md   # /guides/examples/
└── reference/
    └── api.md        # /reference/api/

The root index.md can use the splash template for a hero landing page:

---
title: Home
template: splash
hero:
  title: My Product Documentation
  tagline: Everything you need to build with My Product.
  actions:
    - text: Get Started
      link: /guides/setup/
      variant: primary
    - text: View on GitHub
      link: https://github.com/yourcompany
      variant: secondary
---

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 →

Initializing an Astro + Starlight Project