AEO for Gatsby
Check how each Gatsby route is rendered and rebuilt. Static generation is the default. Deferred, server and client rendering can change what a published route returns.
Default robots.txt behavior
Supply crawler rules through a static/robots.txt file or a configured plugin. Gatsby copies files in static/ to the output root. The official gatsby-plugin-sitemap generates a sitemap in production builds. Its default path is /sitemap-index.xml. Make the sitemap reference in robots.txt match the actual output.
Decide whether to permit search and user-fetch crawlers separately from training crawlers, within the controls your platform provides. See how AEOprobe distinguishes crawler roles.
Default structured data
Gatsby’s built-in Head API is available from version 4.19. It can render JSON-LD script tags from a named Head export in a page or page template. You do not need to install a package called gatsby-head. If it helps, share an SEO component and render it from the page’s Head with that page’s data.
Common AEO issues
| Issue | Impact | Fix |
|---|---|---|
| robots.txt references the wrong sitemap path | ImpactThe referenced sitemap does not match the deployed file. | FixCompare the robots.txt reference with the production output. The sitemap plugin’s default path is /sitemap-index.xml. |
| Published content has not reached the built site | ImpactThe visible page and its JSON-LD can retain old content. | FixFor statically generated pages, trigger your hosting build pipeline when content changes. Then inspect the deployment. |
| A client-only route omits initial content | ImpactThe initial response may lack the intended page text. | FixReview the route’s rendering choice and check its deployed HTML. Not every Gatsby page is fully pre-built. |
Plugins and modules
- gatsby-plugin-sitemap(opens in a new tab)
The official sitemap plugin. Configure public URLs and check its production output path.
Step-by-step guide
- 1
Identify how the route is rendered
Find out whether the page uses static generation, deferred static generation, server rendering or client rendering. Gatsby supports more than one approach. Inspect the initial HTML of the public route you care about.
- 2
Align crawler files with production output
If you use a static file, add static/robots.txt. Configure gatsby-plugin-sitemap with the site’s public URLs. Make the sitemap reference in robots.txt match the generated path. The development server does not emit the sitemap.
- 3
Render JSON-LD through the page’s Head
Export Head from the page or page template. Render an application/ld+json script from its content data. If you share an SEO component, pass page-specific facts into it. Do not repeat one schema object on every page.
- 4
Publish changed content through the correct pipeline
Set up a rebuild for static pages whenever content is published or edited. Check the deployed page, its JSON-LD and the production sitemap. Deferred generation does not replace updating the content a build uses.
Official documentation
- Gatsby rendering options(opens in a new tab)
Static, deferred, server and client rendering boundaries.
- Gatsby Head API(opens in a new tab)
Named page exports and JSON-LD scripts.
- Gatsby static folder(opens in a new tab)
Copying root files into the built site.
- Gatsby sitemap plugin documentation(opens in a new tab)
Production-only generation and the default sitemap-index.xml path.
Questions
Is every Gatsby route generated at build time?
No. Static generation is the default. Gatsby also supports deferred static generation, server rendering and client rendering. Check the configuration of the route you are reviewing.
Why is the sitemap missing in development?
gatsby-plugin-sitemap generates its files during production builds. Inspect the deployed output. Look for the default sitemap-index.xml path or the alternative you configured.
The free audit checks up to 3 public pages with no sign-up. Structured data checks read JSON-LD only. Microdata and RDFa are not parsed. Findings do not guarantee rankings or AI citations.
A saved-site audit costs 20 credits. It covers up to 10 pages on Free, 50 on Watch and 100 on Pro. AEOprobe plans are Free at €0/month, Watch at €7/month and Pro at €21/month. Your account shows what you can buy.
Run the free audit on your site