Does Astro-AEO work with my existing Astro setup?

Yes. It runs after @astrojs/mdx and @astrojs/react render your pages, complements @astrojs/sitemap, and skips redirect stubs. Whatever produces HTML gets a markdown copy.

Does it need external services or API keys?

No. Everything is generated locally during astro build. There are no external calls and no runtime dependencies.

What is the difference between llms.txt and llms-full.txt?

llms.txt is a structured index of your site with a link to each page's markdown. llms-full.txt concatenates every page's markdown into a single file for full-context ingestion.

Will it overwrite a robots.txt I already have?

No. It warns before replacing a robots.txt you ship in public/, and it adds Sitemap and llms.txt directives to the policy it generates.

Which Node and Astro versions are required?

Node 20 or newer and Astro 5 or newer. Astro-AEO is MIT licensed.

NPM Package

Your Astro site,
ready for every AI search.

One integration hooks into astro build and generates everything AI systems need to discover, parse, and cite your content: clean markdown copies, llms.txt, structured JSON-LD, crawler policies, and domain identity. Zero config, no external services.

View on npm GitHub

npx astro add astro-aeo

npm GitHub README Setup prompt

What AI reads, before and after.

No AI crawler except Google renders JavaScript, so most systems see your raw HTML. A typical page is 85-95% markup. The .md copy keeps the meaning and drops the noise.

index.html (what most bots see)

<!doctype html>
<html lang="en">
  <head>
    <script src="/_astro/client.9f2a.js"></script>
    <link rel="stylesheet" href="/_astro/index.4c1b.css" />
  </head>
  <body>
    <nav class="site-header"><!-- 40 nav links --></nav>
    <div class="layout-grid">
      <main>
        <h1>Launching v2.0</h1>
        <p>Our biggest release yet.</p>
      </main>
    </div>
    <footer class="site-footer"><!-- ... --></footer>
    <script src="/_astro/analytics.7d3e.js"></script>
  </body>
</html>

about.md (what Astro-AEO ships)

# Launching v2.0

Our biggest release yet.

Clean markdown is 20-30% fewer tokens than HTML. A site-wide llms-full.txt reaches 90%+ token reduction overall.

One build, every AI artifact.

Run astro build and Astro-AEO writes these alongside your static site. Real files, real formats, committed to your repo.

output of astro build

dist/
├─ index.html
├─ about/index.html
├─ about.md              ← clean markdown copy
├─ blog/launching-v2.md
├─ llms.txt              ← site index
├─ llms-full.txt         ← full concatenation
├─ robots.txt            ← search allow / training block
└─ .well-known/
   └─ domain-profile.json

docs/Url-Map.md          ← committable page map

about.md per page

A clean markdown copy of every HTML page, nav and scripts stripped.

# Launching v2.0

Our biggest release yet.
The full post, as clean markdown...

llms.txt site index

A structured index of your whole site, per the llmstxt.org spec.

# My Website

> A website about building great products

## Pages

- [About](/about.md): Our company and mission
- [Pricing](/pricing.md): Plans for every tier

## Blog Posts

- [Launching v2.0](/blog/launching-v2.md): Our biggest release yet

llms-full.txt full corpus

Every page's markdown concatenated into one file for full-context reads.

# My Website

## /about.md
# About
Our company and mission...

## /pricing.md
# Pricing
Plans for every tier...

robots.txt bot policy

Allows search and retrieval bots, blocks training bots.

User-agent: OAI-SearchBot     # allow search
Allow: /

User-agent: GPTBot            # block training
Disallow: /

Sitemap: https://yoursite.com/sitemap-index.xml
# llms.txt: https://yoursite.com/llms.txt

.well-known/domain-profile.json identity

Authoritative site identity, per the AI Domain Data spec.

{
  "name": "My Website",
  "url": "https://yoursite.com",
  "description": "A website about building great products",
  "sameAs": ["https://github.com/you"]
}

docs/Url-Map.md audit

A committable table of every page: URL, markdown path, title, date.

| URL | Markdown | Title | Last modified |
|---|---|---|---|
| /about/ | /about.md | About | 2026-07-06 |
| /pricing/ | /pricing.md | Pricing | 2026-07-01 |

