Skip to content

Your docs site — Astro Starlight on GitLab Pages

The big picture: Blueprint’s own docs (this site) are an Astro Starlight site built in CI and published to GitLab Pages. The reset deletes website/ from a new clone, so your Pages never publish Blueprint’s docs. Run bash scripts/customize.sh --init --keep-website (or --reset-template --keep-website) to keep a stub of the setup as the starting point for your own docs.

Why it matters: A green docs build doesn’t prove the docs rendered. This page covers the checks that make it trustworthy.

What --keep-website leaves you:

  • website/ — the site source, with a placeholder title, site and repository link in astro.config.mjs and one stub page. Set those, then add your own pages under website/src/content/docs/.
  • website:build — builds the site and verifies every page actually rendered.
  • pages — publishes the already-built site on main.
  • ci/docs.yml — checks every internal link, anchor, and image.

Don’t want a docs site? Do nothing: the default reset removes website/, and the website:build and pages jobs skip themselves when it is gone.

Build the site as an Astro Starlight content collection in CI and publish it to GitLab Pages. Use two jobs, deliberately split:

  • website:build runs astro build and then verifies the output, publishing dist/ as an artifact.
  • pages publishes that artifact. GitLab requires the job be named pages with output in public/. It does not rebuild — the site is already built once per pipeline, and a second build paid for a full re-render plus a multi-gigabyte image pull to reproduce bytes that already existed.

astro build exits 0 with a page’s entire body missing

Section titled “astro build exits 0 with a page’s entire body missing”

This is the single most important thing to know about the docs pipeline. A green build is not proof the docs rendered. Starlight’s content loader catches a per-page render error, logs it, drops that page’s whole body, emits the index.html anyway, and the build still succeeds. Upstream (TruePPM, one of the projects Blueprint came from, using this same pattern), three pages shipped as bare navigation chrome — 99 characters of body where eleven sections should have been — for 19 days of green pipelines.

So website:build should run a post-build check that asserts the rendered output actually contains what it should and that the build log carries no error lines. That check, not the exit code, is the verification.

If your site renders diagrams or other content through a headless browser at build time, two consequences are worth copying:

  • Pin the browser version in every place it appears, exactly — no carets — and add a gate that asserts the pins agree. A package only ever looks in the path matching its own revision, so a mismatch is a hard “executable doesn’t exist”, not a soft degrade.
  • A local build does not reproduce it. A stale node_modules still holds the working version; only CI’s clean install honors the drifted lockfile. Astro’s content cache means even a deliberate repro needs the cache cleared first.
Section titled “Internal links, anchors, and assets — checked for you already”

Unlike website:build / pages above, you don’t need to add this one: ci/docs.yml is included by default and scripts/check-docs-internal-links.py runs against website/src/content/docs (and make check-docs-links runs the same check before a push) the moment website/astro.config.mjs exists — which is to say, the moment you’ve added a docs site in this recommended shape. Nothing to wire up.

It reads the Markdown source (not the built HTML, for the same reason the build-output check above exists — a broken route or a renamed heading id has nothing to do with whether astro build exits 0) and fails the job on a link to a page that doesn’t publish, a #anchor that doesn’t match a heading, a relative image that isn’t tracked in the repository, or a -/blob/main/… link into a file this repository doesn’t have. See the script’s own module docstring for what it checks, what it cannot see (anything a component renders at runtime), and which of its assumptions are configurable via --docs-root / --config / --site / --repo-source if your docs site doesn’t use this recommended shape.

The kept stub holds one page. scripts/check-docs-internal-links.py refuses to pass a site where it found no internal link or no heading anchor (“scanner matched nothing”), so keep at least one of each in your docs. The stub carries a link back to its own #start-here heading for that reason; a real docs site has plenty of both.

A docs page can describe an entirely unreleased feature in plain present tense, never mention a version, and read to someone on the current release as a description of their install. Tense rules cannot catch that — nothing can check “did the author choose the right tense”.

The workable answer is to make the author declare it: a front-matter key naming the version the page documents, paired with a visible callout, both checked against the roadmap. The check runs in both directions — a missing callout fails, and so does a “ships in 0.X” banner on a page whose version has since shipped. That reverse direction is the one a release actually produces.

