Starlight Homepage and Landing Page Tutorial

What You Are Building

In this tutorial, you will create a strong homepage for a Starlight site. The homepage will help readers understand what the site is, where to start, and which major sections they can explore.

You will learn how to use:

The Starlight template: splash layout.
The hero frontmatter option.
Hero action buttons.
Homepage cards and learning paths.
Section links for lessons, reference pages, and world bible content.
Custom CSS for homepage card layouts.

Why the Homepage Matters

A documentation or tutorial site can quickly become large. A good homepage acts like a lobby in a large building. It does not contain every room, but it shows people where the important hallways are.

Homepage
  ↓
Start Here
  ↓
Learning Paths
  ↓
Major Sections
  ↓
Reference / Troubleshooting

For a tutorial site, the homepage should answer these questions:

What is this site about?
Who is this site for?
Where should a beginner start?
Where should an experienced user go?
Where are the reference pages?
What are the main categories?

Where the Homepage Lives

In a normal Starlight project, the homepage is usually:

src/content/docs/index.md

This file becomes the root page of your documentation site.

src/content/docs/index.md
  → /

If your Starlight docs are mounted under another route, the exact URL may differ, but index.md is still the main landing page for that folder.

Basic Starlight Homepage

A simple Starlight homepage can be just a Markdown page:

---
title: "Astro Starlight Tutorial Site"
description: "Learn Astro, Starlight, Markdown, MDX, and content collections."
---

# Astro Starlight Tutorial Site

Welcome to the tutorial site.

## Start Here

- [Getting Started](/getting-started/)
- [Lessons](/lessons/)
- [Reference](/reference/)

This works, but it still looks like a normal documentation page. For a more polished landing page, use the splash template.

Use the Splash Template

Starlight pages use the normal documentation layout by default. A landing page usually works better with:

template: splash

The splash template gives the page a wider layout without the normal documentation sidebars. It is designed for landing pages and homepages.

---
title: "Astro Starlight Tutorial Site"
description: "Learn Astro and Starlight step by step."
template: splash
---

Use template: splash when a page is more like a front door than a reference article.

Add a Hero Section

The hero section is the large introduction area at the top of the page. It usually includes a title, tagline, and action buttons.

---
title: "Astro Starlight Tutorial Site"
description: "Learn Astro and Starlight step by step."
template: splash
hero:
  title: "Build Better Documentation Sites"
  tagline: "Learn how to create tutorial libraries, world bibles, and reference sites with Astro and Starlight."
---

The hero should be short and clear. Do not try to explain the whole project in the hero text.

Add Hero Action Buttons

Hero actions are buttons that point readers to important next steps.

---
title: "Astro Starlight Tutorial Site"
description: "Learn Astro and Starlight step by step."
template: splash
hero:
  title: "Build Better Documentation Sites"
  tagline: "Create fast, organized, searchable sites for tutorials, lessons, and worldbuilding."
  actions:
    - text: "Start Learning"
      link: "/getting-started/"
      icon: "right-arrow"
    - text: "Browse Lessons"
      link: "/lessons/"
      icon: "open-book"
    - text: "View Reference"
      link: "/reference/"
      icon: "information"
      variant: "minimal"
---

The first action should be the most important. For most tutorial sites, that is Start Learning or Getting Started.

Add a Hero Image

You can add a hero image from your project. For example, place a logo or illustration in:

src/assets/site-logo.png

Then reference it in frontmatter:

---
title: "Astro Starlight Tutorial Site"
template: splash
hero:
  title: "Build Better Documentation Sites"
  tagline: "Learn Astro and Starlight step by step."
  image:
    alt: "A simple documentation site logo"
    file: "~/assets/site-logo.png"
---

Always include useful alt text. Alt text should describe the image, not simply say “image.”

Full Homepage Frontmatter Example

Here is a complete starting point:

---
title: "Astro Starlight Tutorial Site"
description: "A tutorial library for learning Astro, Starlight, Markdown, MDX, content collections, customization, 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: "Browse Lessons"
      link: "/lessons/"
      icon: "open-book"
    - text: "Reference"
      link: "/reference/"
      icon: "information"
      variant: "minimal"
---

Homepage Content After the Hero

After the frontmatter, you can write normal Markdown content.

## What This Site Teaches

This site teaches how to build and maintain Astro Starlight projects.

## Learning Paths

Choose a path based on your goal:

- New to Astro? Start with the beginner path.
- Building a tutorial site? Use the lesson library path.
- Building a world bible? Use the worldbuilding path.
- Customizing Starlight? Use the advanced path.

