DEV Community

Cover image for A Complete Guide to Build a Documentation Site with Astro Starlight
Waricha
Waricha

Posted on • Edited on

A Complete Guide to Build a Documentation Site with Astro Starlight

#webdev #beginners #tutorial #documentation

Learn how to build a sleek, user-friendly documentation site using the Astro Starlight

Have you ever felt frustrated trying to use a promising new tool, only to find it lacks clear instructions? Good documentation can be a lifesaver in these situations. While it may not be the first thing most users look for, it's often the hero they need when learning new software or facing challenges.

If you're a technical writer or developer looking for a tool to create clear, user-friendly documentation, Astro Starlight could be the right solution for you. This tutorial will guide you on how to build a documentation site using Astro Starlight, from a blank project to a fully functional site.

What we're building today:

bizarre binary dark light modes

View the final result on this demo site or access the full source code in this GitHub repository. (Disclaimer: This site contains AI-generated mock-up content. It is not intended to be accurate or academic.)

By the end of this guide, you will learn:

  • What Astro Starlight is and why it's a great choice
  • Steps to create your new Astro Starlight project
  • How to customize your documentation site's basic settings and theme
  • How to add documentation content
  • …plus, additional tips to improve your Astro Starlight project

Understanding Astro Starlight

Astro Starlight is a specialized theme for creating documentation websites. It's built on top of Astro, a modern web framework. It offers a set of features specifically designed for technical documentation while also benefiting from Astro's speed and performance.

Starlight documentation examples:

Visit the Astro Starlight showcase for more examples.

Why choose Astro Starlight?

Astro Starlight offers several benefits for documentation projects. Here are key reasons why Starlight is the perfect fit for your next project.

  • Ease of use: Starlight is easy to set up, organize content, and deploy a documentation site, offering a good development experience. Your readers can easily find and navigate content thanks to Starlight's intuitive, beautiful design.
  • Multiple content formats support: Starlight supports Markdown, Markdoc, and MDX, allowing you to choose the content format that suits your needs. This enables easy migration and integration of your existing content.
  • Highly customizable: You can adjust the look and feel to match your brand or project needs through the theme editor. Starlight is also compatible with various UI frameworks like React or Svelte.
  • Accessibility-focused: Accessibility is crucial when creating documentation. Luckily, Starlight offers many built-in accessibility features, such as navigation menus, search functionality (Pagefind), dark and light themes, and internationalization.

Prerequisites

Before we get started, make sure you have:

  • Node.js installed on your machine
  • Visual Studio Code or your preferred code editor
  • Basic knowledge of Markdown, CSS, and HTML
  • Git installed (optional but recommended for version control)
  • A GitHub or GitLab account (optional, but useful for deploying your site)

Setting Up Your Astro Starlight Project

The first section will guide you through creating a new Astro Starlight project and explain its essential directories and files.

Create a New Astro Starlight Project

1.Open your code editor and run the following command to create a new Astro project using the Starlight template:

//Using npm
npm create astro@latest -- --template starlight

// Using pnpm
pnpm create astro --template starlight

//Using Yarn
yarn create astro --template starlight
Enter fullscreen mode Exit fullscreen mode

2.Follow the project setup prompts:

a. "Need to install the following packages: create-astro@4.9.0. Ok to proceed? (y)"
Answer: y