Pages that declare nothing are covered by a content hash baseline: editing one breaks its hash and fails the gate until you either declare a version or re-baseline. Be honest about what that buys — re-baselining is one command and a rubber stamp gets today’s outcome. What it removes is the silence: before it, adding four paragraphs of unreleased behavior produced no signal anywhere in the pipeline.

This particular gate is worth the ceremony for a versioned product with a roadmap of shipped/underway/planned features. Blueprint’s own docs site doesn’t need it — a template repository doesn’t have “features that haven’t shipped yet” in the same sense — so it isn’t wired in here. Add it if your project does have that shape.

A docs site usually lives at docs.<product>.com, which keeps the marketing site on the apex domain and the docs on a subdomain you can move independently. The steps (registering the domain in GitLab, the CNAME and TXT DNS records, the certificate, Force HTTPS, and which base to set for each address) are in Publishing to GitLab Pages. Once the domain is live, set site in website/astro.config.mjs to https://docs.<product>.com.

A product that ships releases needs docs per release. A shape that works: next/ tracks main, and a tagged release freezes a snapshot. TruePPM and Visiban, two of the projects Blueprint came from, each do a version of this.

  • Starlight: the starlight-versions plugin keeps a snapshot of the docs per version next to the live pages, and serves the current docs at the site root with older versions under their own paths (read the plugin’s documentation for the exact layout and the config it needs). Publish on v* tags and on main. A next/ path for unreleased docs is a convention you add on top, not something the plugin gives you.
  • MkDocs Material: mike builds each version into its own directory on a gh-pages branch and maintains the version switcher. Push from CI on main (as next) and on tags (as the version number).

Decide the version policy before the first release. Retrofitting snapshots onto a site whose links were never versioned breaks every existing deep link.

MkDocs Material and mike as an alternative

Section titled “MkDocs Material and mike as an alternative”

Starlight is the default here. If you prefer MkDocs Material with mike:

  • Name the job that publishes the site pages and leave the site in public/ as an artifact; on older GitLab versions that is the only thing that publishes. Newer versions (17.9 and later, per GitLab’s Pages documentation: check it for your version) also publish a job that sets pages: true, and let pages.publish name a directory other than public/. See GitLab Pages.
  • mike writes to a gh-pages branch, not to public/. The pages job turns that branch into public/, for example: git fetch origin gh-pages, then mkdir public && git archive origin/gh-pages | tar -x -C public, then artifacts: paths: [public]. The job that runs mike deploy is a separate job, on main and on tags, that pushes to gh-pages.
  • Protect gh-pages under Settings > Repository > Protected branches. Do not set Allowed to push and merge to “No one”: that blocks the CI job too. Set it to the one identity CI pushes as: on the Free tier the protection can only name roles, so use a deploy key with write access (project access tokens are not available on GitLab.com Free; check your tier), and on higher tiers a named user or deploy key. Turn force push off.
  • The Starlight link checker does not apply. ci/docs.yml and scripts/check-docs-internal-links.py read Starlight’s source layout and config, and report scanner matched nothing on an MkDocs tree. Delete that job and make check-docs-links, or replace them with MkDocs’ own check: mkdocs build --strict fails on a broken internal link or a missing nav page.
  • Replace the website:build job with one that runs mkdocs build --strict.

Docs and a marketing site have different audiences, release rhythms and owners. Keep them apart:

  • A separate repository. Keep the marketing site in a separate, private repository, not in website/. Docs change with every feature MR; marketing copy changes on a business schedule and needs different reviewers.
  • A different host and domain. For example an Astro site on Cloudflare (Workers static assets or Pages) at the apex (<product>.com), with the docs at docs.<product>.com from GitLab Pages. Nothing ties the two to the same host.
  • Preview, then staging, then a manual production deploy. Every branch gets a preview URL. main deploys to staging automatically. Production is a manually gated job, so someone looks at the staging site before customers do.

This repository does not template the marketing site itself. Treat it as a second project that starts from its own /kickoff. It does ship one opt-in file for it, ci/cloudflare-deploy.yml, a fully commented-out deploy template to copy into that repository. The walkthrough, from buying the domain to a gated production deploy, is Marketing site on Cloudflare (free plan).