How to keep Astro Starlight docs accurate after a green build
"My Starlight build is green. How do I know the docs are still right?" A green build tells you the site is well-formed: frontmatter matches its schema, internal links resolve once you add a validator, and API pages render from your spec. It cannot tell you whether a sentence in a how-to is still true, which takes a content check driven by what changed in the product.
Take one change: your product renames a component prop. The frontmatter schema passes, the links validate, the starlight-openapi pages regenerate from the updated spec, and the English how-to still shows the old prop. Every translation of that page now repeats the mistake.
TL;DR
- Starlight's schema, link, and OpenAPI checks prove the site is well-formed; none reads a how-to against the product.
- Translations inherit English errors, and Git-based tracking can flag them once the English page is fixed.
- A content check driven by product pull requests closes the gap, with Starlight unchanged.
!Diagram: what a green Starlight build proves, a stack of checks for frontmatter schema, internal links, OpenAPI pages and translation tracking, topped by the open question of whether each sentence is still true, which EkLine checks against product changes
What Starlight and its plugins already check
Starlight pages live in an Astro content collection, and Astro validates them. In the words of the content collections guide, "Schemas enforce consistent frontmatter or entry data within a collection through Zod validation," and "If any file violates its collection schema, Astro will provide a helpful error to let you know." Starlight's docsSchema() helper takes an extend option that can make built-in fields required or add fields of your own, so a page missing something you care about surfaces as an error.
Link checking came from the community. In June 2023, Starlight issue #247 asked for "basic tooling to ensure the integrity of internal links," and the thread pointed to starlight-links-validator, an MIT-licensed plugin by HiDeoo. Its getting started page describes "A Starlight plugin to validate internal links in Markdown and MDX files," and the check runs during a production build.
The API reference can come from the spec. starlight-openapi, also by HiDeoo under MIT, is a "Starlight plugin to generate documentation from OpenAPI/Swagger specifications," so endpoint pages follow the spec your engineers maintain.
Translations have two tools. Starlight's i18n guide handles missing pages: when a translation does not exist yet, readers get the default-language page with the notice "This content is not available in your language yet." Tracking stale translations belongs to a separate project, Lunaria, which describes "a custom tracking system that keeps track of your source and localized content changes powered by Git." Lunaria's May 2024 launch post lists Astro and Starlight among the projects using it to track translations.
Where the renamed prop slips through
Try this on your docs. Pick the most recent merged pull request that renamed a prop or changed what a component does. Did anything flag the how-to that shows it? Run the rename past each check:
| Native check | What it verifies | What it does not see | Where EkLine fits |
| --- | --- | --- | --- |
| Collection schema | Frontmatter against its Zod schema | The page body, where the old prop sits | Automatic PR review reads the product pull request |
| starlight-links-validator | Internal links in Markdown and MDX, in production builds | A how-to whose links resolve and whose example is out of date | Docs Agent opens an MDX edit in your docs repository |
| starlight-openapi | Endpoint pages generated from the spec | Hand-written how-tos around those pages | Docs Agent drafts their fixes, and Docs Reviewer checks their writing with the astro framework value |
| Lunaria | Which translations predate a change to the English source | An English page that is wrong and unchanged | A merged English fix gives Lunaria a change to track |
The i18n guide describes no outdated-translation check, and once a translated page exists, the fallback notice has no reason to appear, so translated readers see the old prop with no warning. Until someone notices the English error, nothing in the stack flags it.
A checklist you can run this week without EkLine
- Extend docsSchema() with an owner or last-reviewed field, so every page names who answers for it and when someone last checked it.
- Add starlight-links-validator to the production build your CI already runs, and confirm in your own pipeline how a broken link is reported.
- Generate the API reference with starlight-openapi from the spec your engineers ship, and stop hand-editing endpoint pages.
- Track translations with Git-based tooling such as Lunaria, so a change to an English source page can show up against each locale.
- After each release, reread your most-visited how-to pages against what shipped, starting with pages that show code.
Is a same-PR docs rule enough for a small team?
For most small teams it is: when the engineer who renames the prop also edits the how-to in the same pull request, the docs stay right without new tooling. Practitioners on Ask HN describe docs-first and docs-in-the-PR habits: "Update the documentation first ... Followed by the code changes," and "every AI-heavy PR still needs a human owner, reproducible tests, and docs explaining the behavior change." Starlight's authoring guide describes no built-in AI writer, so a second layer here would not overlap with a platform agent.
Draw the line here. The same-PR rule and Starlight's checks are enough when the product and the docs share a repository and every fact the how-to needs is in that pull request. They fall short once those facts sit in a ticket, a Slack thread, a spec, or a repository the docs team does not watch, or when each how-to has translations to keep in step.
How EkLine fits a Starlight repository
| Question | On a Starlight site |
| --- | --- |
| Where your content lives | src/content/docs in a GitHub or GitLab repository. |
| What EkLine watches | Your code repositories. The GitHub App lists Code Repositories separately from Documentation Repositories, so the product and the docs can live in different repositories. |
| When it reads a change | Automatic PR review assesses each pull request once, when it opens or leaves draft, from the diff, title, and description. GitLab merge requests get the same review, per the May 2026 changelog. A scheduled Docs Drift Review sweeps what merged. |
| Where its pull request lands | Your docs repository, as an edit to the MDX that your team reviews and merges. |
| Which CI check runs | Docs Reviewer, which checks each docs change for style, consistency, links, and accuracy, set to the astro framework value in its config or CLI. |
| What stays in Starlight | Your Astro build and preview, plugins, schema, and translation workflow. |
Take the prop rename again. When it opens as a pull request in the product repository, automatic PR review assesses it. At high confidence, Docs Agent opens a docs pull request that edits the English how-to; at medium, it leaves a suggestion comment; at low, it stays silent. That assessment uses the pull request alone: "Linked Jira or Linear tickets are not included." If the rename merged before you connected EkLine or scored below the threshold, the Drift Review catches it, using a default prompt that starts "Audit the last 30 days of GitHub activity for customer-facing changes that lack documentation." The framework page says "Mintlify currently has the most comprehensive component support" and "Support for other frameworks is expanding," so test your custom components. If the old prop also appears in samples across other pages, the Code Sample Review agent in Scheduled Agents "Verifies that code samples in your docs are accurate and runnable." Docs Agent "is available to all plans, but we grant access on request."
Worried about volume once every product change gets a docs check? At Socure, "One technical writer merged 348 documentation updates in seven weeks" using EkLine, "with no added headcount." The case study does not name Socure's docs platform.
Moving to Starlight, or starting fresh
If you are moving to Starlight from another framework, the path that puts the least accuracy work at risk keeps your docs as Markdown and MDX in Git, so the pull request loop you run today works on the new site too. EkLine maintains Potluck Docs, an open-source Astro + Starlight template under the MIT license, for that kind of start. It ships "Three example OpenAPI references, rendered by Scalar with a built-in client for sending real requests," private docs for signed-in readers and org-scoped docs for each org's members, and a sitemap and llms.txt "generated on every build." By its own description, it is "a template, not a hosted product." Use it to start a site or as a reference; EkLine does not require it.
FAQ
Does EkLine replace your docs platform?
No. Starlight keeps building, previewing, and serving your site, and your schema, plugins, and translation workflow stay where they are. EkLine adds a content layer on top: Docs Agent proposes MDX edits as pull requests when a product change makes a page wrong, and Docs Reviewer checks those pages in CI with its astro framework value.
Does Starlight check for broken links?
Starlight's answer to the 2023 request for link checking, issue #247, was a community plugin: starlight-links-validator by HiDeoo. It validates internal links in Markdown and MDX files during a production build. External URLs are outside its stated scope, and its pages do not say outright that a broken link fails the build, so confirm the behavior in your own CI before you treat it as a gate.
Can't we script this ourselves?
To a point. In the Ask HN thread, cyanydeez described "a for loop that runs nightly on any files updated the prior day," with local AI revising the Markdown next to each one. A Starlight how-to lives in src/content/docs, apart from the component it documents, and each translation adds pages to pair. Each rewrite also needs a reviewer, the gap rstagi named: "it's hard to fact-check everything all the time." EkLine reads the product pull request and proposes the English edit for review.
Open one product pull request from your last release and bring it along. To see what Docs Agent would flag in your Starlight repository after your next release, book a demo with EkLine.
Mentions
The @astrodotbuild LLM factory works great. Found a bug, clanker wrote a simple repro + short description, I then (manually) filed a ticket. Their bot wrote a fix in ~20 mins. Few days later, after @matthewcp approved the changes, fix was merged in ~3 h. astro#18507
Building a blog shouldn't feel like building a whole app. 🌐 Astro is designed for content-focused sites, with Markdown and UI framework support. Great for portfolios and docs. 🚀 withastro/astro #WebDev #浇朋友 #蓝朋友 #互关 #fo
搭博客还要先搞一整套复杂前端？🌐 Astro 适合内容型网站，支持 Markdown 和多种前端组件。建作品集或文档站可以试试。🚀 withastro/astro #WebDev #浇朋友 #蓝朋友 #互关 #fo
only tangentially related, but a few weeks back I was trying to build an astro site as an SEA roadmap#1442 yeah maybe astro is overkill for my use-case (digital signage kiosk app), but having a single binary would be useful in a variety of cases, same as with CLI apps
roadmap#1450 Composition: so hot right now
Proposal to Break Up Astro! Matt is drafting a proposal to break Astro into composable Vite plugins. This could get interesting. 👀 roadmap#1450 Short version: right now Astro is like a set meal. You get the whole combo whether you want every item or not. This proposal would let you order a la carte instead. But it only got accepted yesterday as an idea (Stage 2, no RFC, no code yet), so you can’t use any of it today.
Happy spooky season @astro.build It wasn't immediately obvious to me why Houston had a bone... github.com/withastro/astro/blob/c75e89711a4935a0b… At least now I know it's a tie 💀
週刊プログラミングニュース｜Deno・Python・OSSと開発ツール【2026-W42／10月9〜15日】 週刊プログラミングニュース｜2026年10月9日〜15日 | 2026-W42 最初にDeno、Python、Bun、GitHub Actions、.NET、シークレット保護。その後、OSS・フレームワーク、ライブラリー・データベース、IDE・開発プラットフォームを章ごとに整理します。 対象期間：10月9日00:00〜15日23:59 JST。時刻を確認できた発表はJSTへ換算し、日付のみの資料は公式表記日を採用しています。境界時刻が未確認の候補は確定分と区別しました。 正式版、プレビュー、今後の予定を区別しています。Dockerは修正済み問題の開示、Nodeの10月21日予定分は未提供の修正予告です。 映像は公式情報に基づく解説図で、実機デモではありません。性能値は発表元の測定で、独自の実測ではありません。 日本語音声・日英字幕。 チャプター 00:00 週刊プログラミングニュース 00:28 DenoチームがCloudflareへ 01:50 Python 3.15が正式公開 03:18 Bun 1.4.3に型チェッカー 04:30 Actionsにワークフローロック 05:38 .NETは安定版更新とRC2 07:00 GitHubのシークレット検出拡大 07:59 Next.jsのセキュリティ更新 09:28 Express・Fastify・Micronaut 10:57 フロントエンドの安定版とRC 12:16 Astro・Rolldown・Laravel 13:21 Hydrogenがライブラリーへ 14:14 Pydantic・NumPy・FastAPI 15:59 PgBouncerとpsqlODBC 17:25 SQLite 3.54.0 18:38 Ruby 4.1のプレビュー 19:39 Node.js更新と次のセキュリティ修正 20:51 VS CodeとVisual Studio 22:07 Cursor Originのアプリ連携 22:54 GitLabの緊急修正 23:57 Docker Hubの修正済み問題の開示 25:04 Lambdaの新しい実行モデルと接続維持 26:27 今週の確認リスト 公式出典 deno.com blog.python.org bun.com github.blog devblogs.microsoft.com github.blog devblogs.microsoft.com github.com/dotnet/core/blob/main/release-notes/10… nextjs.org github.com/expressjs/express/releases/tag/v5.3.0 github.com/fastify/fastify/releases github.com/fastify/fastify/security/advisories/GH… micronaut.io micronaut.io github.com/angular/angular/releases/tag/v22.2.3 github.com/vuejs/core/releases github.com/vuejs/core/blob/main/CHANGELOG.md github.com/vuejs/core/blob/minor/CHANGELOG.md github.com/nuxt/nuxt/releases/tag/v4.6.1 github.com/sveltejs/kit/releases/tag/@sveltejs%2F… github.com/withastro/astro/releases/tag/astro@7.4… github.com/rolldown/rolldown/releases/tag/v1.2.14 github.com/laravel/framework/releases/tag/v13.36.0 github.com/laravel/framework/releases shopify.dev github.com/pydantic/pydantic/releases/tag/v2.14.0 pydantic.dev github.com/pydantic/pydantic/releases github.com/numpy/numpy/releases/tag/v2.5.4 github.com/fastapi/fastapi/releases/tag/0.143.1 github.com/fastapi/fastapi/releases/tag/0.143.2 pgbouncer.org github.com/pgbouncer/pgbouncer/releases/tag/pgbou… postgresql.org sqlite.org ruby-lang.org nodejs.org nodejs.org nodejs.org openwall.com code.visualstudio.com learn.microsoft.com cursor.com docs.gitlab.com docker.com aws.amazon.com developers.cloudflare.com
How to keep Astro Starlight docs accurate after a green build "My Starlight build is green. How do I know the docs are still right?" A green build tells you the site is well-formed: frontmatter matches its schema, internal links resolve once you add a validator, and API pages render from your spec. It cannot tell you whether a sentence in a how-to is still true, which takes a content check driven by what changed in the product. Take one change: your product renames a component prop. The frontmatter schema passes, the links validate, the starlight-openapi pages regenerate from the updated spec, and the English how-to still shows the old prop. Every translation of that page now repeats the mistake. TL;DR - Starlight's schema, link, and OpenAPI checks prove the site is well-formed; none reads a how-to against the product. - Translations inherit English errors, and Git-based tracking can flag them once the English page is fixed. - A content check driven by product pull requests closes the gap, with Starlight unchanged. !Diagram: what a green Starlight build proves, a stack of checks for frontmatter schema, internal links, OpenAPI pages and translation tracking, topped by the open question of whether each sentence is still true, which EkLine checks against product changes What Starlight and its plugins already check Starlight pages live in an Astro content collection, and Astro validates them. In the words of the content collections guide, "Schemas enforce consistent frontmatter or entry data within a collection through Zod validation," and "If any file violates its collection schema, Astro will provide a helpful error to let you know." Starlight's docsSchema() helper takes an extend option that can make built-in fields required or add fields of your own, so a page missing something you care about surfaces as an error. Link checking came from the community. In June 2023, Starlight issue #247 asked for "basic tooling to ensure the integrity of internal links," and the thread pointed to starlight-links-validator, an MIT-licensed plugin by HiDeoo. Its getting started page describes "A Starlight plugin to validate internal links in Markdown and MDX files," and the check runs during a production build. The API reference can come from the spec. starlight-openapi, also by HiDeoo under MIT, is a "Starlight plugin to generate documentation from OpenAPI/Swagger specifications," so endpoint pages follow the spec your engineers maintain. Translations have two tools. Starlight's i18n guide handles missing pages: when a translation does not exist yet, readers get the default-language page with the notice "This content is not available in your language yet." Tracking stale translations belongs to a separate project, Lunaria, which describes "a custom tracking system that keeps track of your source and localized content changes powered by Git." Lunaria's May 2024 launch post lists Astro and Starlight among the projects using it to track translations. Where the renamed prop slips through Try this on your docs. Pick the most recent merged pull request that renamed a prop or changed what a component does. Did anything flag the how-to that shows it? Run the rename past each check: | Native check | What it verifies | What it does not see | Where EkLine fits | | --- | --- | --- | --- | | Collection schema | Frontmatter against its Zod schema | The page body, where the old prop sits | Automatic PR review reads the product pull request | | starlight-links-validator | Internal links in Markdown and MDX, in production builds | A how-to whose links resolve and whose example is out of date | Docs Agent opens an MDX edit in your docs repository | | starlight-openapi | Endpoint pages generated from the spec | Hand-written how-tos around those pages | Docs Agent drafts their fixes, and Docs Reviewer checks their writing with the astro framework value | | Lunaria | Which translations predate a change to the English source | An English page that is wrong and unchanged | A merged English fix gives Lunaria a change to track | The i18n guide describes no outdated-translation check, and once a translated page exists, the fallback notice has no reason to appear, so translated readers see the old prop with no warning. Until someone notices the English error, nothing in the stack flags it. A checklist you can run this week without EkLine - Extend docsSchema() with an owner or last-reviewed field, so every page names who answers for it and when someone last checked it. - Add starlight-links-validator to the production build your CI already runs, and confirm in your own pipeline how a broken link is reported. - Generate the API reference with starlight-openapi from the spec your engineers ship, and stop hand-editing endpoint pages. - Track translations with Git-based tooling such as Lunaria, so a change to an English source page can show up against each locale. - After each release, reread your most-visited how-to pages against what shipped, starting with pages that show code. Is a same-PR docs rule enough for a small team? For most small teams it is: when the engineer who renames the prop also edits the how-to in the same pull request, the docs stay right without new tooling. Practitioners on Ask HN describe docs-first and docs-in-the-PR habits: "Update the documentation first ... Followed by the code changes," and "every AI-heavy PR still needs a human owner, reproducible tests, and docs explaining the behavior change." Starlight's authoring guide describes no built-in AI writer, so a second layer here would not overlap with a platform agent. Draw the line here. The same-PR rule and Starlight's checks are enough when the product and the docs share a repository and every fact the how-to needs is in that pull request. They fall short once those facts sit in a ticket, a Slack thread, a spec, or a repository the docs team does not watch, or when each how-to has translations to keep in step. How EkLine fits a Starlight repository | Question | On a Starlight site | | --- | --- | | Where your content lives | src/content/docs in a GitHub or GitLab repository. | | What EkLine watches | Your code repositories. The GitHub App lists Code Repositories separately from Documentation Repositories, so the product and the docs can live in different repositories. | | When it reads a change | Automatic PR review assesses each pull request once, when it opens or leaves draft, from the diff, title, and description. GitLab merge requests get the same review, per the May 2026 changelog. A scheduled Docs Drift Review sweeps what merged. | | Where its pull request lands | Your docs repository, as an edit to the MDX that your team reviews and merges. | | Which CI check runs | Docs Reviewer, which checks each docs change for style, consistency, links, and accuracy, set to the astro framework value in its config or CLI. | | What stays in Starlight | Your Astro build and preview, plugins, schema, and translation workflow. | Take the prop rename again. When it opens as a pull request in the product repository, automatic PR review assesses it. At high confidence, Docs Agent opens a docs pull request that edits the English how-to; at medium, it leaves a suggestion comment; at low, it stays silent. That assessment uses the pull request alone: "Linked Jira or Linear tickets are not included." If the rename merged before you connected EkLine or scored below the threshold, the Drift Review catches it, using a default prompt that starts "Audit the last 30 days of GitHub activity for customer-facing changes that lack documentation." The framework page says "Mintlify currently has the most comprehensive component support" and "Support for other frameworks is expanding," so test your custom components. If the old prop also appears in samples across other pages, the Code Sample Review agent in Scheduled Agents "Verifies that code samples in your docs are accurate and runnable." Docs Agent "is available to all plans, but we grant access on request." Worried about volume once every product change gets a docs check? At Socure, "One technical writer merged 348 documentation updates in seven weeks" using EkLine, "with no added headcount." The case study does not name Socure's docs platform. Moving to Starlight, or starting fresh If you are moving to Starlight from another framework, the path that puts the least accuracy work at risk keeps your docs as Markdown and MDX in Git, so the pull request loop you run today works on the new site too. EkLine maintains Potluck Docs, an open-source Astro + Starlight template under the MIT license, for that kind of start. It ships "Three example OpenAPI references, rendered by Scalar with a built-in client for sending real requests," private docs for signed-in readers and org-scoped docs for each org's members, and a sitemap and llms.txt "generated on every build." By its own description, it is "a template, not a hosted product." Use it to start a site or as a reference; EkLine does not require it. FAQ Does EkLine replace your docs platform? No. Starlight keeps building, previewing, and serving your site, and your schema, plugins, and translation workflow stay where they are. EkLine adds a content layer on top: Docs Agent proposes MDX edits as pull requests when a product change makes a page wrong, and Docs Reviewer checks those pages in CI with its astro framework value. Does Starlight check for broken links? Starlight's answer to the 2023 request for link checking, issue #247, was a community plugin: starlight-links-validator by HiDeoo. It validates internal links in Markdown and MDX files during a production build. External URLs are outside its stated scope, and its pages do not say outright that a broken link fails the build, so confirm the behavior in your own CI before you treat it as a gate. Can't we script this ourselves? To a point. In the Ask HN thread, cyanydeez described "a for loop that runs nightly on any files updated the prior day," with local AI revising the Markdown next to each one. A Starlight how-to lives in src/content/docs, apart from the component it documents, and each translation adds pages to pair. Each rewrite also needs a reviewer, the gap rstagi named: "it's hard to fact-check everything all the time." EkLine reads the product pull request and proposes the English edit for review. Open one product pull request from your last release and bring it along. To see what Docs Agent would flag in your Starlight repository after your next release, book a demo with EkLine.
Flue (withastro/flue) is an open-source TypeScript framework for building autonomous AI agents, created by the Astro team. github.com It is a harness framework (not just another LLM SDK). You write agents as ordinary TypeScript functions using a React-style hooks API (useModel, useSandbox, useTool, useSkill, usePersistentState, etc.). The framework supplies the surrounding runtime: sessions, durable state, tools, skills, filesystem access, and a secure sandbox so the model can actually do real work (edit files, run commands, call APIs, etc.) instead of just chatting. flueframework.com Dev is onboard and redirecting fees to his GitHub