How it works

Astro-AEO hooks into the standard Astro integration lifecycle. No separate build step, no post-processing scripts, no external services.

1
Astro renders

Every route is rendered to static HTML during astro build, after your other integrations run.
2
HTML is collected

At the astro:build:done hook, Astro-AEO reads each HTML page exactly once.
3
Markdown is extracted

Turndown strips nav, footers, scripts, and styles, leaving clean structured markdown.
4
Artifacts fan out

One pass writes the .md copy, llms.txt, robots.txt, domain profile, and URL map.
5
Output is validated

npx astro-aeo validate confirms every artifact exists and is well formed.

Nine features, one install.

Four are on by default, one ships as importable components, three are opt-in, and one is a CLI you run whenever you like.

Generate .md files

A clean .md companion for every page: content preserved, nav, scripts, and styles removed. Title, description, and date can be prepended as frontmatter.
Inject link tags

Adds <link rel="alternate" type="text/markdown"> to every page so AI crawlers discover the machine-readable copy without knowing your URL scheme.
Generate llms.txt

A structured /llms.txt index plus a concatenated /llms-full.txt, following the llmstxt.org spec. Sections are configurable by glob, RegExp, or predicate.
Generate JSON-LD

Importable schema.org components from astro-aeo/components: FAQPage, HowTo, BreadcrumbList, Organization, Speakable, and Article.
Generate robots.txt

One policy that allows search and retrieval bots, blocks training bots, and adds Sitemap and llms.txt directives. Warns before replacing a robots.txt you already ship.
Generate domain profile

Publishes /.well-known/domain-profile.json for authoritative site identity, per the AI Domain Data spec. Auto-populated from your config.
Generate URL map

A committable docs/Url-Map.md table of every page, with URLs, markdown paths, titles, and last-modified dates, for use as a content audit.
Preview in dev

astro dev serves llms.txt, robots.txt, and every .md companion live. See what AI crawlers will read while you edit, with no build step.
Validate output

npx astro-aeo validate checks llms.txt, markdown links, alternate tags, and the domain profile. Use --strict to fail on warnings and --json for CI.

Six JSON-LD components

Import from astro-aeo/components and drop into any layout. Each renders a single, XSS-safe script tag; BreadcrumbList builds itself from the URL.

Component	Marks up	Use it on
BreadcrumbList	Site hierarchy, derived from the URL	Most pages, no props needed
Organization	Brand identity	The homepage
FAQPage	Question and answer pairs	FAQ, docs, support
HowTo	Step-by-step instructions	Tutorials and guides
Speakable	Voice-readable sections	Assistant-friendly pages
Article	Headline, author, and dates	Blog posts and news

src/layouts/Base.astro

---
import { FaqJsonLd, BreadcrumbJsonLd } from 'astro-aeo/components';
---
<FaqJsonLd items={faqs} />
<BreadcrumbJsonLd />

Allow the search bots, block the trainers.

The generated robots.txt lets your content appear in AI answers while keeping it out of training datasets. You get the citation benefit without feeding the models.

Allowed: search and retrieval

OAI-SearchBot
ChatGPT-User
Claude-SearchBot
Claude-User
PerplexityBot
Googlebot
Bingbot
Applebot-Extended

Blocked: model training

GPTBot
ClaudeBot
Google-Extended
Applebot
Meta-ExternalAgent
Amazonbot

robots.txt

User-agent: OAI-SearchBot     # allow search
Allow: /

User-agent: GPTBot            # block training
Disallow: /

Sitemap: https://yoursite.com/sitemap-index.xml
# llms.txt: https://yoursite.com/llms.txt

The AI crawler landscape

Company	Search / retrieval bot	Training bot	Notes
OpenAI	OAI-SearchBot, ChatGPT-User	GPTBot	ChatGPT-User no longer respects robots.txt
Anthropic	Claude-SearchBot, Claude-User	ClaudeBot	Respects robots.txt and Crawl-delay
Perplexity	PerplexityBot, Perplexity-User	None	Perplexity-User ignores robots.txt
Google	Googlebot	Google-Extended	The only platform that renders JavaScript
Microsoft	Bingbot	None	Powers a large share of ChatGPT citations
Apple	Applebot-Extended	Applebot	Apple Intelligence
Meta	None	Meta-ExternalAgent	Training only
Amazon	None	Amazonbot	Training and Alexa

