Build a Manual with Starlight #4: Deploy to Cloudflare Pages and Connect a Domain

Framework Starlight Documentation Static Site
3 min read

By the time you reach #3, you have docs that look good locally. But only you can see localhost. In this post we send these docs out so that anyone can reach them by address.

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

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

In this post we cover pushing to GitHub, connecting Cloudflare Pages and setting up the build, and attaching a custom domain.

Pushing to GitHub #

So that build output and dependencies do not end up in the repository, start with .gitignore. Astro’s build output is the dist folder.

.gitignore 
dist/
node_modules/
.astro/

Then initialize the repository and push.

Push to GitHub 
git init
git add .
git commit -m "docs: first docs"
git branch -M main
git remote add origin https://github.com/your-account/my-docs.git
git push -u origin main

Connecting Cloudflare Pages #

In the Cloudflare dashboard, go to Workers & Pages → Create → Pages → Connect to Git and select the repository. Astro is a Node project, so the build settings are simple.

ItemValue
Framework presetAstro
Build commandnpm run build
Build output directorydist
Environment variableNODE_VERSION = 20

It is safer to match the Node version to your local one. Press Save and Deploy and the first deploy starts; when it finishes you get a project-name.pages.dev address. From then on, it rebuilds automatically every time you push to main. The search index we saw in #2 is also created during this build step.

Connecting a Custom Domain #

Instead of the pages.dev address, attach a domain you bought yourself. In the Pages project, enter the domain under Custom domains → Set up a domain. If you manage DNS elsewhere, add the following record yourself.

DNS record (subdomain) 
Type    Name     Value
CNAME   docs     project-name.pages.dev

Once the connection is done, Cloudflare automatically issues and renews the HTTPS certificate. When using a custom domain, also set the site value in astro.config.mjs to that address. This is so that search and the sitemap use the correct absolute address.

Wrapping Up #

In this post we pushed the docs to GitHub, connected Cloudflare Pages and set up the Astro build, and attached a custom domain. Now the docs have a real address and are live on the internet.

In the next post we cover multilingual and versioning. We will go over serving one doc in multiple languages, and how to keep old docs around as product versions move up.

X