b. "Where should we create your new project?"
Answer: Your preferred project name (We'll use "bizarre-binary" for this example.)

c. "Do you plan to write TypeScript?" (Optional)
Answer: Yes

d. "How strict should TypeScript be?" (Only if you chose TypeScript)
Answer: Strict

e. "Install dependencies?" (Recommend)
Answer: Yes

f. "Initialize a new git repository?" (Optional)
Answer: Yes (If you prefer to set up git manually or use a different version control system, you can choose "No" here.)
Enter fullscreen mode Exit fullscreen mode

3.Once the setup is complete, navigate into your new project directory:

cd ./bizarre-binary
Enter fullscreen mode Exit fullscreen mode

4.Start the development server with the following command.

npm run dev
Enter fullscreen mode Exit fullscreen mode

You can view the local preview at http://localhost:4321/ (or the provided URL). Your new Astro Starlight project is now set up and ready for development.

starlight starter theme

Project Structure Overview

Below is the project’s directory tree:

shaky-satellite/
├── .astro/
├── .git/
├── .vscode/
├── node_modules/
├── public/
│   └── favicon.svg
├── src/
│   ├── assets/
│   ├── content/
│   └── docs/
│       ├── guides/
│       │   └── example.md
│       └── reference/
│           └── example.md
├── .gitignore
├── astro.config.mjs
├── config.ts
├── env.d.ts
├── index.mdx
├── package-lock.json
├── package.json
├── README.md
└── tsconfig.json
Enter fullscreen mode Exit fullscreen mode

Key directories and files:

  • public/: Contains static assets to be served directly (e.g., favicon.svg, fonts, PDFs).
  • src/content/docs/: Contains documentation files (.md, .mdx, or .mdoc). Starlight automatically generates routes and serves this content on your website. For example, a file named example-page.md creates the route: https://your-website.com/example-page.
  • src/assets/: Stores images and other assets used in the documentation.
  • astro.config.mjs: Configures Astro and Starlight settings, such as the site title, social links, sidebar structure, and integrations.
  • src/content/config.ts: Defines content collections and adds Starlight’s frontmatter schemas to your documentation.

Customizing Your Astro Starlight Site

In this section, we’ll discuss the astro.config.mjs file to configure basic settings and customize appearance:

Site metadata

Configure site metadata for search engine results in astro.config.mjs.

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

// https://astro.build/config
export default defineConfig({
    integrations: [
        starlight({
            // Site title
            title: 'Bizarre Binary Docs',
            // Site description
            description: `Welcome to Bizarre Binary, your trusted companion for exploring the vast expanse of space.`,
        }),
    ],
});
Enter fullscreen mode Exit fullscreen mode
  • title (required): The website title header, also shown in the browser tab.
  • description: The website description in the <meta name="description"> tag.

You’ll see the title in the site header:

customization site title

Site logo

To add a logo to your site header:

  1. Place your logo image file in src/assets/. (I created a mock-up logo for this demo site.)
  2. In astro.config.mjs, add logo with your logo path.
  3. By default, the logo will appear next to the site title. If you want to replace the title with your logo, set replacesTitle to true. 
// ... existing code

starlight({
  // ... other Starlight configurations
  logo: {
    src: './src/assets/bizarre-binary-logo.png',
    replacesTitle: true, // Hide the site title
  },
});
Enter fullscreen mode Exit fullscreen mode

The site logo is added to the header:

customization site logo

Social links

Next, add social media accounts to the site header with social:

// ... existing code

starlight({
  // ... other Starlight configurations
  social: {
    github: 'https://github.com/warishco',
    linkedin: 'https://www.linkedin.com/in/warish',
    'x.com': 'https://x.com/warishwrites',
  },
});
Enter fullscreen mode Exit fullscreen mode

customization social links

Our side header is now looking good! Let's move to sidebar customization.

Sidebar navigation

Starlight offers various sidebar customization options. In this tutorial, I created a site structure diagram below:

bizarre binary site structure

This demo site will have a simple layout: two main sections, each with three internal links and two external links. I’ll customize the sidebar following this site structure.

Autogenerated sidebar group

The easiest way to create a sidebar is to let Starlight do it automatically. With an autogenerated sidebar group, Starlight creates a sidebar based on the folders and files in src/content/docs/. New content added to the directory appears in the sidebar, labeled with the document title.

// ... existing code

starlight({
  // ... other Starlight configurations
  sidebar: [
    // Autogenerated group
    {
      // Link group title
      label: 'Getting Started',
      // Directory of an autogenerate a group of links
      autogenerate: { directory: 'getting-started' },
    },
  ],
});
Enter fullscreen mode Exit fullscreen mode
  • label: Title of the sidebar group
  • autogenerate: Directory to include in the sidebar

Internal link group

For manually organized links, you can create an internal link group for more control over the order and hierarchy of your sidebar items.

// ... existing code

starlight({
  // ... other Starlight configurations
  sidebar: [
    // ... exiting autogenerated group
    // Internal link group
    {
        label: 'Cosmic Navigation', // Link group title
        items: [
            // Each item here is one entry in the navigation menu.
            { slug: 'cosmic-navigation/reading-star-charts-and-maps' },
            { label: 'Plotting a Course Through Space', slug: 'cosmic-navigation/plotting-course-through-space' },
            'cosmic-navigation/dealing-with-gravity-and-orbit', // shorthand for an internal link
        ],
    },
  ],
});
Enter fullscreen mode Exit fullscreen mode
  • label: Title of the sidebar group
  • items: Array of sidebar links, including subgroups
  • slug: Reference to an internal page (shorthand allowed). You can specifically add label for each link if you want it to differ from the page title.

External link

You can add links to external websites or pages outside your documentation site.

// ... existing code

starlight({
  // ... other Starlight configurations
  sidebar: [
    // ... exiting autogenerated group
    // ... exiting internal link group
    // External links
    { label: 'Spaceships and Rockets', link: 'https://www.nasa.gov/humans-in-space/spaceships-and-rockets/' }, // An external link to the NASA website.
    { label: 'Space Movie', link: 'https://en.wikipedia.org/wiki/Interstellar_(film)' },
  ],
});
Enter fullscreen mode Exit fullscreen mode
  • label: Link title
  • link: Path to other pages outside your documentation or an external page URL

Here’s what our sidebar looks like:

customization sidebar

Table of contents

Starlight features a table of contents (TOC) on each page for easy navigation. By default, Starlight displays a TOC panel on the right side of each page, automatically including all <h2> and <h3> headings.

You can customize which heading levels appear in the TOC.

// ... existing code

starlight({
  // ... other Starlight configurations
  tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 2 },
});
Enter fullscreen mode Exit fullscreen mode
  • minHeadingLevel: The highest heading level to include
  • maxHeadingLevel: The lowest heading level to include

