Astro Starlight Full Site Setup Tutorial

A complete beginner-to-intermediate guide for creating a real Astro Starlight tutorial site from scratch, adding pages, organizing folders, configuring navigation, customizing styles, building the project, and preparing it for deployment.

What You Are Building

In this tutorial, you will build a working Astro Starlight documentation site that can be used as a tutorial library, world bible, course site, reference manual, or project documentation site.

The finished project will include:

Big Picture Mental Model

Astro is the site builder. Starlight is the documentation theme. Markdown and MDX are the writing formats. Vercel, Netlify, Cloudflare Pages, or another host can publish the final site.

Markdown / MDX content
  ↓
Astro + Starlight
  ↓
Static website build
  ↓
dist/ folder
  ↓
Deploy online

Think of the project like a publishing workshop:

What You Need Before Starting

You should have:

Check Node and npm:

node -v
npm -v

If those commands show version numbers, you are ready to continue.

Create the Astro Project

Run this command in the folder where you keep your projects:

npm create astro@latest

The setup tool will ask questions. A practical beginner setup is:

Project name:
  astro-starlight-tutorial-site

Template:
  Starlight / Documentation starter if available

Install dependencies:
  Yes

Initialize git repository:
  Yes

TypeScript:
  Yes, recommended

If the setup tool does not offer Starlight as a starter, choose a basic Astro starter and add Starlight in the next step.

Add Starlight to an Existing Astro Project

If your Astro project does not already include Starlight, go into the project folder:

cd astro-starlight-tutorial-site

Then add Starlight:

npx astro add starlight

This installs the Starlight integration and updates your project configuration.

Start the Development Server

Run:

npm run dev

Astro will start a local development server. The local URL is commonly:

http://localhost:4321/

Open that URL in your browser. You should see your Starlight site.

Understand the Basic Project Structure

A basic Starlight project may look like this:

astro-starlight-tutorial-site/
  public/
  src/
    assets/
    content/
      docs/
        index.md
    components/
  astro.config.mjs
  package.json
  tsconfig.json

The most important files and folders are:

File or FolderPurpose
src/content/docs/Starlight documentation pages.
src/components/Reusable Astro components.
src/assets/Images and assets imported by Astro components.
public/Static files copied directly to the final site.
astro.config.mjsMain Astro and Starlight configuration file.
package.jsonProject scripts and dependencies.

Create a Useful Site Structure

For a tutorial site, create folders like this inside src/content/docs/:

src/content/docs/
  index.md
  getting-started.md
  lessons/
    index.md
    beginner/
      index.md
      markdown-basics.md
      yaml-basics.md
    intermediate/
      index.md
      mdx-components.md
      starlight-sidebar.md
    advanced/
      index.md
      content-collections.md
      component-overrides.md
  reference/
    index.md
    commands.md
    troubleshooting.md

This structure creates a clear learning path:

Start Here
  Getting Started

Lessons
  Beginner
  Intermediate
  Advanced

Reference
  Commands
  Troubleshooting

Create the Homepage

Edit or create:

src/content/docs/index.md

Add:

---
title: "Astro Starlight Tutorial Site"
description: "A tutorial library for learning Astro, Starlight, Markdown, MDX, content collections, and deployment."
template: splash
hero:
  title: "Astro Starlight Tutorial Site"
  tagline: "Build fast documentation, lesson, and world bible sites with Astro and Starlight."
  actions:
    - text: "Start Learning"
      link: "/getting-started/"
      icon: "right-arrow"
    - text: "View Lessons"
      link: "/lessons/"
      icon: "open-book"
---

## What This Site Covers

This site teaches how to build and maintain an Astro Starlight documentation project.

## Learning Paths

- Beginner setup
- Markdown and YAML
- MDX and custom components
- Sidebar navigation
- Content collections
- Styling and customization
- Deployment workflow

The template: splash frontmatter creates a more landing-page-style home page in Starlight.

Create a Getting Started Page

Create:

src/content/docs/getting-started.md

Add:

---
title: "Getting Started"
description: "Start here to learn how this tutorial site is organized."
---

# Getting Started

This tutorial site is organized into beginner, intermediate, advanced, and reference sections.

## Recommended Order