The hero introduces the site. The body of the homepage organizes the reader's choices.

Create Homepage Cards with Markdown

The simplest homepage cards can be normal Markdown sections.

## Learning Paths

### Beginner Path

Start here if you are new to Astro and Starlight.

[Beginner Lessons](/lessons/beginner/)

### Intermediate Path

Learn MDX, components, sidebars, and site structure.

[Intermediate Lessons](/lessons/intermediate/)

### Advanced Path

Learn content collections, schemas, overrides, and deployment.

[Advanced Lessons](/lessons/advanced/)

This is easy to maintain, but it may not look like a card grid. For a card-like layout, use HTML or an MDX component.

Create a Card Grid in Markdown

Markdown pages can include simple HTML when needed.

<div class="home-card-grid">

<article class="home-card">
  <h2>Beginner Path</h2>
  <p>Start here if you are new to Astro and Starlight.</p>
  <a href="/lessons/beginner/">Beginner Lessons</a>
</article>

<article class="home-card">
  <h2>Intermediate Path</h2>
  <p>Learn MDX, components, and sidebar structure.</p>
  <a href="/lessons/intermediate/">Intermediate Lessons</a>
</article>

<article class="home-card">
  <h2>Advanced Path</h2>
  <p>Learn schemas, overrides, deployment, and advanced customization.</p>
  <a href="/lessons/advanced/">Advanced Lessons</a>
</article>

</div>

This gives you a reusable visual structure without creating a component yet.

Add CSS for Homepage Cards

Create or edit:

src/styles/custom.css

Add:

.home-card-grid {
  display: grid;
  gap: 1rem;
  grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr));
  margin-block: 2rem;
}

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

.home-card h2 {
  margin-top: 0;
}

.home-card a {
  font-weight: 700;
}

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

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

Homepage Layout for a Tutorial Site

A tutorial-site homepage should guide learners by skill level or goal.

Hero
  Site title
  Short promise
  Start button
  Lessons button

What This Site Teaches
  Short explanation

Learning Paths
  Beginner
  Intermediate
  Advanced

Core Topics
  YAML
  Markdown
  MDX
  Components
  Content Collections
  Deployment

Reference
  Commands
  Troubleshooting
  Glossary

Homepage Layout for a World Bible Site

A world bible homepage should guide readers by setting category.

Hero
  World title
  Short setting premise
  Start reading button
  Timeline button

Explore the World
  Regions
  Characters
  Factions
  Locations
  Storylines
  Timeline

Start Here
  World overview
  Reading guide
  Major conflicts
  Glossary

Featured Entries
  Featured character
  Featured region
  Featured storyline

The same Starlight splash-page tools work for both tutorials and worldbuilding.

Homepage Layout for a Software Documentation Site

Hero
  Product name
  What the tool does
  Get started
  Install

Quick Start
  Install command
  First project
  Configuration

Guides
  Concepts
  API reference
  Deployment
  Troubleshooting

Community / Links
  GitHub
  Changelog
  Support

Complete Homepage Example

Create or replace:

src/content/docs/index.md

Use this complete example:

---
title: "Astro Starlight Tutorial Site"
description: "Learn how to build documentation, lesson, and world bible sites with Astro and Starlight."
template: splash
hero:
  title: "Astro Starlight Tutorial Site"
  tagline: "Build fast, organized, searchable sites for tutorials, reference guides, and worldbuilding projects."
  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"
---

## What This Site Teaches

This site teaches how to create, organize, customize, and deploy Astro Starlight projects.

<div class="home-card-grid">

<article class="home-card">
  <h2>Beginner Path</h2>
  <p>Start here if you are new to Astro, Starlight, Markdown, and YAML.</p>
  <a href="/lessons/beginner/">Beginner Lessons</a>
</article>

<article class="home-card">
  <h2>Intermediate Path</h2>
  <p>Learn project structure, sidebar navigation, MDX, and reusable components.</p>
  <a href="/lessons/intermediate/">Intermediate Lessons</a>
</article>

<article class="home-card">
  <h2>Advanced Path</h2>
  <p>Learn content collections, schemas, component overrides, and deployment workflows.</p>
  <a href="/lessons/advanced/">Advanced Lessons</a>
</article>

</div>

## Core Topics

- [YAML Frontmatter](/core-tools/yaml/)
- [Markdown and MDX](/core-tools/markdown-mdx/)
- [Sidebar Navigation](/project-structure/sidebar/)
- [Custom Components](/components/mdx-components/)
- [Content Collections](/content-architecture/content-collections/)
- [Deployment](/deployment/)

