Astro and Starlight Basic Tutorial

What You Are Building

This tutorial shows how to create a basic documentation-style website using Astro and Starlight.

Astro is a framework for building fast, content-focused websites. Starlight is Astro's official documentation framework/theme. Together, they are a good fit for guides, lesson sites, manuals, reference sites, project notes, and worldbuilding-style documentation.

The Big Picture

Astro gives you the site-building system. Starlight gives you a ready-made documentation layout with navigation, sidebars, search, Markdown support, and a polished structure.

A simple mental model:

Astro = the engine
Starlight = the documentation dashboard
Markdown files = your pages
astro.config.mjs = your control panel

When to Use Astro and Starlight

Use Astro and Starlight when your project is mostly written content organized into pages.

Do not choose Starlight first if you are building a complex web app with accounts, dashboards, live editing, and database-heavy workflows. For that kind of project, you may want something like Next.js, SvelteKit, Nuxt, Laravel, Django, or another app-focused framework.

Prerequisites

Before starting, install Node.js. You should also be comfortable opening a terminal and running commands.

Check your installed versions:

node -v
npm -v

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

Create a New Starlight Project

The fastest beginner-friendly path is to create a new Astro project from the official Starlight starter.

npm create astro@latest my-starlight-site -- --template starlight

Then move into the project folder:

cd my-starlight-site

Install dependencies if the setup did not already do so:

npm install

Start the local development server:

npm run dev

Astro usually serves the local site at:

http://localhost:4321

Alternative: Add Starlight to an Existing Astro Project

If you already have an Astro project, you can add Starlight with:

npx astro add starlight

This installs the Starlight integration and updates the project configuration.

Basic Project Structure

A simple Starlight project usually looks similar to this:

my-starlight-site/
  astro.config.mjs
  package.json
  public/
  src/
    assets/
    content/
      docs/
        index.mdx
        guides/
          example.md

The most important folder is:

src/content/docs/

That is where your documentation pages live.

Create Your First Page

Inside src/content/docs/, create a file named getting-started.md.

---
title: Getting Started
description: A beginner-friendly introduction to the site.
---

# Getting Started

Welcome to the site.

This page introduces the project and explains where to go next.

## What This Site Contains

- Guides
- Reference pages
- Lessons
- Examples

## Next Step

Open the first guide and follow the instructions.

The top section between the triple dashes is called frontmatter. It stores page metadata such as the title and description.

Markdown Basics

Most Starlight pages are written in Markdown or MDX.

# Main Heading

## Section Heading

This is a paragraph.

- Bullet item
- Another bullet item

[Link text](https://example.com)

```js
console.log('Hello, Astro!');
```

Markdown is useful because you can focus on writing content instead of repeating full HTML structure on every page.

Configure the Site Title and Sidebar

Open astro.config.mjs. A Starlight configuration may look similar to this:

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Documentation Site',
      sidebar: [
        {
          label: 'Start Here',
          items: [
            { label: 'Getting Started', slug: 'getting-started' },
          ],
        },
      ],
    }),
  ],
});

The title controls the site name. The sidebar controls the navigation links shown in the documentation layout.

Example Sidebar for a Lesson Site

sidebar: [
  {
    label: 'Course Introduction',
    items: [
      { label: 'Welcome', slug: 'welcome' },
      { label: 'How to Use This Course', slug: 'how-to-use-this-course' },
    ],
  },
  {
    label: 'Lessons',
    items: [
      { label: 'Lesson One', slug: 'lessons/lesson-one' },
      { label: 'Lesson Two', slug: 'lessons/lesson-two' },
    ],
  },
]

This works well for tutorials, course notes, software manuals, and structured learning paths.

Example Sidebar for a Worldbuilding Site

sidebar: [
  {
    label: 'World Bible',
    items: [
      { label: 'Overview', slug: 'world/overview' },
      { label: 'Timeline', slug: 'world/timeline' },
    ],
  },
  {
    label: 'Reference',
    items: [
      { label: 'Regions', slug: 'reference/regions' },
      { label: 'Characters', slug: 'reference/characters' },
      { label: 'Factions', slug: 'reference/factions' },
      { label: 'Locations', slug: 'reference/locations' },
    ],
  },
]