For this demo documentation, we'll modify the TOC to display only <h2> headings. See the outcome below:

customization toc

Custom CSS styles

You can customize your documentation site by adding CSS files.

  1. Create a styles folder in src/.
  2. Create a style.css file and add it to the folder.
  3. As an example, I’ll add the following CSS to style.css to change the h1 font family to monospace: 
/* Change the font family of h1 headings */
h1 {
    font-family: monospace;
}
Enter fullscreen mode Exit fullscreen mode
  1. Tell Starlight to use your custom CSS by adding customCss to astro.config.mjs: 
// ... existing code

starlight({
  // ... other Starlight configurations
  customCss: [
        // Path to your custom CSS file
        './src/styles/style.css',
  ],
});
Enter fullscreen mode Exit fullscreen mode

Color theme

Here’s how to customize your site’s color scheme for light and dark modes.

  1. Visit the Color theme editor in Starlight documentation.
  2. Use the color sliders to customize your theme. The preview panel shows how your changes affect dark and light modes in real time, and the entire page updates accordingly.

starlight color theme editor

  1. When you are satisfied, copy the generated CSS code and paste it into your style.css file. 
/* Dark mode colors. */
:root {
    --sl-color-accent-low: #36113e;
    --sl-color-accent: #a400c0;
    --sl-color-accent-high: #e3b6ed;
    --sl-color-white: #ffffff;
    --sl-color-gray-1: #f2e9fd;
    --sl-color-gray-2: #c7bdd5;
    --sl-color-gray-3: #9581ae;
    --sl-color-gray-4: #614e78;
    --sl-color-gray-5: #412e55;
    --sl-color-gray-6: #2f1c42;
    --sl-color-black: #1c1425;
}
/* Light mode colors. */
:root[data-theme='light'] {
    --sl-color-accent-low: #ebc9f3;
    --sl-color-accent: #a700c3;
    --sl-color-accent-high: #4e0e5b;
    --sl-color-white: #1c1425;
    --sl-color-gray-1: #2f1c42;
    --sl-color-gray-2: #412e55;
    --sl-color-gray-3: #614e78;
    --sl-color-gray-4: #9581ae;
    --sl-color-gray-5: #c7bdd5;
    --sl-color-gray-6: #f2e9fd;
    --sl-color-gray-7: #f8f4fe;
    --sl-color-black: #ffffff;
}
Enter fullscreen mode Exit fullscreen mode

