AI AI Tools Guidebook
AI Tool Tutorials

Use AI to Audit Astro Sites

Astro-specific audit prompts — sitemap, hreflang, output mode, RSS.

Published: Author: AI Productivity Guide Team 🌐 查看中文版本

Astro’s flexibility — three output modes, optional integrations, content collections, hybrid render — is also where most teams accumulate subtle SEO bugs. Sitemap missing a route, hreflang missing a locale, RSS pointing to a stale base URL — none of these surface until traffic starts dropping. This walks through framework-specific audit prompts that catch the Astro-shaped problems generic site audits miss.

What this covers

Astro-specific audit prompts that target the integration layer where most teams ship and forget: astro.config.mjs, src/pages/, sitemap output, hreflang alternates, output mode (static / SSR / hybrid), and RSS feeds. The audit is shaped around how Astro actually works — not generic “is your site good” advice.

Key tools and concepts:

  • Astro: A modern frontend framework optimized for content-heavy static and hybrid sites. Different output modes change the audit surface significantly.
  • Integrations: @astrojs/sitemap, @astrojs/rss, astro-i18n, and friends. Most audit findings live in how these are configured.

Who this is for

Indie devs and small teams running Astro content / marketing sites — especially bilingual sites where hreflang and route generation interact in non-obvious ways.

When to reach for it

Before or after a large content addition. After upgrading Astro major versions (config shape changes between 3.x / 4.x / 5.x). After adding or removing an integration. Anywhere production behavior diverges from your mental model. After the site-level pass, drill into the AI category-page audit tutorial — duplicate intros, weak internal linking, and broken pagination usually only surface when you audit category pages specifically.

Before you start

  • Have astro.config.mjs and src/pages/ accessible to the AI. The audit reads both.
  • Know your output mode (output: 'static' | 'server' | 'hybrid'). The right audit prompts differ by mode.
  • Have a list of locales (for bilingual sites). The hreflang audit needs to know what’s expected.

Step by step

  1. Feed astro.config.mjs plus a tree of src/pages/ (run find src/pages -type f) to the agent as context.
  2. Run the routing audit. Prompt:
Given astro.config and src/pages, list every route Astro
will generate at build. Flag any: dynamic [...slug] routes
without getStaticPaths, getStaticPaths returning empty,
routes whose file path conflicts with another, locale
prefixes missing or inconsistent.
  1. Run the sitemap audit:
Inspect @astrojs/sitemap config. List every URL the
generated sitemap will include. Cross-check against the
route list from the previous step. Flag any: routes in
sitemap but not generated, routes generated but excluded
from sitemap, alternates (hreflang) missing for bilingual
URLs, lastmod set incorrectly.
  1. Run the hreflang audit:
For each bilingual page pair, confirm: both pages exist,
each <link rel="alternate" hreflang="..."> in the head
of one points at the other, x-default is set, and no
self-referential hreflang is missing.
  1. Run the RSS audit if you have one:
Read @astrojs/rss usage. Confirm: site URL matches
production, items include pubDate, the feed is linked
in <head>, and the feed URL works in a reader.
  1. Triage findings: blocker (broken page or wrong canonical), warn (missing nice-to-have), info (style). Fix blockers first.
  2. After fixing, regenerate the site and re-run the audit. Sitemap-related fixes especially need a fresh build.

First-run exercise

  1. Run only the routing audit. Read every flagged route.
  2. For each “missing” route the audit names, verify by visiting the URL on a local dev server. The audit can be wrong; treat it as a hypothesis.
  3. Fix one true positive end-to-end (e.g., one missing locale alternate). Re-run the same audit only — confirm count dropped by exactly 1.
  4. Now add the next audit (sitemap). Layer one at a time so you can attribute findings.

Quality check

  • Does each finding cite a specific file or line? “Sitemap is wrong” is not actionable; “sitemap includes /en/foo but src/pages/en/foo.astro does not exist” is.
  • Are findings reproducible against a fresh npm run build? If the audit says “X is missing” but dist/X.html exists, the audit was reading stale source.
  • For bilingual claims, does the AI distinguish between “locale missing” and “locale exists but not linked”? Different fixes.

How to reuse this workflow

  • Save each prompt (routing, sitemap, hreflang, RSS) separately. You’ll re-run different subsets depending on what changed.
  • Wire up a small CI script that runs astro build and grep-checks the output against an expected route manifest. The AI audit becomes the “is the manifest still correct” question, not “what’s broken.”
  • Track findings over time. Recurring categories (always missing hreflang on new locales) reveal where to add tooling.

Astro config + pages → routing audit → sitemap audit → hreflang audit → RSS audit → fix list → apply → regenerate → re-audit. Once the Astro-specific layer is clean, pair the audit with a stack-tailored technical SEO checklist so you also catch render-mode, schema and monitoring gaps that go beyond Astro itself.

Common mistakes

  • Asking AI to “review the site” too vaguely — you get generic SEO advice unrelated to Astro specifics.
  • Auditing source files without rebuilding — sitemap and rendered HTML can drift from your source until you astro build again.
  • Trusting the route count without verifying with astro build --verbose — Astro output mode changes what gets generated.
  • Skipping the hreflang audit on bilingual sites — this is the #1 silent Astro SEO issue.
  • Only running the audit before launch — Astro upgrades and integration version bumps drift the config; quarterly re-runs catch it.
  • Treating warnings about getStaticPaths returning empty arrays as harmless — they’re broken routes that ship 404s.

FAQ

  • Static vs SSR vs hybrid — does the audit change?: Yes. SSR mode introduces request-time rendering bugs that static audits miss. Tell the AI your output mode up front.
  • What if my site uses astro-i18n instead of manual locales?: Same audit, different config path. The AI handles both if you give it the config file.
  • How does this relate to the content audit?: Content audit checks per-file frontmatter; site audit checks framework-level wiring. Run both. See the Astro content audit tutorial.
  • Can the AI generate the fix code?: Yes — ask “show me the minimum patch to fix finding N.” For config changes especially, the AI is fast and accurate.
  • Does this work on Starlight, Astro Studio, or other Astro-based templates?: Yes, with caveats. Templates may abstract the config; point the AI at the underlying astro.config.mjs if visible.

Tags: #AI coding #Tutorial

Related Articles