Astro

Astro appears in more guides here than any other generator, partly because it is where a lot of teams moving off client-rendered frameworks land, and partly because its model — static HTML by default, JavaScript only in islands that ask for it — makes it a useful reference point for performance work. The guides below cover it end to end: content collections and the content layer, image optimization with astro:assets, hydration directives and server islands, i18n routing, and deployment to Cloudflare Workers.

Roughly a quarter of them are comparisons, most against Eleventy and Next.js, measured on the same content. Read those if you are still deciding; read the how-tos if you have decided and want the setup that measured best.

Each stage has its own guides below; the hydration and image stages have the most.

Choosing the Right Static Site Generator for Production

Astro vs Eleventy Build Times at 10,000 PagesComparisonAstro and Eleventy benchmarked on the same docs corpus from 1,000 to 10,000 pages: cold, warm and one-page-edit builds, memory, and where each scales badly.
Astro vs Eleventy for Large Docs (1000+ Pages)ComparisonA decision guide for documentation sites of 1000+ pages — comparing Astro and Eleventy on build scaling, search, MDX/components, and authoring ergonomics with measured numbers.
Comparing Docs Framework Build TimesComparisonBenchmark Docusaurus, Starlight and VitePress on the same 2,000-page docs corpus: cold and warm builds, memory, output size and what drives each number.
Content Collections vs the Eleventy Data CascadeComparisonTwo ways to model documentation content: a typed schema that fails the build, or a layered cascade that resolves at render. What each buys, and how to get validation in both.
Dev Server Performance: Astro vs EleventyComparisonMeasure cold start, hot reload and memory for Astro and Eleventy dev servers on a 1,300-page docs site, and the settings that keep writers’ previews fast.
Gatsby vs Astro for Content Sites in 2026ComparisonGatsby and Astro compared for content sites today: build time, JavaScript shipped, Core Web Vitals, ecosystem health and the cost of moving.
MDX vs Markdoc for Docs ContentComparisonChoose between MDX and Markdoc for documentation components: authoring errors, validation, build speed and safety for contributor-heavy docs repos.
Markdown Pipelines: remark vs markdown-itComparisonCompare the remark and rehype pipeline in Astro with markdown-it in Eleventy: plugin models, speed, custom syntax, heading anchors and link rewriting.
Next.js Static Export vs Astro for MarketingComparisonA measured head-to-head of Next.js static export and Astro for marketing sites — JavaScript shipped, LCP and INP, developer experience, and build speed on the same pages.
Shortcodes vs Components for Docs AuthorsComparisonEleventy shortcodes and Astro components compared from the writer's chair: syntax, error messages, reuse, JavaScript cost and how to keep the vocabulary small.
Choosing an SSG for API Reference DocumentationConceptAPI docs are generated, versioned and enormous. Compare Hugo, Astro, Eleventy and Next export on build scale, schema-driven pages, versioning and search.
Choosing an SSG for a Marketing Site with Non-Technical EditorsConceptPick a generator and editing setup for a marketing site edited by non-developers: visual editing, previews, publish speed, guardrails and page performance.
Picking an SSG for a Multi-Language Docs SiteConceptCompare i18n in Astro, Hugo, Eleventy, and Jekyll for multi-language documentation — routing, content organization, and build cost — with measured numbers across locales.
SSG Selection Checklist for Engineering TeamsConceptA practical SSG selection checklist for engineering teams — score build scale, team skills, content model, i18n, hosting, ecosystem, and maintenance before you commit.
Scoring SSG Long-Term Maintenance RiskConceptScore a static site generator’s five-year maintenance risk: project health, upgrade history, dependency surface, plugin ecosystem and your exit cost.
Total Cost of Ownership for Static Site GeneratorsConceptEstimate the three-year cost of running a static site on Hugo, Eleventy, Astro, Next.js export or a docs framework: people time, builds, hosting, upgrades.
Adding JSON-LD Structured Data at Build TimeHow-toEmit valid JSON-LD from frontmatter in Astro, Eleventy and Hugo: build objects not strings, pick the right schema.org types, and validate every page in CI.
Adding Pagefind to an Astro SiteHow-toAdd Pagefind search to a plain Astro site: post-build indexing, content boundaries, heading weights, a lazy-loaded UI and a CI relevance check.
Converting Front Matter at Scale During MigrationHow-toScript front matter conversion across thousands of Markdown files between generators: field maps, type fixes, validation against a schema, and reviewable diffs.
Customizing Starlight Without Forking the ThemeHow-toBrand a Starlight docs site with CSS custom properties, component overrides and plugins so every upgrade stays a one-line version bump instead of a merge.
Generating Breadcrumb Structured Data in AstroHow-toGenerate visible breadcrumbs and matching BreadcrumbList JSON-LD in Astro from the URL or content collections, with readable names, and test both in CI.
How to Benchmark Hugo vs Astro Build SpeedsHow-toBuild a reproducible Hugo-vs-Astro benchmark with hyperfine — identical corpus, pinned containers, production builds only — so numbers reflect the generators, not your laptop.
Loading Remote Content With Astro Content Layer LoadersHow-toPull content from an API or CMS into Astro collections with a custom content layer loader, cache it between builds with digests, and validate it with a schema.
Migrating From Hugo to Astro Without Breaking URLsHow-toMove a Hugo site to Astro content collections while reproducing every permalink: slug mapping, a typed schema, shortcodes as MDX components, and a URL parity gate in CI.
Migrating from Gatsby to AstroHow-toMove a Gatsby content site to Astro: replace GraphQL queries with content collections, port React components as islands, and keep image quality and URLs.
Migrating from Next.js Pages Router to AstroHow-toMove a content-heavy Next.js Pages Router site with getStaticProps to Astro: routes, data fetching, MDX, React islands, images, redirects and the measured result.
RSS and Atom Feeds for Static BlogsHow-toPublish valid RSS and Atom feeds from Eleventy, Astro or Hugo with full content, absolute URLs, stable IDs and correct headers, then check them in CI.
Sidebar Navigation in Astro and EleventyHow-toBuild a docs sidebar from content in Astro and Eleventy: ordering, nesting, active state, collapsed sections, page weight, and keeping incremental builds fast.
Syntax Highlighting with Shiki in Astro and EleventyHow-toHighlight code at build time with Shiki in Astro and Eleventy: dual light and dark themes, line annotations, build-time cost and zero runtime JavaScript.
hreflang and Language Alternates on Static SitesHow-toGenerate reciprocal hreflang alternates from a translation key at build time in Hugo, Astro or Eleventy, and validate every language group in CI.
i18n Routing in AstroHow-toConfigure Astro i18n routing: locales, an unprefixed default language, fallbacks, locale-aware links and content collections organised per language.
Fixing Astro Build Errors After Upgrading to Astro 5FixWork through the build errors an Astro 4 site hits on Astro 5, from legacy collections and slug to removed hybrid output, and prove the URLs did not change.
Fixing Slow Astro Builds Caused by Large MDX CollectionsFixFind why an Astro build with thousands of MDX files is slow, then convert plain pages to Markdown, trim plugins and cache the content layer in CI.