Refresh the site to see the new color scheme in action.

customization color theme

Adding Documentation Content

Now that you've customized your site's settings and appearance, it's time to focus on the heart of your documentation: the content.

Create and organize pages

Adding new pages to your Astro Starlight documentation site is straightforward. Simply create a new .md or .mdx file in src/content/docs/ for each page.

To keep your documentation well-organized, create folders within src/content/docs/ to group related pages. Make sure to use a logical hierarchy that reflects your content structure.

Customize frontmatter

Frontmatter is a section at the beginning of a documentation page between --- separators. It contains metadata and key information about the content. Frontmatter also controls the sidebar and table of contents display. For a complete list of options, see Frontmatter Reference in Starlight documentation.

Here’s an example of frontmatter:

---
title: Setting Up Your Spacecraft
description: Learn how to set up your spacecraft for space exploration.
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 3
draft: true # Exclude this page from production builds
---
Enter fullscreen mode Exit fullscreen mode
  • title (required): The page title appears at the top of the page, in browser tabs, and as metadata.
  • description : Used for page metadata, search engines, and social media previews.
  • template: The page layout style, including 'doc' by default and 'splash' for a wider layout without the sidebar.
  • draft: Hide from production. If true, a page is only visible during development.

Modify the homepage

Documentation’s homepage is located at src/content/docs/index.md. This page uses template: splash and has a hero component at the top. Let’s break down the homepage customization into two main parts:

1. Hero section

The hero section appears at the top of your homepage. You can customize its components within hero to create a welcoming introduction to your documentation site.

---
title: Homepage
description: Bizarre Binary is your trusted companion for exploring the vast expanse of space.
template: splash
hero:
  title: Bizarre Binary Docs
  tagline: Welcome to Bizarre Binary, your trusted companion for exploring the vast expanse of space. This documentation site is dedicated to helping you master the art of space exploration.
  image:
    alt: Bizarre Binary Logo
    file: ../../assets/bizarre-binary-hero.png
  actions:
    - text: Getting Started
      link: /getting-started/intro-to-space-exploration/
      icon: right-arrow
    - text: Read the Starlight docs
      link: https://starlight.astro.build
      icon: external
      variant: minimal
---
Enter fullscreen mode Exit fullscreen mode
  • title: The main heading of your hero section
  • tagline: A brief description below the title
  • image: The hero image configuration
  • actions: Call-to-action buttons guiding users to important pages

2. Feature Cards

This section is where you guide visitors to key areas of your documentation using the CardGrid (the grid layout) and Card components.

// ...existing code

import { Card, CardGrid } from '@astrojs/starlight/components';

## Next steps

