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,siteand repository link inastro.config.mjsand one stub page. Set those, then add your own pages underwebsite/src/content/docs/.website:build— builds the site and verifies every page actually rendered.pages— publishes the already-built site onmain.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.
Go deeper: why the build is two jobs
Section titled “Go deeper: why the build is two jobs”Build the site as an Astro Starlight content collection in CI and publish it to GitLab Pages. Use two jobs, deliberately split:
website:buildrunsastro buildand then verifies the output, publishingdist/as an artifact.pagespublishes that artifact. GitLab requires the job be namedpageswith output inpublic/. 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_modulesstill 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.
Internal links, anchors, and assets — checked for you already
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.
Keep a link and an anchor in your docs
Section titled “Keep a link and an anchor in your docs”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.
Saying which version a page describes
Section titled “Saying which version a page describes”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 custom domain
Section titled “A custom domain”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.
Versioned docs
Section titled “Versioned docs”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-versionsplugin 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 onv*tags and onmain. Anext/path for unreleased docs is a convention you add on top, not something the plugin gives you. - MkDocs Material:
mikebuilds each version into its own directory on agh-pagesbranch and maintains the version switcher. Push from CI onmain(asnext) 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
pagesand leave the site inpublic/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 setspages: true, and letpages.publishname a directory other thanpublic/. See GitLab Pages. mikewrites to agh-pagesbranch, not topublic/. Thepagesjob turns that branch intopublic/, for example:git fetch origin gh-pages, thenmkdir public && git archive origin/gh-pages | tar -x -C public, thenartifacts: paths: [public]. The job that runsmike deployis a separate job, onmainand on tags, that pushes togh-pages.- Protect
gh-pagesunder 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.ymlandscripts/check-docs-internal-links.pyread Starlight’s source layout and config, and reportscanner matched nothingon an MkDocs tree. Delete that job andmake check-docs-links, or replace them with MkDocs’ own check:mkdocs build --strictfails on a broken internal link or a missing nav page. - Replace the
website:buildjob with one that runsmkdocs build --strict.
A separate marketing site
Section titled “A separate marketing site”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 atdocs.<product>.comfrom GitLab Pages. Nothing ties the two to the same host. - Preview, then staging, then a manual production deploy. Every branch gets a preview
URL.
maindeploys 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).