Choosing Between Astro and Eleventy for Large Docs

Once a documentation set crosses roughly a thousand pages, the framework decision stops being about syntax preference and starts being about throughput: how long a full build takes, how fast an author sees their edit, how search scales, and how much front-end knowledge writers need. Astro and Eleventy both produce excellent static documentation, but they behave differently at this size. This guide compares them on the four things that actually hurt at scale, with measured numbers from a representative 1,500-page corpus. It sits under Astro vs Eleventy for Documentation Sites, within the broader Choosing the Right Static Site Generator for Production work.

Prerequisites

• A documentation corpus you can measure against — ideally your real Markdown, since synthetic pages compress differently than prose with code blocks.
• Node 20+ and hyperfine installed for repeatable build timing (brew install hyperfine or your package manager's equivalent).
• A rough inventory of how many pages need interactivity (tabs, live demos, embedded playgrounds) versus plain prose — this single ratio drives most of the decision.

Build Scaling at 1000+ Pages

The single most felt difference at scale is build time. Eleventy does less per page — it parses Markdown, runs a template, and writes HTML — so a corpus of pure Markdown builds fast. Astro compiles each page through its component pipeline, which buys you components but costs CPU per page.

On a 1,500-page corpus (real documentation Markdown averaging 900 words per page, ~12% of pages with a tabbed code component), measured with hyperfine --warmup 1 --runs 5:

# Repeatable cold-build timing
hyperfine --warmup 1 --runs 5 'rm -rf dist && npx @11ty/eleventy'
hyperfine --warmup 1 --runs 5 'rm -rf dist && npx astro build'

The cold-build gap is large but only paid in CI. What authors feel all day is the incremental rebuild, where both are sub-two-seconds. Eleventy's --incremental flag rebuilds only the changed file's outputs; Astro's dev server uses an in-memory content cache that keeps warm rebuilds fast. If your CI cold build is the bottleneck, that is a caching problem more than a framework problem — the same caching discipline described in Caching node_modules in GitHub Actions for Faster SSG Builds applies to both.

Search at Scale

Neither generator ships search; you build an index at build time and ship a client-side searcher. The pragmatic choice for both is Pagefind, which indexes your built HTML output, so it is framework-agnostic and adds the same step regardless of generator:

# After either build, index the output directory
npx pagefind --site dist

Pagefind shards its index and lazy-loads only the shards a query touches, which is why it scales to thousands of pages without shipping a multi-megabyte index up front. On the 1,500-page corpus the generated index totaled 4.1 MB on disk but the browser downloaded only ~90 KB for a typical two-word query, because unrelated shards are never fetched. If you prefer an in-app index, a prebuilt FlexSearch index works too, but you own the size budget — a naive Lunr index over 1,500 pages came out to 2.3 MB shipped on first search, which is the kind of payload that erases the JavaScript savings of a static site.

Components, MDX, and Authoring

This is where the two frameworks genuinely diverge. Astro gives you a real component model: a <Callout>, a <Tabs>, a versioned <ApiTable> are components you write once and authors invoke. With MDX, authors import and place components inline. That power has a cost at scale — MDX pages parse and compile more slowly than plain Markdown, so a docs set that is 80% MDX builds noticeably slower than one that is 80% Markdown.

Eleventy reaches the same outcomes through shortcodes and includes rather than components:

{% raw %}{% callout "warning" %}
Deprecated in v3 — migrate to the new client.
{% endcallout %}{% endraw %}

The practical rule at 1000+ pages: keep the majority of pages plain Markdown and reserve components/MDX for the pages that truly need interactivity. That keeps build time down on both frameworks and keeps the authoring surface small for writers. For the framework-feature comparison that underlies this, see the parent Astro vs Eleventy for Documentation Sites.

Authoring Ergonomics for Writers

Who edits the docs matters as much as the byte counts. Eleventy's templates-and-Markdown model is forgiving: a writer can edit a .md file and never see a component. Astro asks authors to understand frontmatter conventions and, for MDX, component imports — manageable when an engineer owns the layout layer and writers stay in the Markdown body, but a real ramp for a non-technical team.

If your documentation team is primarily writers, that ergonomic difference often outweighs the build-time numbers. See Best SSG for Technical Writers Without Coding Experience for the authoring-first view, and Eleventy vs Jekyll for Markdown-Heavy Blogs for how Eleventy compares against the other template-first option.

Measured Impact

Putting the numbers together for the 1,500-page corpus:

The headline: Eleventy wins cold-build throughput and writer simplicity; Astro wins component ergonomics and per-page interactivity. Search and shipped-JS are a wash because both rely on the same post-build indexing and both default to zero JavaScript.

Pitfalls & Rollback

• Benchmarking on synthetic pages: uniform generated Markdown understates Astro's component cost and overstates cache efficiency. Always time against your real corpus.
• Going all-in on MDX: converting every page to MDX for the convenience of occasional components multiplies build time. Keep MDX scoped to interactive pages.
• Shipping a monolithic search index: a single Lunr/FlexSearch index over thousands of pages can dwarf your page payload. Prefer a sharded index like Pagefind, or budget the index size explicitly.
• Ignoring the author audience: a faster build that your writers can't operate is a net loss. Weight authoring ergonomics for the people who actually edit pages.
• Rollback: because both generators consume the same Markdown source tree, a trial migration is low-risk. Keep content framework-agnostic (plain Markdown, shortcodes abstracted) and you can build the same corpus with either tool, comparing real numbers before committing.

Conclusion

At 1000+ pages the decision reduces to two questions the flowchart captures: do many pages need interactive components, and do writers work without engineers? If the answer is mostly-prose-and-writers, Eleventy's faster cold builds and simpler authoring win. If it is component-heavy docs maintained by a team comfortable with frontmatter and MDX, Astro's component model earns its extra build seconds. Measure your real corpus with hyperfine, scope MDX tightly, and index search at build time — then either framework will carry a large documentation set well.

FAQ

Which is faster to build at 1000+ pages, Astro or Eleventy?

For pure Markdown with no per-page components, Eleventy is usually faster on a cold build because it has less per-page work. In our 1,500-page test Eleventy finished a cold build in 41 seconds versus 88 seconds for Astro. Astro narrows the gap on incremental rebuilds when its content cache is warm.

Do I need MDX for a large documentation site?

Not necessarily. If most pages are prose with the occasional callout or tabbed code block, plain Markdown plus a few shortcodes or components covers it. Reach for MDX only when many pages embed interactive widgets, because MDX raises per-page parse and compile cost at scale.

How should search work on a 1000-page static site?

Build a search index at build time and ship a client-side search library such as Pagefind or a prebuilt Lunr or FlexSearch index. Both Astro and Eleventy can run an index step after the build. Pagefind is index-on-output, so it works identically for either generator.

Can a small writing team manage either without front-end engineers?

Eleventy leans on templates and Markdown and is easier for writers who never touch a component. Astro asks authors to understand components and frontmatter conventions, which is fine if an engineer maintains the layout layer and writers only edit Markdown.

Does Astro ship JavaScript to documentation readers?

Only what you opt into. Static Astro pages ship zero JavaScript unless you add an interactive island. Eleventy ships zero JavaScript by default as well. For read-mostly docs both can deliver near-zero-JS pages.

Related

• Parent: Astro vs Eleventy for Documentation Sites — the framework-feature comparison this decision builds on.
• Best SSG for Technical Writers Without Coding Experience — the authoring-first angle on the same choice.
• Eleventy vs Jekyll for Markdown-Heavy Blogs — Eleventy against the other template-first option.
• Choosing the Right Static Site Generator for Production — where this fits the full selection picture.