Starlight is not specifically a worldbuilding app, but its documentation structure can work very well for a world bible, lore guide, setting reference, or campaign wiki.

Add More Pages

You can organize pages in folders.

src/content/docs/
  index.mdx
  getting-started.md
  lessons/
    lesson-one.md
    lesson-two.md
  reference/
    glossary.md
    resources.md

A page at:

src/content/docs/lessons/lesson-one.md

usually becomes a URL like:

/lessons/lesson-one/

Use MDX When You Need Components

Use regular .md files for normal writing. Use .mdx files when you want to mix Markdown with components.

For example, an MDX page could include a reusable card, diagram component, or custom warning box.

---
title: Example MDX Page
---

import MyCard from '../../components/MyCard.astro';

# Example MDX Page

This is normal Markdown.

<MyCard title="Important Note" />

For beginners, start with Markdown. Add MDX later only when you need richer page features.

Common Commands

Command Purpose
npm run dev Starts the local development server.
npm run build Builds the production version of the site.
npm run preview Previews the production build locally.
npx astro add starlight Adds Starlight to an existing Astro project.
npx @astrojs/upgrade Updates Astro-related packages.

Build the Site

Before deploying, always test the production build:

npm run build

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

dist

That dist folder is what hosting services publish online.

Preview the Built Site

After building, preview the production output:

npm run preview

This lets you check the final site before deployment.

Deploy to Netlify

For Netlify, the basic settings are:

Build command: npm run build
Publish directory: dist

Connect your GitHub repository to Netlify, set those build options, and deploy.

Deploy to Vercel

For Vercel, import the GitHub repository and use the Astro framework preset when available.

Build command: npm run build
Output directory: dist

Vercel often detects Astro projects automatically, but it is still useful to understand these settings.

Common Beginner Problems

The Site Does Not Start

Try reinstalling dependencies:

npm install
npm run dev

A Page Does Not Appear in the Sidebar

Creating a Markdown file does not always mean it appears in your sidebar. Add the page to the Starlight sidebar configuration in astro.config.mjs.

The Build Fails

Run the build locally and read the error message carefully:

npm run build

Common causes include broken links, invalid frontmatter, missing files, or syntax errors in configuration.

Images Do Not Load

Static files can go in the public folder. For example:

public/images/logo.png

You can reference it like this:

![Logo](/images/logo.png)

Suggested Lesson Site Structure

src/content/docs/
  index.mdx
  getting-started.md
  lessons/
    what-is-html.md
    what-is-css.md
    what-is-javascript.md
  exercises/
    html-practice.md
    css-practice.md
  reference/
    glossary.md
    commands.md

This structure is good for beginner programming tutorials, software lessons, and course-style websites.

Suggested Worldbuilding Site Structure

src/content/docs/
  index.mdx
  world/
    overview.md
    timeline.md
    technology.md
  regions/
    europe.md
    north-america.md
  characters/
    main-cast.md
    supporting-cast.md
  factions/
    overview.md
  locations/
    major-cities.md
  storylines/
    main-series.md

This structure turns Starlight into a reference archive. It is not a database, but it is very useful for published worldbuilding documentation.

Practice Exercise

Create a small Starlight site with the following pages:

Then update the sidebar so all three pages are visible.

Finally, run:

npm run build
npm run preview

If the preview works, your site is ready to deploy.

Cheat Sheet

Create a new Starlight site:
npm create astro@latest my-starlight-site -- --template starlight

Go into the folder:
cd my-starlight-site

Start development:
npm run dev

Add a page:
src/content/docs/my-page.md

Configure navigation:
astro.config.mjs

Build for production:
npm run build

Preview production build:
npm run preview

Deploy output folder:
dist

Final Summary

Astro and Starlight are excellent when your site is mostly structured written content. Astro provides the framework. Starlight provides the documentation layout. Markdown provides the content format.

The basic workflow is:

Create project
Write Markdown pages
Configure sidebar
Run local server
Build site
Deploy dist folder

Once you understand that workflow, you can use Astro and Starlight for tutorials, guides, manuals, worldbuilding references, and other organized content sites.

Sources and Further Reading