Quick start, under five minutes.

Three steps to an AI-readable site. Follow the setup prompt to hand the whole thing to your coding agent.

1 Install

Wire the integration automatically, or add it by hand with bun add astro-aeo.
terminal
npx astro add astro-aeo
2 Build

Check dist/ for a .md companion per page, plus llms.txt and llms-full.txt at the root.
terminal
astro build
3 Validate

Confirm the output is complete and well formed. Add --strict for CI.
terminal
npx astro-aeo validate

Built for every AI platform.

Cited domains overlap little across platforms, so a shared technical foundation (clean markdown, llms.txt, domain profile, robots.txt) is the highest-leverage investment: it works everywhere at once.

Platform	Leans on	Notable source
ChatGPT	Referring domains, domain traffic	Wikipedia and the Bing index
Perplexity	Recency, semantic relevance	Reddit and its own index
Claude	Brand authority, content quality	Brave Search
Google AI Overviews	Schema markup, E-E-A-T	Google Search

What the research says

The GEO study (Generative Engine Optimization, Princeton, Georgia Tech, Allen AI, and IIT Delhi; ACM SIGKDD 2024) tested nine optimization methods. Citing sources, adding quotations, and adding statistics each lifted visibility 30-40%. Keyword stuffing did not help.

Astro-AEO makes your content technically accessible. These principles make it worth citing once it is.

Answer first: Lead each section with a direct, concise answer. AI systems extract the opening of a relevant section most often.
Fact density: Include concrete statistics, data points, and cited sources. This is the highest-impact content change GEO found.
Clear hierarchy: Use H2 and H3 headings as semantic boundaries and keep sections focused, the shape retrieval prefers.
Tables and lists: AI systems reliably extract structured tabular data and numbered steps, so lead with them where you can.
Content freshness: Refresh on a regular cadence. Astro-AEO writes last-modified dates into the URL map automatically.
Neutral tone: Encyclopedic, authoritative prose surfaces in AI answers more often than opinion-heavy writing.

Built with

TypeScript
Astro
Turndown
Schema.org JSON-LD

Designed to coexist

Astro-AEO works alongside the integrations you already use. Your sitemap URL lands in the generated robots.txt automatically, it runs after @astrojs/mdx and @astrojs/react render your pages, and it skips redirect stubs. Install them together and they cooperate with nothing to configure.

Node 20 or newer. Astro 5 or newer. MIT licensed. Built and maintained by ZAAI.

Questions worth asking.

Does Astro-AEO work with my existing Astro setup?: Yes. It runs after @astrojs/mdx and @astrojs/react render your pages, complements @astrojs/sitemap, and skips redirect stubs. Whatever produces HTML gets a markdown copy.
Does it need external services or API keys?: No. Everything is generated locally during astro build. There are no external calls and no runtime dependencies.
What is the difference between llms.txt and llms-full.txt?: llms.txt is a structured index of your site with a link to each page's markdown. llms-full.txt concatenates every page's markdown into a single file for full-context ingestion.
Will it overwrite a robots.txt I already have?: No. It warns before replacing a robots.txt you ship in public/, and it adds Sitemap and llms.txt directives to the policy it generates.
Which Node and Astro versions are required?: Node 20 or newer and Astro 5 or newer. Astro-AEO is MIT licensed.

Make your Astro site AI-readable.

One astro add, and every page ships a clean markdown copy, an llms.txt index, and a crawler policy.

View on npm GitHub

Your Astro site, ready for every AI search.

What AI reads, before and after.

One build, every AI artifact.

How it works

Astro renders

HTML is collected

Markdown is extracted

Artifacts fan out

Output is validated

Nine features, one install.

Generate .md files

Inject link tags

Generate llms.txt

Generate JSON-LD

Generate robots.txt

Generate domain profile

Generate URL map

Preview in dev

Validate output