Build a Documentation Site with Starlight and Deploy It

If you want documentation that looks great out of the box, loads instantly, and lives in the same modern toolchain as the rest of your frontend, Starlight is a strong choice. It's the official documentation framework from the Astro team — full-featured, fast, and static by default. This guide covers building a docs site with Starlight and deploying it to your own server with DeployHQ.

What is Starlight?

Starlight is a documentation theme and toolkit built on Astro, the content-focused web framework. You get site search, dark mode, i18n, sidebar navigation, and accessible, responsive styling with almost no configuration — write your docs in Markdown or MDX and Starlight handles the rest. Because it's built on Astro, it ships as a fully static site: fast to load, cheap to host, and simple to deploy.

If you're already familiar with Astro, Starlight will feel immediately at home — it's a set of Astro components and an integration rather than a separate tool. Our Astro deployment guide covers the underlying framework in more depth.

Creating a Starlight project

Scaffold a new site with the official template:

npm create astro@latest -- --template starlight

Answer the prompts, then start the dev server:

cd my-docs
npm run dev

Your docs are live at http://localhost:4321 with hot reload.

Adding content

Documentation pages live in src/content/docs/ as Markdown or MDX files. Starlight builds the sidebar and routing from your configuration in astro.config.mjs:

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Project Docs',
      sidebar: [
        { label: 'Start Here', items: [{ label: 'Introduction', link: '/intro/' }] },
        { label: 'Guides', autogenerate: { directory: 'guides' } },
      ],
    }),
  ],
});

Drop a Markdown file into src/content/docs/intro.md and it's a page.

Building the static site

When you're ready to publish, build it:

npm run build

Astro compiles everything into a static dist/ directory — that folder is your entire documentation site. As with any static site, dist/ is the artifact you deploy.

Deploying Starlight with DeployHQ

Because Starlight builds to static files, deployment is a clean build-then-ship flow. Add a build pipeline that installs dependencies and builds the site:

npm ci
npm run build

Then point your deployment at the generated dist/ directory so only the compiled site ships — not your source files or node_modules. Enable automatic deployments so every push to your docs branch rebuilds and republishes, keeping your documentation current with each release.

The build runs on Node, so set your Node version in your build configuration to match local development — the same version you'd pin with a Node.js version manager like fnm or Volta.

Choosing a documentation generator

Starlight is the natural pick when you're in the Astro or broader JavaScript ecosystem and want a polished docs site with minimal setup. If your stack leans Python, the MkDocs guide covers the leading Markdown-and-YAML option; for a React-based generator, see the Docusaurus deployment guide. They differ in ecosystem, but the deployment shape is identical: build a static site, ship the output directory.

Ready to publish your docs to your own server? Create a free DeployHQ account and connect your repository in minutes.