Starlight Lesson Library Site Tutorial

A practical capstone tutorial for building a complete lesson library, course guide, or tutorial documentation site with Astro and Starlight.

What You Are Building

In this tutorial, you will design a full lesson library site using Astro and Starlight. The site will organize lessons by level, topic, course, and reference type.

The finished site can support:

The Big Picture

Homepage
  ↓
Learning paths
  ↓
Course sections
  ↓
Lesson pages
  ↓
Exercises and references
  ↓
Deployment

A lesson library is not just a folder full of pages. It is a guided learning system. The site should help learners answer: where do I start, what do I read next, and where do I go when I get stuck?

Recommended Site Structure

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

  lessons/
    index.md
    beginner/
      index.md
      html-basics.md
      css-basics.md
      markdown-basics.md
    intermediate/
      index.md
      mdx-components.md
      starlight-sidebar.md
      content-collections.md
    advanced/
      index.md
      dynamic-routes.md
      component-overrides.md
      deployment-workflow.md

  courses/
    index.md
    astro-starlight/
      index.md
      setup.md
      project-structure.md
      deployment.md

  exercises/
    index.md
    markdown-practice.md
    component-practice.md

  reference/
    index.md
    commands.md
    glossary.md
    troubleshooting.md
    cheat-sheets.md

Homepage Purpose

The homepage should not list everything. It should direct the learner to the correct path.

Homepage sections:
  Hero
  Start Here
  Beginner / Intermediate / Advanced cards
  Featured course
  Reference links
  Troubleshooting link

A good lesson-library homepage gives readers confidence that the material has an order.

Homepage Example

Create or edit:

src/content/docs/index.md
---
title: "Astro Starlight Lesson Library"
description: "A structured tutorial library for learning Astro, Starlight, Markdown, MDX, and deployment."
template: splash
hero:
  title: "Astro Starlight Lesson Library"
  tagline: "Learn by following guided paths, examples, exercises, and reference pages."
  actions:
    - text: "Start Learning"
      link: "/getting-started/"
      icon: "right-arrow"
    - text: "Browse Lessons"
      link: "/lessons/"
      icon: "open-book"
    - text: "Reference"
      link: "/reference/"
      icon: "information"
      variant: "minimal"
---

## Choose a Learning Path

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

## Featured Course

Start with the [Astro Starlight Course](/courses/astro-starlight/).

Lesson Page Template

Every lesson should feel familiar. Use the same section pattern again and again.

---
title: "Markdown Basics"
description: "Learn how Markdown works in Astro and Starlight."
level: "beginner"
course: "Astro Starlight"
order: 1
tags:
  - markdown
  - writing
  - starlight
---

# Markdown Basics

## What You Are Learning

## Why This Matters

## Mental Model

## Step-by-Step Guide

## Example

## Common Mistakes

## Practice Exercise

## Summary

## What to Learn Next

Course Page Template

---
title: "Astro Starlight Course"
description: "A guided path through Astro and Starlight site building."
---

# Astro Starlight Course

## Course Goal

Build a complete documentation site.

## Recommended Order

1. Full Site Setup
2. Project Structure
3. Sidebar Navigation
4. Markdown and MDX
5. Custom Components
6. Content Collections
7. Styling
8. Deployment

## Lessons

- [Full Site Setup](/courses/astro-starlight/setup/)
- [Project Structure](/courses/astro-starlight/project-structure/)
- [Deployment](/courses/astro-starlight/deployment/)

Exercise Page Template

---
title: "Markdown Practice Exercise"
description: "Practice writing a lesson page in Markdown."
difficulty: "beginner"
relatedLesson: "markdown-basics"
---

# Markdown Practice Exercise

## Goal

Create a Markdown lesson page.

## Starter Instructions

1. Create a new file.
2. Add frontmatter.
3. Add headings.
4. Add a list.
5. Add a code block.

## Expected Result

A readable Markdown page with title, sections, and examples.

## Stretch Goal

Add a table and a link to another lesson.

Sidebar Configuration

Use a sidebar that reflects the learning path.

sidebar: [
  {
    label: 'Start Here',
    items: [
      { label: 'Home', slug: '' },
      { label: 'Getting Started', slug: 'getting-started' },
    ],
  },
  {
    label: 'Lessons',
    items: [
      { label: 'Overview', slug: 'lessons' },
      { label: 'Beginner', autogenerate: { directory: 'lessons/beginner' } },
      { label: 'Intermediate', autogenerate: { directory: 'lessons/intermediate' } },
      { label: 'Advanced', autogenerate: { directory: 'lessons/advanced' } },
    ],
  },
  {
    label: 'Courses',
    autogenerate: { directory: 'courses' },
  },
  {
    label: 'Exercises',
    autogenerate: { directory: 'exercises' },
  },
  {
    label: 'Reference',
    autogenerate: { directory: 'reference' },
  },
]

Content Collections for Lessons

If you want dynamic indexes and filtering, create a lesson collection.

import { defineCollection, z } from 'astro:content';

const lessons = defineCollection({
  schema: z.object({
    title: z.string(),
    description: z.string(),
    level: z.enum(['beginner', 'intermediate', 'advanced']),
    course: z.string().optional(),
    order: z.number(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
  }),
});

export const collections = { lessons };

Use a schema when you want lesson metadata to stay consistent.

Lesson Card Component

A reusable lesson card can make indexes easier to scan.

---
const { title, description, href, level } = Astro.props;
---

<article class="lesson-card">
  <p><strong>{level}</strong></p>
  <h2><a href={href}>{title}</a></h2>
  <p>{description}</p>
</article>

Custom CSS for Lesson Cards

.lesson-grid {
  display: grid;
  gap: 1rem;
  grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr));
}

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

Reference Section

A lesson library needs quick-reference pages for learners who are stuck.

reference/
  commands.md
  glossary.md
  troubleshooting.md
  cheat-sheets.md
  common-errors.md

Reference pages should be short, searchable, and practical.

Recommended Tags

level tags:
  beginner
  intermediate
  advanced

topic tags:
  markdown
  mdx
  yaml
  astro
  starlight
  deployment
  components
  content-collections

format tags:
  tutorial
  exercise
  reference
  checklist

Build Checklist

[ ] Homepage has a clear start button
[ ] Getting Started page exists
[ ] Beginner, intermediate, and advanced folders exist
[ ] Each major folder has an index.md page
[ ] Sidebar matches the learning path
[ ] Lesson pages use a consistent structure
[ ] Exercise pages are separated from lessons
[ ] Reference pages are easy to find
[ ] Tags are consistent
[ ] npm run build succeeds
[ ] npm run preview works

Common Mistakes

Too many lessons at the same level

Separate beginner, intermediate, and advanced material so learners are not overwhelmed.

No index pages

Every major folder should have an index.md page that explains what the section contains.

Lessons without practice

For learning sites, include exercises, mini projects, or checklists.

Reference pages mixed with lessons

Keep guided lessons and quick-reference pages separate.

Simple Rule of Thumb

Homepage guides the learner.
Sidebar organizes the journey.
Lessons teach one topic at a time.
Exercises turn reading into practice.
Reference pages help when stuck.
Indexes help learners choose what to read next.