<CardGrid stagger>
    <Card title="Launch into Orbit" icon="rocket">
        Learn the basics of spacecraft operations → [Introduction to Space Exploration](/getting-started/intro-to-space-exploration/)
    </Card>
    <Card title="Chart Your Course" icon="open-book">
        Plot your journey through the galaxy with our comprehensive guide → [Plotting a Course Through Space](/cosmic-navigation/plotting-course-through-space/)
    </Card>
    <Card title="Setting Up Your Spacecraft" icon="setting">
        Get your spacecraft ready for launch → [Setting Up Your Spacecraft](/getting-started/setting-up-your-spacecraft/)
    </Card>
    <Card title="Master Gravity and Orbit" icon="star">
        Understand the forces that shape your journey → [Mastering Gravity and Orbit](/cosmic-navigation/dealing-with-gravity-and-orbit/)
    </Card>
</CardGrid>
Enter fullscreen mode Exit fullscreen mode

The <Card> component includes these properties:

customized homepage

Add page content

Starlight supports full Markdown syntax for content creation. Let’s add content to example.md.

Basic Markdown syntax

Here are essential Markdown elements you'll frequently use in the documentation:

---
title: Markdown Guide
description: How to use Markdown in Starlight
---

This page displays basic and documentation-specific Markdown syntax in Starlight.

## Headings

Text can be **bold**, _italic_, or ~~strikethrough~~.

> Blockquotes for highlighting important quotes or references
Enter fullscreen mode Exit fullscreen mode

Documentation-specific elements

You can include additional syntax specifically useful for documentation. For example:

  • Asides (Admonitions/Callouts): Perfect for highlighting important information, including note, tip, caution, or danger. Simply use a pair of triple colons ::: to wrap your content. 
:::tip[Pro Tip]
Use keyboard shortcuts to navigate faster:
- `Ctrl + F`: Find in page
- `Ctrl + B`: Toggle sidebar
:::

:::caution
Remember to backup your configuration files before making changes.
:::

:::note
This feature is available in version 2.0 and above.
:::
Enter fullscreen mode Exit fullscreen mode
  • Code blocks: Ideal for explaining code examples, indicated by a block with three backticks ` at the start and end. Starlight uses Expressive Code to extend formatting possibilities, for example, line highlighting ({ }) and file name tab with a comment.

`
`js {3-4}
// my-test-file.js
function demo() {
// This line (#3) and the next one are highlighted
return 'This is line #4 of this snippet';
}
`
`

Below is what example.md looks like:

add md content

Deploying Your Documentation Site

Astro supports deployment to multiple popular hosting platforms like Netlify, Vercel, and Cloudflare Pages.

astro deployment guides

You can quickly deploy your website by connecting your Astro project's Git repository (GitHub, GitLab, or Bitbucket) to a hosting provider. For detailed instructions, read this full guide: How to deploy Astro sites to Cloudflare Pages.

Conclusion: Taking Your Documentation Further

Clear documentation solves problems. It helps end users find the information they need, smooths the development process, and connects developers with users. Astro Starlight checks all the boxes to build a documentation website. It’s packed with useful features, easy to use, and scalable.

In this tutorial, you've learned how to set up an Astro Starlight project, customize its appearance and settings, create pages, and add content. Keep in mind that documentation is not a one-time task. It needs iterative improvements. Here are ways to improve your Astro Starlight project:

  • Add multiple languages. Make your site accessible to a broader audience. Starlight offers a built-in Internationalization (i18n) feature for creating a multilingual documentation site.
  • Improve search functionality: Integrate advanced search tools like Algolia DocSearch.
  • Extend functionality: Add features like a Starlight blog for announcements and updates.

Now it’s your turn to share your completed Astro Starlight projects! Follow this blog for more content about web development and Astro tutorials.

Top comments (0)

Read next

harold_defree profile image

Month 1: The Kickoff – Building the Foundation

Harold Defree -

cp_nandani profile image

Building a Better Monorepo with TypeScript, Turborepo, or Nx

Nandani Sharma -

witcher_1001 profile image

🌐 SSH Tunneling: Securely Connect to Remote Networks Like a Pro

The Witcher -

terieyenike profile image

Building a Console-Based Calculator in C#

teri -