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](https://www.deployhq.com/guides/astro) covers the underlying framework in more depth.

## Creating a Starlight project

Scaffold a new site with the official template:

```bash
npm create astro@latest -- --template starlight
```

Answer the prompts, then start the dev server:

```bash
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`:

```js
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:

```bash
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](https://www.deployhq.com/features/build-pipelines) that installs dependencies and builds the site:

```bash
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](https://www.deployhq.com/features/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](https://www.deployhq.com/guides/node-version-managers).

## 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](https://www.deployhq.com/guides/mkdocs) covers the leading Markdown-and-YAML option; for a React-based generator, see the [Docusaurus deployment guide](https://www.deployhq.com/guides/deploy-docusaurus). 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](https://www.deployhq.com/signup) and connect your repository in minutes.