63 guides use Astro in depth; each is listed below under the section it belongs to.

Core Web Vitals Optimization for SSGs

Astro Islands vs Full Hydration PerformanceComparisonMeasured comparison of Astro islands against full SPA hydration — JavaScript bytes, Total Blocking Time, and INP numbers, plus which directive to reach for.
Preact vs React Islands Bundle SizeComparisonMeasure React against Preact for Astro islands: runtime size, hydration time, compatibility gaps with preact/compat, and when switching is worth the effort.
Art Direction with the Picture ElementHow-toServe different crops of a hero image to mobile and desktop with picture and media queries in Astro, Eleventy and Hugo, without hurting LCP or causing layout shift.
Blur-Up Placeholders with LQIPHow-toGenerate tiny blurred placeholders for images at build time in Astro or Eleventy, inline them without slowing LCP, and decide when a solid colour is better.
Caching Processed Images Between BuildsHow-toPersist Astro and Eleventy image caches between CI builds so AVIF and WebP variants are generated once, with correct cache keys, pruning and measured build times.
Code Splitting and Module Preload in Vite-Based SSGsHow-toFind JavaScript that loads on every page of an Astro or VitePress site, split it with dynamic imports and manualChunks, and keep modulepreload hints honest.
Deferring Hydration with client:visible in AstroHow-toUse client:visible, client:idle and client:media to delay Astro island hydration until it is needed, cut startup JavaScript and protect INP on content pages.
Generating Open Graph Images at Build TimeHow-toRender a unique social preview image for every page at build time with Satori and resvg, cache the output, and wire og:image tags into Astro, Hugo or Eleventy.
Inlining Critical CSS on Static SitesHow-toRemove the render-blocking stylesheet on static sites: inline small CSS whole, or extract critical rules per page with Beasties, and measure the trade-off.
Lazy-Loading Images Without Hurting LCPHow-toloading="lazy" saves bytes below the fold but delays the LCP image when applied to it. How to decide per image, per template, in Astro, Hugo and Eleventy.
Optimizing LCP on Astro with Priority HintsHow-toUse fetchpriority="high", rel=preload, and Astro Image priority to load the hero first and cut LCP — with measured before/after numbers from Lighthouse and WebPageTest.
Optimizing WebP Images in Hugo Without PluginsHow-toGenerate WebP at build time using only Hugo's built-in image processing — no Node, no plugins, no system libraries. Requires the hugo-extended edition for WebP.
Prefetching Links in AstroHow-toConfigure Astro's built-in prefetch — strategies, defaults, per-link overrides and speculation rules — and measure what it does to navigation speed.
Replacing React Islands with Web ComponentsHow-toSmall interactive widgets rarely need React. Rewriting islands as custom elements removes the framework runtime, cuts JavaScript and improves INP.
Server Islands in AstroHow-toUse Astro server islands to add small per-request parts to a static page, such as stock or account state, with fallbacks, caching headers and measured costs.
Serving Astro Images Through Cloudflare Image ResizingHow-toMove Astro image processing from build time to Cloudflare Images transformations with a custom image service, cutting build time while keeping srcset and AVIF.
Tailwind v4 in Astro Without PostCSS PluginsHow-toMove an Astro site from Tailwind 3 with the PostCSS integration to Tailwind 4 on its Vite plugin: CSS-first config, sources, dark mode and build time, measured.
View Transitions in Astro Without Hurting VitalsHow-toAdd view transitions to an Astro site with the ClientRouter or native cross-document transitions, then keep LCP, INP and CLS intact with measured settings.
Eliminating Render-Blocking CSS on Static SitesFixInline critical CSS, defer the rest, and purge unused rules to cut render delay on static sites — with measured LCP and FCP before/after from Lighthouse.
Fixing Blurry Images From astro:assets ResizingFixFind why images from Astro's Image and Picture components look soft on high-density screens, and fix widths, sizes, densities and quality settings.
Fixing Hydration Mismatch Errors in Astro IslandsFixTrack down hydration mismatch warnings in React, Preact and Vue islands on Astro pages, from dates to invalid HTML, and fix them without client:only.
Reducing LCP from Hero Images on Static SitesFixSize, format, and preload hero images to cut LCP on static sites — responsive srcset, AVIF/WebP, explicit dimensions, and why you must never lazy-load the hero.