1. Learn the project structure.
2. Learn Markdown and YAML.
3. Learn MDX components.
4. Learn Starlight sidebar navigation.
5. Learn content collections.
6. Customize and deploy the site.

Create Lesson Index Pages

Create:

src/content/docs/lessons/index.md

Add:

---
title: "Lessons"
description: "Browse beginner, intermediate, and advanced Astro Starlight lessons."
---

# Lessons

Use this section to learn Astro and Starlight step by step.

## Sections

- [Beginner Lessons](/lessons/beginner/)
- [Intermediate Lessons](/lessons/intermediate/)
- [Advanced Lessons](/lessons/advanced/)

Create similar index.md pages for lessons/beginner/, lessons/intermediate/, and lessons/advanced/.

Create a Sample Lesson Page

Create:

src/content/docs/lessons/beginner/markdown-basics.md

Add:

---
title: "Markdown Basics"
description: "Learn how Markdown pages work in a Starlight site."
---

# Markdown Basics

Markdown is a plain-text format for writing structured content.

## Headings

Use number signs for headings.

```md
# Page Title
## Major Section
### Smaller Section
```

## Lists

```md
- One item
- Another item
- A third item
```

## Summary

Markdown is the main writing format for most Starlight pages.

Create a Reference Section

Create:

src/content/docs/reference/index.md

Add:

---
title: "Reference"
description: "Quick references, commands, and troubleshooting notes."
---

# Reference

This section contains quick lookup pages.

- [Commands](/reference/commands/)
- [Troubleshooting](/reference/troubleshooting/)

Create:

src/content/docs/reference/commands.md

Add:

---
title: "Common Commands"
description: "Common Astro and Starlight project commands."
---

# Common Commands

## Start the local dev server

```bash
npm run dev
```

## Build the production site

```bash
npm run build
```

## Preview the production build locally

```bash
npm run preview
```

Configure the Starlight Sidebar

Open:

astro.config.mjs

A basic Starlight configuration looks like this:

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Astro Starlight Tutorial Site',
    }),
  ],
});

Now add a sidebar:

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Astro Starlight Tutorial Site',
      sidebar: [
        {
          label: 'Start Here',
          items: [
            { label: 'Home', slug: '' },
            { label: 'Getting Started', slug: 'getting-started' },
          ],
        },
        {
          label: 'Lessons',
          items: [
            { label: 'Lesson Overview', slug: 'lessons' },
            {
              label: 'Beginner',
              autogenerate: { directory: 'lessons/beginner' },
            },
            {
              label: 'Intermediate',
              autogenerate: { directory: 'lessons/intermediate' },
            },
            {
              label: 'Advanced',
              autogenerate: { directory: 'lessons/advanced' },
            },
          ],
        },
        {
          label: 'Reference',
          autogenerate: { directory: 'reference' },
        },
      ],
    }),
  ],
});

This is a hybrid sidebar. The big sections are manual, while the lesson pages inside folders can be autogenerated.

Add Custom CSS

Create:

src/styles/custom.css

Add simple custom styles:

:root {
  --sl-content-width: 52rem;
}

.card-grid {
  display: grid;
  gap: 1rem;
}

.lesson-card {
  border: 1px solid var(--sl-color-gray-5);
  border-radius: 0.75rem;
  padding: 1rem;
}

Then register the CSS file in astro.config.mjs:

export default defineConfig({
  integrations: [
    starlight({
      title: 'Astro Starlight Tutorial Site',
      customCss: ['./src/styles/custom.css'],
      sidebar: [
        // sidebar items here
      ],
    }),
  ],
});

Add Static Assets

For simple static assets, use the public/ folder:

public/
  favicon.png
  images/
    site-logo.png
    screenshots/
    diagrams/
  downloads/

Reference public images with root-relative paths:

![Site Logo](/images/site-logo.png)

Create a Simple MDX Page

Markdown is enough for most pages. Use MDX when you need components.

Add MDX support if needed:

npx astro add mdx

Create:

src/content/docs/lessons/intermediate/example-mdx-page.mdx

Add:

---
title: "Example MDX Page"
description: "A Starlight page that can use components."
---

# Example MDX Page

This page uses MDX.

<div className="lesson-card">
  <h2>MDX Card Example</h2>
  <p>MDX lets you mix Markdown with component-style markup.</p>
</div>

Add a Reusable Astro Component

Create:

src/components/LessonCallout.astro

Add:

---
const { title = 'Lesson Note' } = Astro.props;
---

<aside class="lesson-card">
  <h2>{title}</h2>
  <slot />
</aside>

Use it inside an MDX file:

---
title: "Using Components in MDX"
description: "A lesson using a reusable Astro component."
---

import LessonCallout from "../../../components/LessonCallout.astro";

# Using Components in MDX

<LessonCallout title="Remember">
Markdown is for writing. MDX is for writing plus components.
</LessonCallout>

Check the Site Locally

Run:

npm run dev

Check these things in the browser:

Build the Production Site

Run:

npm run build

If the build succeeds, Astro creates a production-ready output folder:

dist/

This folder is what static hosts publish online.

Preview the Production Build

Run:

npm run preview

This serves the built dist/ version locally. This is useful because sometimes a site works in development but has broken links, paths, or assets after building.

Prepare for Deployment

Before deploying, check:

Typical static deployment settings:

SettingValue
Build commandnpm run build
Output directorydist
Install commandnpm install or automatic default

Git Workflow

Initialize Git if you did not do so during project setup:

git init
git add .
git commit -m "Initial Astro Starlight tutorial site"

Add your GitHub remote:

git remote add origin YOUR_REPOSITORY_URL
git branch -M main
git push -u origin main

After the site is connected to a host such as Vercel or Netlify, future updates usually follow this pattern:

git add .
git commit -m "Add new lesson"
git push

Recommended Tutorial Site Table of Contents

Start Here
  Home
  Getting Started

Core Tools
  YAML
  Markdown
  MDX
  Astro Basics
  Starlight Basics

Project Structure
  Folder Structure
  Sidebar Navigation
  Assets and Images
  Custom CSS

Components
  Components in MDX
  Callout Components
  Character Cards
  Lesson Cards

Content Architecture
  Content Collections
  Schemas
  Dynamic Routes
  Tags and Categories

Customization
  Styling
  Homepage Design
  Component Overrides

Deployment
  Build and Preview
  Vercel
  Netlify
  Cloudflare Pages
  Troubleshooting

Recommended Folder Structure for a Full Tutorial Site

src/content/docs/
  index.md
  getting-started.md

  core-tools/
    index.md
    yaml.md
    markdown.md
    mdx.md

  project-structure/
    index.md
    folders.md
    sidebar.md
    assets.md

  components/
    index.md
    mdx-components.md
    callouts.md
    cards.md

  content-architecture/
    index.md
    content-collections.md
    schemas.md
    dynamic-routes.md
    tags.md

  customization/
    index.md
    styling.md
    homepage.md
    overrides.md

  deployment/
    index.md
    build-preview.md
    vercel.md
    netlify.md
    troubleshooting.md

Common Problems and Fixes

Problem: The sidebar link goes to a 404 page

Check the slug. A file at:

src/content/docs/lessons/beginner/markdown-basics.md

usually maps to:

lessons/beginner/markdown-basics

Problem: A new page does not appear in the sidebar

If you are using a manual sidebar, you must add the new page manually or use an autogenerated group.

Problem: Images do not load

If the image is in public/images/, reference it like this:

![Example Image](/images/example.png)

Problem: Build fails after adding MDX

Check that the MDX file has valid JSX-style syntax and that imported components use the correct relative paths.

Problem: Site works in dev but not after build

Run:

npm run build
npm run preview

Then test the built site locally before deploying.

Best Practices

Mini Project Checklist

[ ] Project created
[ ] Starlight installed
[ ] Dev server runs
[ ] Homepage created
[ ] Getting started page created
[ ] Lesson folders created
[ ] Reference section created
[ ] Sidebar configured
[ ] Custom CSS connected
[ ] Sample Markdown lesson added
[ ] Optional MDX lesson added
[ ] Build succeeds
[ ] Preview succeeds
[ ] Git repository created
[ ] Project pushed to GitHub
[ ] Deployment settings ready

Simple Rule of Thumb

Use Astro for the build system.
Use Starlight for the docs experience.
Use Markdown for normal pages.
Use MDX for component-rich pages.
Use src/content/docs/ for docs content.
Use astro.config.mjs for site configuration.
Use npm run build before deployment.
Use dist/ as the static output folder.

What to Learn Next