How to Build and Deploy a Starlight Docs Site on PandaStack

Good documentation is a static site with search, a sidebar, and a dark mode toggle — and yet somehow it's easy to overcomplicate. Starlight (https://starlight.astro.build) is Astro's official documentation theme, and it gives you all of that out of the box: full-text search (via Pagefind), i18n, a responsive sidebar, code-block syntax highlighting, and excellent Core Web Vitals because it ships almost no JavaScript. It builds to a folder of static files, which is exactly what PandaStack's static hosting was made for.

This guide builds a Starlight site and deploys it with automatic SSL and deploy-on-push.

Why Starlight for docs

• Fast — Astro's island architecture means near-zero JS on doc pages; pages load instantly.
• Search included — Pagefind indexes your content at build time; no Algolia account needed.
• Markdown/MDX — write docs in plain Markdown, drop in components where you need interactivity.
• Static output — deploys to any static host, no server to run or scale.

If you want docs that pass Core Web Vitals without effort and don't require a running backend, this is a strong default.

Step 1: Scaffold the site

npm create astro@latest -- --template starlight my-docs
cd my-docs
npm install
npm run dev

The dev server runs at http://localhost:4321. You get a working docs site with example pages immediately.

Step 2: Configure your docs

Everything lives in astro.config.mjs:

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

export default defineConfig({
  site: 'https://docs.yourproject.com',
  integrations: [
    starlight({
      title: 'My Project Docs',
      social: {
        github: 'https://github.com/you/my-project',
      },
      sidebar: [
        { label: 'Start Here', items: [
          { label: 'Introduction', link: '/intro/' },
          { label: 'Installation', link: '/install/' },
        ]},
        { label: 'Guides', autogenerate: { directory: 'guides' } },
      ],
    }),
  ],
})

Setting site correctly matters — it's used for canonical URLs and the sitemap, both of which affect SEO.

Step 3: Write content

Docs are Markdown files under src/content/docs/. A page with frontmatter:

---
title: Installation
description: How to install My Project in under a minute.
---

Install the CLI:

\`\`\`bash
npm install -g my-project
\`\`\`

That's it. Run `my-project --help` to confirm.

The description becomes the meta description for that page — write it deliberately for search snippets. The folder structure maps directly to URLs.

Step 4: Build locally to verify

npm run build

Output lands in dist/. This is the folder PandaStack serves. Preview it exactly as it'll ship:

npm run preview

Confirm search works and no links 404 before deploying — cheaper to catch here than in production.

Step 5: Deploy to PandaStack static hosting

1. 1Push the repo to GitHub.
2. 2Dashboard (https://dashboard.pandastack.io) → New Deployment → Static Site.
3. 3Connect the repo.
4. 4Configure the build:

1. 1Deploy. Build + publish takes a couple of minutes.

Or via CLI:

npm install -g @pandastack/cli
panda login
panda deploy --type static --build-cmd "npm run build" --output dist

Every push to your default branch rebuilds and redeploys automatically — your docs update the moment you merge.

Step 6: Custom domain + SSL

Docs usually live at docs.yourproject.com:

1. 1Deployment → Domains → Add Domain → docs.yourproject.com.
2. 2Add the shown CNAME record at your DNS provider.
3. 3SSL is provisioned automatically via Let's Encrypt.

Update site in astro.config.mjs to the final domain so canonical URLs and the sitemap match, then redeploy.

Step 7: Make search work in production

Starlight's search is powered by Pagefind, which indexes during npm run build. Because PandaStack runs your build, the index is generated and served as static assets automatically — no configuration, no external service, no monthly search bill. Just make sure your build command is npm run build (not a dev command), or the index won't be produced.

Step 8: SEO niceties

• Every page's title and description frontmatter drive its meta tags — fill them in.
• Starlight generates a sitemap at build; submit https://docs.yourproject.com/sitemap-index.xml to Google Search Console.
• Because pages ship minimal JS, your Largest Contentful Paint and Cumulative Layout Shift are excellent by default — a real ranking advantage over heavy JS doc frameworks.

Troubleshooting

• Search box does nothing — you deployed a dev build, or the output directory is wrong. Rebuild with npm run build and serve dist.
• Broken relative links — set site correctly and use root-relative links (/guides/x/).
• 404 on refresh of a deep page — static SPA fallback isn't needed here; Starlight generates a real HTML file per route, so this usually means the output directory is misconfigured.

Wrap-up

Starlight gives you fast, searchable, good-looking docs with essentially no runtime, and PandaStack serves the static build with SSL and push-to-deploy. It's the least fussy way to ship documentation that also happens to score well on Core Web Vitals. Docs: https://docs.pandastack.io. Start free at https://dashboard.pandastack.io.