Production-Ready Deployment & CI/CD for SSGs

Incremental Rebuild Times Across Astro, Eleventy and HugoComparisonAstro, Eleventy and Hugo measured on the same 5,000-page site for full, cached and single-page rebuilds, in CI and the dev server, with what each skips.
Vercel ISR vs Static Generation for SSGsComparisonISR rebuilds pages on demand; static generation builds everything upfront. Astro, Eleventy, Hugo, and Jekyll have no ISR — they rebuild and purge at the CDN.
Build Caching on Netlify and VercelHow-toMake Netlify and Vercel reuse dependency, framework and image caches between static site builds, verify cache hits in logs, and measure the savings.
Building Astro Sites with GitHub ActionsHow-toA production GitHub Actions workflow for Astro: pinned Node, dependency and image caches, astro check, build artifacts and a deploy job that only runs on main.
Deploying Astro to Cloudflare Workers Static AssetsHow-toDeploy a static Astro site to Cloudflare Workers with static assets: wrangler config, trailing slashes, 404 handling, headers, previews and optional server routes.
Deploying Astro to Vercel as a Fully Static SiteHow-toDeploy an Astro site to Vercel as pure static output with no functions: skipping the adapter, headers and redirects in vercel.json, and images.
Hash-Based CSP for Inline Scripts in AstroHow-toCompute SHA-256 hashes for every inline script in an Astro build, write them into the CSP header automatically, and keep unsafe-inline out of the policy.
Incremental Builds in Astro with the Content LayerHow-toHow the Astro content layer caches entries between builds, how to write loaders with digests, and how to persist the data store in CI so builds stay fast.

Topic pages give the wider context for each group; the numbers count only guides that use this tool in depth.

Often used with Astro

Eleventy22 shared guidesIncremental builds, image pipelines and the data cascade.
Hugo17 shared guidesBuild time at scale, image caches, modules and multilingual sites.
Starlight4 shared guidesAstro-based docs: overrides, translation and migration in.
Next.js4 shared guidesStatic export for content sites, its limits and alternatives.
Jekyll3 shared guidesPlugins, reproducible builds, upgrades and migration away.
Vercel3 shared guidesNon-Next.js generators, the Build Output API and caching.