Build a Manual with Starlight #1: From Install to Your First Doc

Framework Starlight Documentation Static Site
3 min read

When you start building documentation in earnest, you almost always run into the same problem: where to put documentation that a single README can no longer handle. Notion is cumbersome for public sharing and version control, and if you build it with a blogging tool, posts just line up chronologically, which is awkward to use as a reference. That is why many teams move toward treating docs like code, an approach known as Docs as Code. You write in Markdown, manage it with Git, and deploy it as a static site.

This series covers that first step, building a documentation site with a static site generator. The tool is Starlight. It is a documentation theme built on the modern web framework Astro, and its strength is that it ships almost no JS by default, so it is light and fast. Search and multilingual support come built in as well.

This series is Build a Manual with Starlight, in six parts.

  • #1 From Install to Your First Doc ← this post
  • #2 Sidebar and Search — Structuring Your Docs
  • #3 Writing Content — Code Blocks, Mermaid, asides
  • #4 Deploy to Cloudflare Pages and Connect a Domain
  • #5 Multilingual and Versioning
  • #6 Maintenance — Search, Accessibility, Docs Culture

In this post we will look at what Starlight requires as prerequisites, then create a new site and bring up our first doc on the dev server.

Prerequisite — Node.js #

Since Starlight is built on Astro, the prerequisite is Node.js version 18 or higher. After installing, check the version.

Check the version 
node --version

Like Docusaurus, it lives in the JavaScript ecosystem, but Astro applies JS only where it is needed, so the output is lighter.

Creating a New Site #

When you point Astro’s generator at the Starlight template, the skeleton of a documentation site is created in one shot.

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

It interactively asks for the folder name and whether to install dependencies, and when it finishes you have something you can start right away.

Bringing Up Your First Doc #

Enter the created folder and start the dev server.

Run the dev server 
cd my-docs
npm run dev

Open http://localhost:4321 in your browser and the default docs appear in the Starlight layout. Edit a file and the screen updates immediately.

Settings such as the site title are defined in the Starlight integration in astro.config.mjs.

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

export default defineConfig({
  integrations: [
    starlight({ title: 'Product Manual' }),
  ],
});

Understanding the Folder Structure #

In the generated structure, the places you need to know right away are the folder where docs go and the config file.

Folder structure 
my-docs/
├─ astro.config.mjs       # Astro + Starlight config
├─ src/
│  └─ content/
│     └─ docs/            # Doc body (you fill this in)
│        ├─ index.mdx     # First screen
│        └─ guides/example.md
├─ public/                # Static files such as images
└─ dist/                  # npm run build output (for deployment)

Growing your docs ultimately means adding Markdown files under src/content/docs. Starlight builds the sidebar automatically based on this folder structure, and you can also define it yourself if needed. We cover how in the next post.

Wrapping Up #

In this post we got Node.js ready, created a Starlight site with create astro, and brought up our first doc on the dev server. Starlight’s strengths are that it is Node-based yet produces light output, and that search is built in.

In the next post we cover the sidebar and search. This is the step where you design the information structure so that readers do not get lost even as the docs grow to dozens of pages.

X