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:
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
- 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
- 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.)
- Once the setup is complete, navigate into your new project directory:
cd ./bizarre-binary
- Start the development server with the following command.
npm run dev
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.
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
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.`,
}),
],
});
-
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:
Site logo
To add a logo to your site header:
- Place your logo image file in
src/assets/
. (I created a mock-up logo for this demo site.) - In
astro.config.mjs
, addlogo
with your logo path. - By default, the logo will appear next to the site title. If you want to replace the title with your logo, set
replacesTitle
totrue
.
// ... existing code
starlight({
// ... other Starlight configurations
logo: {
src: './src/assets/bizarre-binary-logo.png',
replacesTitle: true, // Hide the site title
},
});
The site logo is added to the header:
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',
},
});
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:
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' },
},
],
});
-
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
],
},
],
});
-
label
: Title of the sidebar group -
items
: Array of sidebar links, including subgroups -
slug
: Reference to an internal page (shorthand allowed). You can specifically addlabel
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)' },
],
});
-
label
: Link title -
link
: Path to other pages outside your documentation or an external page URL
Here’s what our sidebar looks like:
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 },
});
-
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:
Custom CSS styles
You can customize your documentation site by adding CSS files.
- Create a
styles
folder insrc/
. - Create a
style.css
file and add it to the folder. - 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;
}
- Tell Starlight to use your custom CSS by adding
customCss
toastro.config.mjs
:
// ... existing code
starlight({
// ... other Starlight configurations
customCss: [
// Path to your custom CSS file
'./src/styles/style.css',
],
});
Color theme
Here’s how to customize your site’s color scheme for light and dark modes.
- Visit the Color theme editor in Starlight documentation.
- 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.
- 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;
}
Refresh the site to see the new color scheme in action.
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
---
-
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. Iftrue
, 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
---
-
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>
The <Card>
component includes these properties:
-
title
: The card's heading -
icon
: Add an icon from Starlight's built-in icon set - Card content can include text and Markdown links.
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
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
, ordanger
. 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.
:::
-
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:
Deploying Your Documentation Site
Astro supports deployment to multiple popular hosting platforms like Netlify, Vercel, and Cloudflare Pages.
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)