Starlight (Astro) docs monitoring

Starlight is the documentation theme for Astro. It renders fully static HTML from a content collection, generates sidebars from the folder structure when configured to, and inherits Astro's routing and redirect options.

How Starlight sites typically break

Autogenerated sidebars hide removals. With autogenerate sidebars TODO(verify): option name, moving a Markdown file to another folder changes both its URL and its sidebar position. Links from other pages and from outside keep pointing at the old path.

Heading slugs follow the heading text. Starlight generates ids for headings, and its table of contents links to them. Editing a heading breaks any #fragment link that targeted it. TODO(verify): whether custom ids via {#id} or a remark plugin are supported out of the box.

Content collection moves change URLs. Astro derives routes from file paths in the docs collection TODO(verify). Reorganising folders is a URL migration and needs redirects.

Localized sites duplicate every problem. With i18n enabled, each language has its own tree. A fix in the default language does not fix the translated copy.

External links rot and nothing in the default build re-checks them.

What the Astro build catches, and what it misses

• Astro fails the build for pages that fail to render and for invalid frontmatter in content collections.
• Starlight validates sidebar entries that point at missing pages TODO(verify).
• Link checking is not built in; community integrations can check internal links at build time TODO(verify): integration names.
• It misses: everything that happens after deploy: external links, redirect chains, anchors targeted from other sites, sitemap drift, orphans in autogenerated sidebars, soft 404s and duplicate titles across locales.

Setting up redirects on Starlight

Astro supports a redirects option in astro.config.mjs (verified 2026-09-17 against the Astro routing guide):

// astro.config.mjs
export default defineConfig({
  redirects: {
    '/docs/old-page': '/docs/new-page',
    '/guides/legacy': { status: 301, destination: '/guides/current' },
  },
});

For static output Astro writes HTML pages with a meta refresh and ignores the status code; with a supported adapter the rules are written to the host's configuration and become real HTTP redirects (default 301). The host-level files (vercel.json, Netlify or Cloudflare _redirects) in the redirect rules cheat sheet always produce HTTP 301s, which is what search engines prefer. The migration redirect checker writes any of those formats.

How PathIntact monitors a Starlight site

• Detection: the Astro generator meta tag together with Starlight's sl- class names and custom elements (verified 2026-09-17 against starlight.astro.build, confidence 0.8).
• Render mode: auto, effectively static: Starlight pages contain all content in the HTML.
• Sitemap: Astro's sitemap integration produces sitemap-index.xml and per-locale files TODO(verify): file names; PathIntact follows sitemap indexes and reports non-200 entries, noindex entries and drift.
• Locales: each locale is crawled under the same scope; hreflang alternates are recorded per page.
• Anchors and orphans: fragment links are checked against element ids on the rendered page; sitemap pages with no inbound links are reported as orphans.

Check my docs