## Recommended Next Step

New readers should begin with [Getting Started](/getting-started/).

Add a Banner

Starlight pages can include a banner in frontmatter. This is useful for announcements, version notes, or important guidance.

---
title: "Astro Starlight Tutorial Site"
template: splash
banner:
  content: |
    New tutorial path added: <a href="/lessons/advanced/">Advanced Astro and Starlight</a>
---

Use banners sparingly. If every page has an announcement, readers stop noticing them.

Disable or Adjust the Table of Contents

Landing pages often do not need a table of contents. On a splash page, the layout is already simplified, but you can also adjust frontmatter if needed.

---
title: "Astro Starlight Tutorial Site"
template: splash
tableOfContents: false
---

For long landing pages, a table of contents can still be useful. For short homepages, disabling it may feel cleaner.

Homepage Links and Sidebar Strategy

The homepage and sidebar have different jobs.

Element	Job
Homepage	Guide readers to the most important starting points.
Sidebar	Help readers navigate the site while reading.
Search	Help readers find a specific page quickly.

Do not make the homepage repeat the entire sidebar. Highlight the most important choices instead.

Good Homepage Writing

A good homepage uses direct language.

Weak	Better
Welcome to my collection of things.	Learn how to build Astro Starlight tutorial sites.
Here are some resources you might find interesting.	Start with beginner lessons, then move to components and deployment.
This site has information about many topics.	This site covers Markdown, MDX, content collections, customization, and deployment.

Homepage Accessibility Checklist

Use one clear page title.
Use headings in logical order.
Make link text descriptive.
Do not use “click here” as link text.
Add alt text to hero images.
Make sure card links are keyboard-accessible.
Keep paragraphs short.
Do not rely on color alone to communicate meaning.

Homepage SEO and Metadata

The homepage should have a clear title and description.

---
title: "Astro Starlight Tutorial Site"
description: "Learn Astro, Starlight, Markdown, MDX, content collections, customization, and deployment."
---

The description should explain the site in one sentence. This helps search, previews, and reader understanding.

Testing the Homepage

Run the development server:

npm run dev

Check:

The homepage loads at the expected URL.
The hero text is not too long.
Hero action buttons go to the right pages.
Homepage cards are readable in light and dark mode.
Internal links work.
The page is usable on a phone-sized screen.

Build and Preview

After editing the homepage, run:

npm run build
npm run preview

Use the preview command to check the built version, not just the development version. This helps catch path and asset problems before deployment.

Common Problems and Fixes

Problem: The homepage still looks like a normal docs page

Make sure the frontmatter includes:

template: splash

Problem: Hero buttons go to 404 pages

Check that the target pages exist and that the links use the correct route.

link: "/getting-started/"

Problem: Hero image does not load

Check the file path. If using ~/assets/, make sure the image is inside src/assets/.

Problem: Card grid looks unstyled

Make sure your custom CSS file exists and is registered in astro.config.mjs.

Problem: Homepage is too crowded

Move extra details to section landing pages. The homepage should guide, not contain everything.

Homepage Design Patterns

Beginner Tutorial Site

Hero
Start Here
Beginner / Intermediate / Advanced cards
Core Tools
Reference

World Bible Site

Hero
World Overview
Regions / Characters / Factions / Locations cards
Timeline
Storylines
Glossary

Software Docs Site

Hero
Install
Quick Start
Guides
API Reference
Troubleshooting

Mini Project: Build the Homepage

Open src/content/docs/index.md.
Add template: splash.
Add a hero block.
Add two or three hero actions.
Add a short “What This Site Teaches” section.
Add three homepage cards.
Add custom CSS for the card grid.
Run npm run dev.
Test all homepage links.
Run npm run build.

Cheat Sheet

Need	Use
Landing page layout	`template: splash`
Large intro area	`hero`
Main call-to-action buttons	`hero.actions`
Hero image	`hero.image`
Announcement	`banner`
Custom homepage styles	`customCss`
Main homepage file	`src/content/docs/index.md`

Simple Rule of Thumb

Use the homepage to guide.
Use the sidebar to navigate.
Use search to find.
Use section index pages to explain.
Use the splash template for landing pages.
Use normal doc pages for tutorials and references.

What to Learn Next

Starlight styling and theme customization.
Asset management for images, maps, and downloads.
Custom MDX components for homepage cards.
Content collection indexes for dynamic homepage sections.
Building a full lesson library homepage.
Building a world bible homepage.