Static Site Generators: Domain Explainer#

What is a Static Site Generator?#

A Static Site Generator (SSG) is a tool that creates a complete website made up of pre-rendered HTML files during a build process, rather than generating pages dynamically on each request.

Static vs Dynamic Sites#

Example: Blog Post#

Static Site (SSG):

Build time:
markdown/my-post.md → SSG → HTML/my-post.html (stored on disk)

Request time:
User visits /my-post → Server sends pre-rendered HTML (instant)

Dynamic Site (SSR):

Request time:
User visits /my-post → Server queries database → Renders template → Sends HTML (slower)

Core Concepts#

1. Build Process#

SSGs follow a build-once, serve-many model:

Content (Markdown, MDX) + Templates + Assets
           ↓
     Build Process
           ↓
Static HTML + CSS + JS + Images
           ↓
    Deploy to CDN

Example build command:

hugo build              # Hugo
npm run build           # Next.js/Astro/Gatsby
jekyll build            # Jekyll

Output: A dist/ or public/ folder with static HTML files ready to serve.

2. Content Authoring#

Most SSGs use Markdown for content:

---
title: "My Blog Post"
date: 2026-02-04
tags: ["webdev", "ssg"]
---

# My Blog Post

This is the content of my post.

Frontmatter: Metadata in YAML/TOML/JSON at the top of files Content: Markdown body converted to HTML

3. Templating#

SSGs use templates to define page structure:

Hugo (Go templates):

{{ range .Pages }}
  <article>
    <h2>{{ .Title }}</h2>
    <time>{{ .Date }}</time>
    {{ .Content }}
  </article>
{{ end }}

Astro (component-based):

---
const posts = await getCollection('blog');
---
{posts.map(post => (
  <article>
    <h2>{post.data.title}</h2>
    <time>{post.data.date}</time>
    <slot />
  </article>
))}

Next.js (React):

export default function BlogPost({ post }) {
  return (
    <article>
      <h1>{post.title}</h1>
      <time>{post.date}</time>
      <div dangerouslySetInnerHTML={{ __html: post.html }} />
    </article>
  );
}

4. Routing#

File-based routing: Directory structure becomes URL structure

content/
  about.md          →  /about
  blog/
    post-1.md       →  /blog/post-1
    post-2.md       →  /blog/post-2

Dynamic routing: Generate pages from data

// Generate a page for each blog post
export async function getStaticPaths() {
  const posts = await fetchAllPosts();
  return posts.map(post => ({ params: { slug: post.slug } }));
}

JAMstack Architecture#

JAMstack = JavaScript + APIs + Markup

SSGs are the core of the JAMstack philosophy:

Static HTML (M)
    ↓
JavaScript for interactivity (J)
    ↓
APIs for dynamic data (A)

Example: E-commerce Site#

Static:

• Product pages (generated at build time)
• Marketing pages
• Blog content

Dynamic (via APIs):

• Shopping cart (client-side JS)
• Checkout (Stripe API)
• Inventory (headless CMS API)

Architecture:

Hugo (build product pages)
    ↓
Deploy to Cloudflare Pages
    ↓
Client-side JS fetches live inventory from API
    ↓
Stripe handles checkout

Benefits:

• Product pages load instantly (pre-rendered)
• Inventory updates without rebuild (API call)
• Secure (no database to attack)
• Scales infinitely (CDN)

Rendering Strategies#

1. Static Site Generation (SSG)#

All pages generated at build time.

Pros:

• Fastest page loads
• Cheapest hosting
• Best for SEO

Cons:

• Content updates require rebuild
• Not suitable for real-time data

Use cases: Blogs, documentation, marketing sites

2. Server-Side Rendering (SSR)#

Pages generated on each request.

Pros:

• Always up-to-date content
• User-specific pages

Cons:

• Slower than SSG
• Requires server

Use cases: Dashboards, user profiles, real-time apps

3. Incremental Static Regeneration (ISR)#

Static pages with background updates (Next.js).

How it works:

export async function getStaticProps() {
  return {
    props: { data },
    revalidate: 60, // Regenerate every 60 seconds
  };
}

Process:

1. Page generated at build time
2. After 60s, next request shows cached page
3. Background regeneration starts
4. New version replaces cache

Pros:

• Fast like SSG
• Updates without full rebuild

Cons:

• Requires Node.js server
• Not true “static”

Use cases: E-commerce, CMS-driven sites

4. Client-Side Rendering (CSR)#

Minimal HTML, JavaScript renders content.

Pros:

• Highly interactive
• No server required

Cons:

• Slow initial load
• Poor SEO

Use cases: Single-page apps (SPAs), authenticated apps

Hybrid Rendering#

Modern SSGs like Next.js and Astro support mixing strategies per-page:

/about         → SSG (static)
/blog/[slug]   → SSG (static)
/dashboard     → SSR (dynamic)
/products      → ISR (static + updates)

Hydration#

Hydration is the process of making static HTML interactive by attaching JavaScript event handlers.

Full Hydration (React/Vue SSGs)#

1. Server renders <button onClick={handleClick}>Click</button> to HTML
2. Client loads JavaScript bundle
3. React "hydrates" button (attaches event listener)
4. Button becomes interactive

Downside: Entire page’s JavaScript must load, even if only one button is interactive.

Partial Hydration (Astro Islands)#

Islands Architecture: Only interactive components (“islands”) hydrate.

<!-- Static HTML (no JS) -->
<header>
  <h1>My Site</h1>
</header>

<!-- Interactive island (loads JS) -->
<ProductCarousel client:visible />

<!-- Static HTML (no JS) -->
<footer>
  <p>Copyright 2026</p>
</footer>

Benefits:

• 90%+ less JavaScript
• Faster page loads
• Heavy components don’t block light ones

Build Performance#

Why Build Speed Matters#

For a 1000-page site:

• Hugo: 2 seconds → Deploy in 1 minute
• Gatsby: 10 minutes → Deploy in 15 minutes

CI/CD impact: Fast builds = faster iteration, cheaper CI costs

Incremental Builds#

Full build: Regenerate all pages Incremental build: Only regenerate changed pages

Example (Hugo):

hugo --gc --cacheDir .cache  # Incremental build

Benefit: 1000-page site, change 1 file → rebuild in seconds, not minutes

Content Sources#

SSGs can pull content from multiple sources:

1. Local Files (Markdown/MDX)#

content/
  blog/
    post-1.md
    post-2.md

2. Headless CMS#

Fetch content from API during build:

const posts = await fetch('https://api.contentful.com/...');

Popular headless CMS: Contentful, Sanity, Strapi, WordPress (headless mode)

3. Databases#

Query database at build time:

const posts = await db.query('SELECT * FROM posts');

4. APIs#

Fetch data from any API:

const weather = await fetch('https://api.weather.com/...');

GraphQL data layer (Gatsby): Unified API for all data sources

query {
  allMarkdownRemark { ... }
  allContentfulPost { ... }
  allWordPressPost { ... }
}

Deployment#

Static Hosting Platforms#

Deploy Process#

# 1. Build site locally
npm run build

# 2. Push to Git
git push origin main

# 3. Platform auto-deploys
# → Pulls code
# → Runs build command
# → Deploys to CDN

Automatic deploys: Push to Git → Site updates in 1-5 minutes

When to Use SSGs#

✅ Good Fit#

• Blogs and portfolios: Content changes infrequently
• Documentation: Versioned docs, search, fast loads
• Marketing sites: High performance, low cost
• Landing pages: SEO critical, conversion-focused
• E-commerce (catalog): Product pages pre-rendered

❌ Poor Fit#

• Real-time apps: Dashboards, chat, live data
• User-generated content: Social networks, forums
• Personalized pages: Recommendations, user-specific views
• Frequent updates: News sites with minutely updates

Hybrid Approach#

Use SSG for static pages + APIs/SSR for dynamic features:

SSG (Hugo):
- Product pages
- Marketing pages
- Blog

API/SSR:
- Shopping cart (client-side)
- Checkout (Stripe API)
- User dashboard (SSR)

Common Gotchas#

1. Build Time Explosion#

Problem: Site with 10,000 pages takes 30+ minutes to build

Solutions:

• Use Hugo (fastest SSG)
• Enable incremental builds
• Use ISR (Next.js) for pages that update

2. Memory Issues (OOM)#

Problem: Build fails with out-of-memory error

Causes:

• Docusaurus/Gatsby with 1000+ pages
• Large image processing
• GraphQL data layer (Gatsby)

Solutions:

• Increase Node memory: NODE_OPTIONS=--max-old-space-size=8192
• Switch to Hugo (low memory usage)
• Reduce image processing during build

3. Dynamic Content#

Problem: Need to show real-time inventory on product pages

Solutions:

• Client-side fetch: Pre-render page, fetch inventory with JavaScript
• ISR: Update pages every 60 seconds without full rebuild
• SSR: Don’t use SSG, render on-demand

SSG Terminology#

Choosing an SSG: Decision Framework#

1. What content type?#

• Blog/Portfolio → Hugo, Eleventy
• Documentation → Starlight, VitePress, Hugo
• Marketing → Astro, Next.js
• E-commerce → Next.js (ISR)

2. What framework preference?#

• React → Next.js, Astro (with React)
• Vue → VitePress, Astro (with Vue)
• No framework → Hugo, Eleventy
• Multi-framework → Astro

3. What’s your priority?#

• Speed (build time) → Hugo
• Speed (page load) → Astro, Hugo
• Developer experience → Astro, Next.js
• Simplicity → Eleventy, Jekyll

4. What’s your scale?#

• <100 pages → Any SSG
• 100-1000 pages → Hugo, Astro, VitePress
• 1000+ pages → Hugo only (or accept slow builds)

Summary#

Static Site Generators pre-render websites at build time, resulting in:

• ⚡ Fast page loads (pre-rendered HTML)
• 💰 Cheap hosting ($0-$5/month)
• 🔒 Secure (no server-side code)
• 📈 Infinite scalability (CDN)

Best for: Blogs, docs, marketing sites, content-heavy sites

Not for: Real-time apps, user-generated content, personalized pages

Modern SSGs (Astro, Next.js) support hybrid rendering, mixing static and dynamic as needed.

Recommended for 2026:

• Default: Astro (best DX, modern)
• Speed: Hugo (fastest)
• React: Next.js (ecosystem)
• Docs: Starlight (beautiful, fast)

S1-Rapid: Static Site Generator Quick Decision Guide#

Reading time: 15 minutes

A practical guide for choosing the right static site generator (SSG) for your project.

Table of Contents#

1. When to Use an SSG
2. Quick Selection Matrix
3. Top Recommendations by Priority
4. Red Flags and Gotchas
5. Decision Tree

When to Use an SSG#

Good Fit for SSGs#

Static site generation works best when:

• Content changes infrequently - Blogs, documentation, marketing sites, portfolios
• Performance is critical - Pre-rendered HTML loads instantly
• Security matters - No server-side code means minimal attack surface
• SEO is important - Pre-rendered pages are easily crawlable
• Hosting costs should be low - Static files can be served from CDN

Poor Fit for SSGs#

Avoid SSGs when:

• Content updates frequently - E-commerce inventory, social feeds, real-time dashboards
• User-specific content dominates - Personalized recommendations, user dashboards
• Interactive features are core - Complex web apps with heavy client-side logic
• Build times become prohibitive - Sites with 10,000+ pages may take too long to rebuild
• Content requires server-side processing - Authentication, payments, form handling

Hybrid approach: Many frameworks (Next.js, Astro) support mixing SSG with server-side rendering (SSR) or client-side rendering (CSR) on a per-page basis.

Source: Smashing Magazine - Differences Between Static Generated Sites And Server-Side Rendered Apps

Quick Selection Matrix#

Legend:

• DX = Developer Experience
• ⚡⚡⚡ = Seconds for 1000s of pages
• ⚡⚡ = Under 1 minute for large sites
• ⚡ = Minutes for large sites
• 🐌 = Can take 30+ minutes for 1000+ pages

Performance sources:

• CloudCannon - Top Five Static Site Generators for 2025
• Criztec - Hugo vs Astro Showdown

Top Recommendations by Priority#

#1 Performance Above All Else#

Choose: Hugo

• Builds 1000s of pages in seconds
• Written in Go (compiled binary, no runtime)
• Lowest memory footprint
• Best for: Large-scale content sites, blogs, documentation

When not Hugo: If you need React/Vue components or modern JavaScript framework features

Alternative: Astro (nearly as fast, better DX, framework flexibility)

Source: CloudCannon - Top Five Static Site Generators

#2 Developer Experience#

Choose: Astro

• Zero JavaScript by default (ships only what’s needed)
• “Islands Architecture” for partial hydration
• Use React, Vue, Svelte, Solid in same project
• Excellent error messages and debugging
• Vite-based hot reload

Trade-off: Not quite as fast as Hugo for massive sites (still fast though)

Source: Crystallize - React-based SSGs Performance

#3 Documentation Sites#

Choose: Starlight (Astro) or VitePress

Starlight:

• Built on Astro, optimized for docs
• Beautiful out-of-the-box design
• Built-in search, i18n, dark mode
• Framework-agnostic (use any UI library)

VitePress:

• Built on Vue + Vite
• Lightning-fast builds
• Simple, focused on docs
• Great for Vue ecosystem projects

When to choose Docusaurus: Already using React heavily, need versioning features, large community

Sources:

• Starlight Astro Build
• Documentation Generator Comparison 2025

#4 Hybrid Static + Dynamic#

Choose: Next.js

• Mix SSG, SSR, and CSR on per-page basis
• Incremental Static Regeneration (ISR) for updating specific pages
• Built-in image optimization
• Massive React ecosystem

Trade-offs:

• Heavier than pure SSGs
• Longer build times for large static sites
• Vercel-centric (though works elsewhere)

When to choose: E-commerce sites, marketing sites with personalization, apps needing auth + static pages

Source: LogRocket - SSG vs SSR in Next.js

#5 Simplicity and Flexibility#

Choose: Eleventy (11ty)

• Zero-config by default
• 10 templating languages supported
• JavaScript-based (Node.js)
• No client-side framework lock-in
• Fast builds (faster than Jekyll/Gatsby)

Best for: Developers who want control over templating without framework constraints

Source: CloudCannon - Eleventy vs Jekyll

Red Flags and Gotchas#

🚩 Build Time Explosion#

Symptom: Site takes 30+ minutes to build, or builds time out

Causes:

• Docusaurus/Next.js/Gatsby with 1000+ pages
• Memory leaks during build (known issue with Docusaurus i18n)
• Image optimization processing thousands of images
• GraphQL query overhead (Gatsby)

Solutions:

• Use incremental builds (Next.js ISR, Hugo’s --incremental)
• Switch to Hugo or Astro for large sites
• Increase Node memory: NODE_OPTIONS=--max-old-space-size=8192
• Split site into multiple smaller sites

Sources:

• GitHub - Docusaurus Memory Leaks Issue
• GitHub - Next.js SSG Performance Discussion

🚩 Memory Usage Spikes#

Symptom: Build process crashes with OOM errors

Common culprits:

• Docusaurus with large localized sites
• Gatsby’s GraphQL data layer
• Next.js processing thousands of pages

Workarounds:

• Monitor with: NODE_OPTIONS=--max-old-space-size=8192 npm run build
• Switch to Hugo (minimal memory footprint)
• Use Astro with selective rendering

Source: GitHub - Docusaurus SSG Memory Leak Fix

🚩 Framework Lock-In#

Risk: Hard to migrate if you need to switch SSGs later

High lock-in:

• Gatsby (GraphQL data layer, React-specific)
• Docusaurus (React + MDX + custom plugin system)
• Next.js (React + file-based routing conventions)

Low lock-in:

• Hugo (Go templates, but content is standard Markdown)
• Eleventy (vanilla HTML/Markdown + flexible templating)
• Jekyll (Liquid templates, standard Markdown)

Mitigation: Keep content in standard Markdown/MDX, minimize framework-specific features

🚩 Ecosystem Decay#

Warning signs:

• Declining GitHub activity
• Plugins not updated in 2+ years
• Breaking changes without migration guides

Safe bets (2025):

• Hugo (stable, mature, corporate backing)
• Astro (rapid growth, active development)
• Next.js (Vercel backing, massive adoption)

Risky choices:

• Jekyll (declining popularity, slower development)
• Gatsby (slowing momentum, cloud service pivot)

Source: Bugfender - Top Static Site Generators 2025

Decision Tree#

START
  │
  ├─ Need server-side logic? (auth, payments, personalization)
  │   ├─ YES → Use Next.js (hybrid SSG/SSR)
  │   └─ NO → Continue
  │
  ├─ Site has 1000+ pages?
  │   ├─ YES → Use Hugo (fastest builds)
  │   └─ NO → Continue
  │
  ├─ Building documentation site?
  │   ├─ YES → Starlight or VitePress
  │   └─ NO → Continue
  │
  ├─ Already using React heavily?
  │   ├─ YES → Next.js (SSG mode)
  │   └─ NO → Continue
  │
  ├─ Already using Vue?
  │   ├─ YES → VitePress
  │   └─ NO → Continue
  │
  ├─ Want maximum performance + modern DX?
  │   ├─ YES → Astro
  │   └─ NO → Continue
  │
  ├─ Want simplicity + templating flexibility?
  │   ├─ YES → Eleventy
  │   └─ NO → Continue
  │
  └─ Default recommendation → Astro
      (Best balance of speed, DX, flexibility)

Summary: The 30-Second Decision#

Most versatile choice for 2025: Astro (unless you have specific framework/speed constraints)

Additional Resources#

• BCMS - SSG vs SSR 2026
• CSS-Tricks - Comparing SSG Build Times
• Hygraph - Top 12 SSGs in 2025

S1-Rapid: Research Approach#

Objective#

Create a 15-minute quick decision guide for selecting a static site generator based on primary requirements.

Methodology#

1. Identify Decision Factors#

Key factors users consider when choosing an SSG:

• Build speed (for large sites)
• Developer experience
• Framework preference (React, Vue, or none)
• Use case (blog, docs, marketing, etc.)
• Community maturity

2. Performance Benchmarking#

Gather real-world build time data for SSGs at different scales:

• 100 pages
• 1000 pages
• 10,000 pages

Sources: GitHub issues, blog posts, official benchmarks

3. Quick Comparison Matrix#

Create a matrix showing:

• SSG name
• Build speed rating
• Best use case
• Key strengths
• When to avoid

4. Decision Tree#

Build a simple decision tree:

• Start with user’s primary need
• Branch based on constraints (speed, framework, scale)
• Lead to recommended SSG

5. Red Flags and Gotchas#

Document common issues users encounter:

• Build time explosion (Gatsby, Docusaurus at scale)
• Memory usage spikes
• Framework lock-in risks
• Ecosystem decay warnings

Sources Strategy#

• Official documentation for features
• GitHub discussions for performance issues
• CloudCannon, Netlify blogs for industry comparisons
• Real-world experience reports

Deliverable#

Single comprehensive README.md with:

• Selection matrix
• Decision tree
• Top 5 recommendations
• Anti-patterns to avoid

S1-Rapid: Final Recommendations#

Quick Selection Guide#

The 30-Second Decision#

Default Recommendation: Astro#

Why Astro is the most versatile choice for 2026:

1. Performance: Islands Architecture ships zero JS by default
2. Flexibility: Use React, Vue, Svelte in the same project
3. Developer Experience: Excellent error messages, Vite-based HMR
4. Ecosystem: Growing rapidly, 200+ integrations
5. Future-proof: Fastest growing web framework in adoption

When to choose alternatives:

• Speed critical (1000+ pages): Choose Hugo
• React ecosystem: Choose Next.js
• Vue ecosystem: Choose VitePress
• Documentation: Choose Starlight

Critical Warnings#

❌ Avoid Gatsby#

• Ecosystem declining
• Plugin support failures
• Memory issues at scale
• Company sunset Gatsby Cloud

Action: Migrate existing Gatsby sites to Astro or Next.js

⚠️ Be Cautious with Docusaurus#

• Excellent for React documentation
• BUT: Memory issues at 1000+ pages
• Slower builds than VitePress/Starlight

Better choice for large docs: Hugo or Starlight

Decision Framework#

1. Start with Astro unless you have specific constraints
2. Choose Hugo if build speed is non-negotiable
3. Choose Next.js if you’re heavily invested in React
4. Choose VitePress if you’re heavily invested in Vue
5. Never choose Gatsby for new projects in 2026

S2-Comprehensive: Deep Static Site Generator Library Analysis#

Reading time: 45-60 minutes

A detailed technical analysis of nine major static site generators, covering architecture, features, performance, and ecosystem maturity.

Table of Contents#

1. Comparison Matrix
2. Hugo
3. Astro
4. Next.js
5. Docusaurus
6. VitePress
7. Jekyll
8. Gatsby
9. Eleventy
10. Starlight
11. Performance Benchmarks
12. Trade-Off Analysis

Comparison Matrix#

Core Architecture#

Build Performance (Relative)#

Note: Benchmarks are approximate and vary based on content complexity, image processing, and hardware.

Sources:

• Hugo Performance
• Docusaurus Memory Leaks Issue
• Next.js SSG Performance Discussion

Feature Comparison#

Hugo#

Overview#

Hugo is a static site generator written in Go, optimized for speed and designed for large-scale content sites.

GitHub: https://github.com/gohugoio/hugo Stars: 75k+ Language: Go First Release: 2013

Architecture#

• Compiled binary: Hugo is distributed as a single Go binary with no runtime dependencies
• Parallel builds: Generates multiple pages simultaneously using Go’s concurrency primitives
• Content organization: Uses front matter (YAML/TOML/JSON) + Markdown content files
• Template system: Go’s html/template package with Hugo-specific functions

Build Pipeline:

Content (Markdown) → Front Matter Parse → Template Rendering → HTML Output
                                           ↓
                                    Parallel Processing

Performance Characteristics#

Hugo is the fastest SSG by a significant margin:

• 10,000 pages: ~1.82 seconds
• 100,000 pages: ~20 seconds
• Memory footprint: Very low (compiled binary, efficient memory management)

Optimizations:

• Parallel page generation
• partialCached for template result caching
• Efficient asset pipeline (SASS, PostCSS, JS bundling)

Source: Hugo Performance Documentation

Templating System#

Hugo uses Go templates with additional Hugo-specific functions:

{{ range .Pages }}
  <h2>{{ .Title }}</h2>
  <p>{{ .Summary }}</p>
{{ end }}

Strengths:

• Fast rendering (compiled templates)
• Type-safe (compile-time checks)
• Rich function library (string manipulation, date formatting, etc.)

Weaknesses:

• Learning curve for Go template syntax
• No JSX/component-based UI
• Limited dynamic interactivity

Content Management#

• Taxonomies: Built-in support for categories, tags, custom taxonomies
• Archetypes: Content templates for new posts
• Multilingual: First-class i18n support with per-language content trees
• Data files: JSON/YAML/TOML data sources

Ecosystem#

• Themes: 300+ community themes
• Modules: Hugo Modules for dependency management (similar to npm)
• Shortcodes: Reusable content snippets
• Deployment: Supports Netlify, Vercel, GitHub Pages, Cloudflare Pages

Best For#

• Large-scale content sites (1000+ pages)
• Documentation portals
• Blogs and news sites
• When build speed is critical

Limitations#

• No React/Vue components
• Template syntax less familiar than JSX
• Limited plugin ecosystem compared to JS-based SSGs
• Interactive features require vanilla JS or external frameworks

Source: Hugo GitHub Repository

Astro#

Overview#

Astro is a modern SSG that ships zero JavaScript by default and supports multiple UI frameworks (React, Vue, Svelte, Solid) through its “Islands Architecture.”

Website: https://astro.build GitHub: https://github.com/withastro/astro Stars: 45k+ Language: JavaScript/TypeScript First Release: 2021

Architecture: Islands#

The core innovation of Astro is Islands Architecture:

• Static HTML by default: All pages render to HTML with zero JS
• Selective hydration: Interactive components (“islands”) load JS only when needed
• Framework-agnostic: Mix React, Vue, Svelte, Solid in the same project

Islands Directives:

<!-- Static (no JS) -->
<Component />

<!-- Hydrate on page load -->
<Component client:load />

<!-- Hydrate when visible -->
<Component client:visible />

<!-- Hydrate when idle -->
<Component client:idle />

<!-- Hydrate on media query -->
<Component client:media="(max-width: 768px)" />

Benefits:

• Performance: Only interactive parts load JS, reducing bundle size by 90%+
• Flexibility: Use the right framework for each component
• Isolation: Islands don’t block each other (heavy component doesn’t slow light ones)

Sources:

• Astro Islands Architecture
• Strapi - Astro Islands Explained

Content Collections#

Astro 2.0+ introduces Content Collections for type-safe content:

// src/content/config.ts
import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
    pubDate: z.date(),
    tags: z.array(z.string()),
  }),
});

export const collections = { blog };

Advantages:

• Type safety for front matter
• Build-time validation
• Auto-complete in editor
• Query API for content

Build Performance#

• Build tool: Vite (fast HMR and bundling)
• Speed: Fast builds, though not as fast as Hugo
• Memory: Low memory usage (no GraphQL layer like Gatsby)
• Incremental: Partial support for incremental builds

Real-world example: Astro site with 127 pages/second build speed after optimization

Source: Bitdoze - Astro Build Speed Optimization

Framework Integration#

Astro supports integrations for multiple frameworks:

npx astro add react vue svelte solid

Each framework runs independently, and you can use them together:

---
import ReactComponent from './ReactComponent.jsx';
import VueComponent from './VueComponent.vue';
import SvelteComponent from './SvelteComponent.svelte';
---

<ReactComponent client:load />
<VueComponent client:visible />
<SvelteComponent client:idle />

Ecosystem#

• Integrations: 200+ official and community integrations
• Adapters: Deploy to Netlify, Vercel, Cloudflare, Node, Deno
• Themes: Growing theme ecosystem
• Content: Integrates with CMS (Contentful, Sanity, WordPress)

Best For#

• Performance-critical sites
• Multi-framework projects
• Content-heavy sites with occasional interactivity
• Teams with diverse framework expertise

Limitations#

• Younger ecosystem than Next.js/Gatsby
• Some framework features don’t work in SSG mode
• Learning curve for Islands concept

Source: Crystallize - React SSG Performance

Next.js#

Overview#

Next.js is a React framework that supports Static Site Generation (SSG), Server-Side Rendering (SSR), and Incremental Static Regeneration (ISR).

Website: https://nextjs.org GitHub: https://github.com/vercel/next.js Stars: 125k+ Language: JavaScript/TypeScript First Release: 2016 Backed by: Vercel

Hybrid Rendering Modes#

Next.js supports multiple rendering strategies per-page:

Static Site Generation (SSG)#

// pages/blog/[slug].tsx
export async function getStaticProps({ params }) {
  const post = await fetchPost(params.slug);
  return { props: { post } };
}

export async function getStaticPaths() {
  const posts = await fetchAllPosts();
  return {
    paths: posts.map(post => ({ params: { slug: post.slug } })),
    fallback: false, // or 'blocking' for ISR
  };
}

Build process:

1. getStaticPaths generates list of pages to pre-render
2. getStaticProps fetches data for each page
3. React renders each page to HTML
4. Output: Static HTML + JSON data files

Incremental Static Regeneration (ISR)#

ISR enables updating static pages without full rebuilds:

export async function getStaticProps() {
  const data = await fetchData();
  return {
    props: { data },
    revalidate: 60, // Revalidate every 60 seconds
  };
}

How it works:

1. Page is statically generated at build time
2. After revalidate seconds, next request still shows cached page
3. Background regeneration starts
4. New version replaces cache when ready

Important: ISR requires a Node.js server. It does NOT work with next export (pure static export).

Sources:

• Next.js ISR Documentation
• FreeCodeCamp - How ISR Works

Image Optimization#

Next.js includes next/image for automatic image optimization:

import Image from 'next/image';

<Image
  src="/photo.jpg"
  width={800}
  height={600}
  alt="Photo"
  loading="lazy"
  placeholder="blur"
/>

Features:

• Automatic WebP/AVIF conversion
• Responsive image srcset
• Lazy loading with blur placeholder
• Optimizes on-demand (not at build time)

Build Performance#

• Small sites (<100 pages): Fast
• Medium sites (100-1000 pages): 2-5 minutes
• Large sites (1000+ pages): 30+ minutes, potential OOM

Scaling challenges:

• Memory usage grows with page count
• No parallelization across pages
• Image optimization can be slow

Workarounds:

• Use ISR instead of full SSG for large sites
• Implement incremental builds
• Deploy on Vercel (optimized infrastructure)

Source: Next.js SSG Performance Discussion

Ecosystem#

• Massive: Largest React SSG ecosystem
• Plugins: Thousands of Next.js-compatible React libraries
• Deployment: Optimized for Vercel, but works on Netlify, AWS, etc.
• CMS integrations: Official integrations with 20+ headless CMS

Best For#

• React projects needing hybrid rendering
• E-commerce sites (ISR for product pages)
• Applications requiring auth + static pages
• Teams already using React

Limitations#

• Overkill for pure static sites
• Slow builds for large static sites
• Vercel-centric design (works elsewhere but less optimized)
• Heavy JavaScript bundle for simple sites

Source: Next.js Documentation

Docusaurus#

Overview#

Docusaurus is a documentation site generator built by Meta (Facebook) using React and MDX.

Website: https://docusaurus.io GitHub: https://github.com/facebook/docusaurus Stars: 55k+ Language: JavaScript/TypeScript First Release: 2017 (v2 in 2022) Backed by: Meta

Architecture#

• React SPA: Client-side navigation after initial load
• MDX: Markdown with JSX components
• Plugin-based: Core features (docs, blog, pages) are plugins
• Webpack: Uses Webpack for bundling

Build process:

1. Parse MDX files
2. Generate React components
3. Server-render to HTML
4. Bundle client-side JS
5. Output static HTML + JS bundles

Plugin System#

Docusaurus features are implemented as plugins:

module.exports = {
  plugins: [
    '@docusaurus/plugin-content-docs',
    '@docusaurus/plugin-content-blog',
    '@docusaurus/plugin-content-pages',
    '@docusaurus/plugin-sitemap',
  ],
};

Official plugins:

• Docs (versioning, sidebar, search)
• Blog (pagination, tags, RSS)
• Pages (custom React pages)
• Search (Algolia DocSearch integration)

Versioning#

Docusaurus has built-in documentation versioning:

npm run docusaurus docs:version 2.0

This creates:

versioned_docs/
  version-2.0/
    intro.md
    api.md
versioned_sidebars/
  version-2.0-sidebars.json

Users can switch between versions in the UI, and old docs remain accessible.

MDX Integration#

Docusaurus v3 uses MDX v3 (stricter than v2):

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# API Reference

<Tabs>
  <TabItem value="js" label="JavaScript">
    ```js
    fetch('/api/data')
    ```
  </TabItem>
  <TabItem value="python" label="Python">
    ```python
    requests.get('/api/data')
    ```
  </TabItem>
</Tabs>

Advantages:

• Interactive documentation
• Reusable components
• Type-safe with TypeScript

Gotcha: MDX v3 requires valid JSX (no loose HTML tags)

Source: Docusaurus Announcing 2.0

Internationalization#

Built-in i18n support:

module.exports = {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr', 'es', 'ja'],
  },
};

Creates separate builds per locale: build/en/, build/fr/, etc.

Memory issue: Docusaurus iterates locales sequentially, and memory grows with each locale, leading to potential OOM on large sites.

Source: Docusaurus SSG Memory Leak Fix

Build Performance#

• Small docs sites (<100 pages): Fast (10-20s)
• Medium sites (100-500 pages): 3-8 minutes
• Large sites (1000+ pages): Risk of OOM

Known issues:

• Memory leaks with i18n
• Webpack overhead for large sites
• No incremental builds

Workaround: Increase Node memory:

NODE_OPTIONS=--max-old-space-size=8192 npm run build

Source: Docusaurus Memory Leaks Issue

Ecosystem#

• Themes: Default theme + community themes
• Plugins: 50+ community plugins
• Search: Algolia DocSearch (free for open source)
• Deployment: Optimized for Netlify, Vercel, GitHub Pages

Best For#

• Technical documentation sites
• Open source project docs
• Sites needing versioning
• Teams familiar with React

Limitations#

• Memory issues on large sites
• Slower builds than Hugo/Astro
• React/Webpack overhead for simple docs
• MDX v3 migration can break existing content

Source: Semaphore - Using Docusaurus

VitePress#

Overview#

VitePress is a documentation-focused SSG built on Vue 3 and Vite, designed as a spiritual successor to VuePress.

Website: https://vitepress.dev GitHub: https://github.com/vuejs/vitepress Stars: 12k+ Language: JavaScript/TypeScript First Release: 2020 Backed by: Vue.js team

Architecture#

• Vue 3 SPA: Client-side navigation after initial load
• Vite-powered: Lightning-fast dev server and builds
• markdown-it: Markdown processor with plugins
• Static HTML + Vue hydration: Pre-rendered HTML becomes interactive Vue app

Build pipeline:

Markdown → markdown-it → Vue components → Vite SSR → HTML
                                                 ↓
                                           Vite build → JS bundles

Markdown Processing#

VitePress uses markdown-it with extensive customization:

// .vitepress/config.js
export default {
  markdown: {
    lineNumbers: true,
    anchor: { permalink: true },
    toc: { includeLevel: [1, 2, 3] },
  },
};

Built-in features:

• Syntax highlighting (Shiki)
• Line highlighting in code blocks
• Import code snippets from files
• Frontmatter support

Vue in Markdown:

# My Page

<script setup>
import { ref } from 'vue'
const count = ref(0)
</script>

<button @click="count++">Count: {{ count }}</button>

Source: VitePress Markdown

Theme Customization#

Extend default theme:

// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme';
import CustomComponent from './CustomComponent.vue';

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    app.component('CustomComponent', CustomComponent);
  },
};

Custom theme: Replace default theme entirely with your own Vue components.

Source: VitePress Custom Theme

Build Performance#

• Build tool: Vite (much faster than Webpack)
• Speed: Significantly faster than Docusaurus
• Memory: Low memory footprint
• Dev server: Instant HMR (hot module replacement)

Comparison: VitePress builds faster than Docusaurus and has lower memory usage for equivalent sites.

Source: Documentation Generator Comparison 2025

Ecosystem#

• Smaller than Docusaurus but growing
• Vue ecosystem: Use any Vue 3 component library
• Plugins: markdown-it plugins for Markdown extensions
• Deployment: Netlify, Vercel, GitHub Pages, Cloudflare Pages

Best For#

• Vue-based documentation sites
• Projects prioritizing build speed
• Developers familiar with Vue ecosystem
• Sites needing simpler setup than Docusaurus

Limitations#

• Vue-specific (not framework-agnostic)
• Smaller community than Docusaurus
• No built-in versioning (manual implementation)
• Less mature plugin ecosystem

Source: VitePress Documentation

Jekyll#

Overview#

Jekyll is a static site generator written in Ruby, known for being the original blog-aware SSG and powering GitHub Pages.

Website: https://jekyllrb.com GitHub: https://github.com/jekyll/jekyll Stars: 49k+ Language: Ruby First Release: 2008 GitHub Pages: Native support

Architecture#

• Ruby-based: Requires Ruby runtime
• Liquid templates: Shopify’s Liquid templating language
• Gem plugins: Extend functionality via Ruby gems
• Convention over configuration: Opinionated directory structure

Directory structure:

_posts/       # Blog posts (date-based)
_layouts/     # Page templates
_includes/    # Reusable snippets
_config.yml   # Site configuration
assets/       # CSS, JS, images

Liquid Templating#

{% for post in site.posts %}
  <article>
    <h2>{{ post.title }}</h2>
    <time>{{ post.date | date: "%B %d, %Y" }}</time>
    {{ post.excerpt }}
  </article>
{% endfor %}

Characteristics:

• Logic separated from content (no JSX)
• Filters for data transformation
• Limited to Liquid’s feature set (no custom functions without plugins)

Source: Jekyll Liquid Documentation

Plugin Ecosystem#

Jekyll plugins are Ruby gems:

# _config.yml
plugins:
  - jekyll-feed       # RSS feed
  - jekyll-seo-tag    # SEO meta tags
  - jekyll-sitemap    # XML sitemap
  - jekyll-paginate   # Pagination
  - jemoji            # GitHub emoji

GitHub Pages limitations: Only approved plugins work on GitHub Pages. For custom plugins, build locally and push HTML.

Source: Jekyll Plugins

GitHub Pages Integration#

Jekyll is native to GitHub Pages:

1. Push Markdown + Jekyll config to GitHub repo
2. GitHub automatically builds and deploys
3. No CI/CD configuration needed

URL: https://username.github.io/repo-name/

Limitations:

• Only approved plugins
• Ruby version locked by GitHub
• No custom build scripts

Source: GitHub Pages - Jekyll

Build Performance#

• Small sites: Fast enough
• Large sites: Slow compared to Hugo/Astro
• Incremental builds: Supported with --incremental flag

Benchmarks:

• 10,000 pages: ~5.4 seconds (vs Hugo’s 1.8s)
• 100,000 pages: ~1 minute (vs Hugo’s 20s)

Memory: Moderate memory usage

Theme System#

Jekyll themes are Ruby gems:

# _config.yml
theme: minima

Override theme files:

_layouts/default.html    # Override theme's default layout
_includes/header.html    # Override theme's header
assets/css/style.scss    # Extend theme styles

Popular themes: Minima, Cayman, Minimal Mistakes, Beautiful Jekyll

Source: Jekyll Themes

Best For#

• Simple blogs and portfolios
• GitHub Pages deployments
• Ruby developers
• Projects not needing modern JS frameworks

Limitations#

• Slower builds than Go/JS SSGs
• Ruby dependency (setup friction)
• Declining ecosystem activity
• Liquid less expressive than JSX/Vue

Source: CloudCannon - Eleventy vs Jekyll

Gatsby#

Overview#

Gatsby is a React-based SSG that uses GraphQL as a unified data layer, designed for pulling content from multiple sources.

Website: https://www.gatsbyjs.com GitHub: https://github.com/gatsbyjs/gatsby Stars: 55k+ Language: JavaScript/TypeScript First Release: 2015 Company: Gatsby Inc. (pivoted to Gatsby Cloud/Valhalla)

Architecture: GraphQL Data Layer#

Gatsby’s defining feature is its GraphQL data layer:

query {
  allMarkdownRemark {
    edges {
      node {
        frontmatter {
          title
          date
        }
        excerpt
        html
      }
    }
  }
}

How it works:

1. Source plugins ingest content (Markdown, CMS, APIs)
2. Gatsby builds a unified GraphQL schema at build time
3. Pages query data via GraphQL
4. React components render with queried data

Advantages:

• Unified API: Query all data sources the same way
• Type safety: GraphQL schema provides types
• Autocomplete: GraphiQL playground for exploring data

Disadvantages:

• Complexity: Extra layer of abstraction
• Build overhead: GraphQL schema generation adds time
• Memory usage: Entire data layer in memory during build

Source: Gatsby - Why GraphQL

Plugin Ecosystem#

Gatsby has a massive plugin ecosystem:

• Source plugins: Fetch data from CMS, APIs, databases (gatsby-source-contentful, gatsby-source-wordpress)
• Transformer plugins: Process data (gatsby-transformer-sharp for images, gatsby-transformer-remark for Markdown)
• Integration plugins: Add functionality (gatsby-plugin-image, gatsby-plugin-react-helmet)

Configuration:

module.exports = {
  plugins: [
    'gatsby-source-filesystem',
    'gatsby-transformer-remark',
    'gatsby-plugin-image',
    'gatsby-plugin-sharp',
    'gatsby-transformer-sharp',
  ],
};

Source: Docsie - 12 Best Gatsby Plugins 2025

Image Optimization#

Gatsby’s image optimization is highly advanced:

import { GatsbyImage, getImage } from 'gatsby-plugin-image';

const image = getImage(data.file);
<GatsbyImage image={image} alt="Description" />;

Features:

• Multiple image sizes generated at build time
• WebP/AVIF format conversion
• Blur-up placeholder
• Lazy loading
• Responsive srcset

Downside: Processing thousands of images at build time can be very slow and memory-intensive.

Source: Kyle Gill - Image Optimization with Gatsby

Build Performance Issues#

Gatsby has known performance problems for large sites:

• Memory usage: Very high due to GraphQL layer and image processing
• Build times: 5-15 minutes for medium sites, 30+ minutes or OOM for large sites
• Incremental builds: Partially implemented, but not as effective as Hugo/Next.js

Real-world reports:

• Sites with 1000+ pages frequently hit OOM errors
• Memory usage keeps growing during multi-locale builds

Mitigation:

• Increase Node memory (NODE_OPTIONS=--max-old-space-size=8192)
• Reduce image processing
• Use Gatsby Cloud (optimized infrastructure)

Source: GitHub - Next.js SSG Discussion (comparing to Gatsby)

Ecosystem Health (2025)#

Warning: Gatsby’s momentum has slowed:

• Company pivoted to Gatsby Cloud and Valhalla (Gatsby v5)
• Community activity declining
• Many developers migrating to Next.js/Astro
• Still viable, but ecosystem growth stagnant

Use with caution: Consider alternatives for new projects.

Source: Encircle Technologies - Gatsby in 2025

Best For#

• React projects with multiple data sources (CMS + API + Markdown)
• Sites requiring advanced image optimization
• Teams already invested in Gatsby
• Projects needing GraphQL data layer

Limitations#

• Slow builds and high memory usage
• Complexity overhead (GraphQL layer)
• Declining ecosystem momentum
• Not recommended for large sites (1000+ pages)

Source: Strapi - Gatsby Guide

Eleventy#

Overview#

Eleventy (11ty) is a JavaScript-based SSG that supports 10 different templating languages and has zero client-side JavaScript by default.

Website: https://www.11ty.dev GitHub: https://github.com/11ty/eleventy Stars: 17k+ Language: JavaScript First Release: 2018 Creator: Zach Leatherman (independent)

Architecture#

• Zero-config by default: Works out of the box
• Multi-template: Use any combination of 10 template languages
• No client JS: Pure static HTML output (opt-in for JS)
• Node.js-based: JavaScript data files and configuration

Philosophy: Flexibility without framework lock-in.

Templating Languages#

Eleventy supports 10 template languages:

1. HTML (.html)
2. Markdown (.md)
3. JavaScript (.11ty.js)
4. Liquid (.liquid)
5. Nunjucks (.njk)
6. Handlebars (.hbs)
7. Mustache (.mustache)
8. EJS (.ejs)
9. Haml (.haml)
10. Pug (.pug)

Mix and match:

/pages/
  index.njk        # Nunjucks template
  about.md         # Markdown
  blog.11ty.js     # JavaScript template
  contact.liquid   # Liquid template

Source: Eleventy Template Languages

Data Cascade#

Eleventy’s Data Cascade merges data from multiple sources:

1. Computed data
2. Front matter data
3. Template data files
4. Directory data files
5. Global data files

Example:

_data/site.json       # Global data
blog/blog.json        # Directory data
blog/post.md          # Front matter data

All data is available in templates:

{{ site.title }}
{{ blog.category }}
{{ title }}

Source: Smashing Magazine - Eleventy Deep Dive

Build Performance#

• Speed: Fast (faster than Jekyll and Gatsby)
• Memory: Low memory usage
• Hot reload: Supports live reload during development
• Incremental: No official incremental builds, but fast enough not to need it

Comparison: Eleventy builds several times faster than an equivalent Jekyll site.

Source: CloudCannon - Eleventy vs Gatsby

Ecosystem#

• Plugins: Smaller ecosystem than React-based SSGs
• Starter templates: 100+ community starters
• No framework lock-in: Use vanilla JS or any framework for client-side code
• Deployment: Works on Netlify, Vercel, GitHub Pages, etc.

Best For#

• Developers who want templating flexibility
• Sites that don’t need a JavaScript framework
• Progressive enhancement advocates
• Projects prioritizing simplicity

Limitations#

• No built-in React/Vue components (vanilla JS only)
• Smaller community than Next.js/Gatsby/Docusaurus
• Less opinionated (more decisions to make)
• No GraphQL data layer

Source: Tom Hazledine - Hugo vs Jekyll vs Gatsby vs 11ty

Starlight#

Overview#

Starlight is a documentation framework built on top of Astro, designed specifically for beautiful, performant docs sites.

Website: https://starlight.astro.build GitHub: https://github.com/withastro/starlight Stars: 4k+ Language: JavaScript/TypeScript First Release: 2023 Backed by: Astro team

Architecture#

Starlight is Astro under the hood:

• Islands Architecture: Inherits Astro’s partial hydration
• Framework-agnostic: Use React, Vue, Svelte for interactive components
• Zero JS by default: Static HTML for content
• Vite-powered: Fast builds and HMR

Built-in Features#

Starlight includes everything needed for documentation:

• Navigation: Automatic sidebar from file structure
• Search: Built-in search (Pagefind)
• i18n: Multi-language support
• Dark mode: Toggle between light/dark themes
• SEO: Optimized meta tags and structured data
• Accessibility: WCAG AA compliant
• Syntax highlighting: Code blocks with Shiki

Out-of-the-box design: Beautiful default theme that rivals custom-designed docs sites.

Source: Starlight Astro Build

Content Format#

Supports Markdown, Markdoc, and MDX:

---
title: Getting Started
description: Learn how to use this library
---

# Getting Started

Install the package:

```bash
npm install my-library

Frontmatter features:

• Table of contents generation
• Sidebar customization
• Edit page links (GitHub)
• Previous/next page navigation

Source: DEV - Complete Guide to Astro Starlight

Customization#

Theme customization:

// astro.config.mjs
export default defineConfig(`{
  integrations: [
    starlight({
      title: 'My Docs',
      customCss: ['./src/styles/custom.css'],
      sidebar: [
        { label: 'Guides', autogenerate: { directory: 'guides' }` },
      ],
    }),
  ],
});

Component overrides: Replace default components with custom ones.

Build Performance#

• Fast builds: Inherits Astro’s build speed (Vite-based)
• Memory: Low memory footprint
• SSR by default: Pages rendered server-side to HTML

Comparison: Similar speed to VitePress, faster than Docusaurus.

Source: Adam Sedwick - Starlight for Design System Docs

Best For#

• Documentation sites needing beautiful default design
• Projects prioritizing performance
• Multi-language documentation
• Teams wanting Astro’s flexibility

Limitations#

• Docs-focused (not general-purpose like Astro)
• Younger project (less battle-tested)
• Smaller community than Docusaurus/VitePress

Source: DEV - VitePress vs Astro Starlight

Performance Benchmarks#

Build Speed Comparison#

Real-world benchmarks for building sites with varying page counts:

Source: CSS-Tricks - Comparing SSG Build Times

Memory Usage#

Note: Memory usage varies based on image processing, content complexity, and plugins.

Runtime Performance (Page Load)#

Factors:

• HTML size: Content-heavy pages increase HTML
• JS size: React/Vue SPA hydration adds JS
• First load: Time to interactive on slow connection

Trade-Off Analysis#

Speed vs Features#

Trade-off: Hugo/Eleventy are fast but lack React/Vue components. Next.js/Docusaurus/Gatsby are feature-rich but slower to build.

Sweet spot: Astro, VitePress, Starlight offer good balance.

Simplicity vs Power#

Trade-off: Jekyll/Eleventy are simple to set up but limited in power. Next.js/Gatsby are powerful but have steep learning curves.

Framework Lock-in#

Migration difficulty: Moving away from React/Vue-based SSGs requires rewriting components. Hugo/Eleventy use standard Markdown, making migration easier.

Ecosystem Maturity#

Future-proofing: Astro is rapidly growing. Gatsby’s momentum has slowed. Jekyll is stable but declining in popularity.

Summary Table: Choosing an SSG#

Additional Resources#

• CloudCannon - Top 5 SSGs for 2025
• Hygraph - Top 12 SSGs 2025
• Bejamas - Cloudflare Pages vs Netlify vs Vercel
• BCMS - SSG vs SSR 2026

S2-Comprehensive: Research Approach#

Objective#

Provide deep technical analysis of 9 major static site generators covering architecture, performance, features, and trade-offs.

Methodology#

1. Architecture Analysis#

For each SSG, document:

• Core technology (Go, JavaScript, Ruby)
• Template engine
• Build system
• Rendering approach (SSG, SSR, ISR, hybrid)
• Content organization

2. Performance Benchmarking#

Collect data on:

• Build times (100, 1000, 10,000 pages)
• Memory usage
• Hot reload speed
• Production page load time

Sources: GitHub performance issues, blog benchmarks, real-world reports

3. Feature Comparison Matrix#

Compare features across SSGs:

• MDX support
• Component frameworks (React, Vue, multi-framework)
• i18n (internationalization)
• Versioning
• Search
• Image optimization
• Dark mode
• TypeScript support

4. Ecosystem Assessment#

Evaluate:

• Plugin/integration count
• Theme availability
• Community size
• Documentation quality
• CMS integrations

5. Trade-Off Analysis#

Identify trade-offs:

• Speed vs features
• Simplicity vs power
• Framework lock-in
• Ecosystem maturity

Research Sources#

• Official documentation (architecture, features)
• GitHub repositories (stars, activity, issues)
• Performance issue threads (memory leaks, build time problems)
• Migration guides (insights into difficulties)
• Real-world blog posts (hands-on experience)

Deliverable Structure#

Single comprehensive README.md organized by SSG with:

• Architecture overview
• Performance characteristics
• Templating system
• Content management
• Ecosystem
• Best use cases
• Limitations

Final sections:

• Performance benchmarks table
• Trade-off analysis
• Summary comparison table

S2-Comprehensive: Technical Recommendations#

Architecture Recommendations#

Best Modern Architecture: Astro Islands#

Why Islands Architecture wins:

• Zero JS by default (best performance)
• Selective hydration (only interactive components load JS)
• Framework-agnostic (mix React, Vue, Svelte)
• No monolithic bundle (heavy widget doesn’t block light nav)

Runners-up:

• Hugo: Compiled binary (fastest, but no component model)
• Next.js: Hybrid rendering (powerful but heavyweight)

Best for Scale: Hugo#

Only SSG that handles 10,000+ pages without OOM:

• 10K pages in 20 seconds
• Memory: ~500 MB (vs Gatsby 4+ GB)
• Linear scaling

Best Hybrid: Next.js ISR#

Incremental Static Regeneration bridges static and dynamic:

• Pages pre-rendered at build
• Background revalidation on schedule
• No full rebuild for content updates

Caveat: Requires Node.js server (not pure static)

Performance Recommendations#

By Site Size#

By Priority#

Feature Recommendations#

Documentation Sites#

Tier 1: Starlight

• Beautiful out-of-the-box
• Fast (Astro-based)
• Built-in search, i18n, versioning

Tier 2: VitePress (Vue), Hugo (scale)

Avoid: Docusaurus for 1000+ pages (memory issues)

Multi-Language Sites#

Best: Hugo

• First-class i18n
• Fastest builds for multiple locales
• RTL support built-in

E-commerce Catalogs#

Best: Next.js with ISR

• Static product pages
• Update prices without rebuild
• Hybrid checkout (SSR)

Alternative: Hugo (static catalog only, webhook rebuilds)

Ecosystem Recommendations#

Most Mature: Hugo, Next.js#

• Large communities
• Extensive themes/plugins
• Corporate backing

Fastest Growing: Astro#

• 113 releases in 2025
• 18% adoption rate
• 200+ integrations

Declining: Gatsby, Jekyll#

• Gatsby: Sunset Gatsby Cloud, minimal maintenance
• Jekyll: Ecosystem stagnation

Strategic Recommendation#

For new projects starting in 2026:

1. Default to Astro unless you have specific constraints

   • Best modern architecture
   • Growing ecosystem
   • Excellent performance

2. Choose Hugo if:

   • Site has 1000+ pages
   • Build speed is critical
   • Simple content (blogs, docs)

3. Choose Next.js if:

   • Heavily invested in React
   • Need ISR for dynamic content
   • Accept slower builds for ecosystem

4. Never choose Gatsby

   • Ecosystem dying
   • Plugin failures
   • Better alternatives exist (Astro, Next.js)

S3-Need-Driven: Use Case Recommendations#

Purpose: Match static site generators to specific project types and requirements.

Table of Contents#

1. Blogs and Personal Sites
2. Documentation Sites
3. Marketing and Landing Pages
4. E-commerce and Product Sites
5. Multi-language Sites
6. Large-Scale Sites (1000+ Pages)
7. Enterprise Portals
8. Agency/Client Work
9. Decision Matrix

Blogs and Personal Sites#

Requirements#

• Simple content workflow (write Markdown, publish)
• Low maintenance overhead
• Fast build times
• SEO-friendly
• Optional commenting system
• RSS/Atom feeds
• Tag/category organization

Recommended SSGs#

Best Choice: Hugo#

Why Hugo:

• Speed: Builds 1000-post blog in <2 seconds
• Batteries included: RSS, sitemap, taxonomy support built-in
• Themes: 300+ blog themes available
• Content organization: Flexible taxonomy system (categories, tags, custom)
• Markdown: Standard Markdown + shortcodes for rich content

Example workflow:

hugo new posts/my-post.md
# Edit content
hugo server  # Live preview
hugo         # Build in <1s

When not Hugo:

• Need React/Vue components → Use Astro
• Already on GitHub Pages with Jekyll → Stay with Jekyll
• Want maximum templating flexibility → Use Eleventy

Documentation Sites#

Requirements#

• Versioning support
• Search functionality
• Sidebar navigation
• Code syntax highlighting
• Multi-language support (i18n)
• API reference integration
• Responsive design

Recommended SSGs#

Best Choice: Starlight (for new projects)#

Why Starlight:

• Out-of-the-box beauty: No custom CSS needed
• Fast builds: Vite-powered, Astro Islands
• Framework flexibility: Use React, Vue, Svelte where needed
• Accessibility: WCAG AA compliant by default
• Search: Built-in Pagefind search
• Dark mode: Automatic theme switching

Example:

npm create astro@latest -- --template starlight

When to choose alternatives:

• VitePress: Vue ecosystem project
• Docusaurus: React ecosystem, need advanced versioning (v1, v2, v3, etc.)
• Hugo: Massive docs site (5000+ pages), need fastest possible builds

Anti-pattern: Docusaurus for large docs#

Warning: Docusaurus has known memory issues with 1000+ pages.

Symptoms:

• Build times >5 minutes for 500 pages
• OOM errors on large docs
• Memory grows with i18n locales

Better choice: Hugo (for scale) or Starlight (for modern DX)

Marketing and Landing Pages#

Requirements#

• Pixel-perfect design control
• Fast page loads (Core Web Vitals)
• A/B testing integration
• Analytics integration
• Form handling
• Image optimization
• CMS integration (optional)

Recommended SSGs#

Best Choice: Astro#

Why Astro:

• Performance by default: Ships zero JS, only hydrates interactive components
• Design freedom: Use any framework (React, Vue, Svelte) per component
• Image optimization: Built-in <Image> component with automatic WebP/AVIF
• CMS integrations: Official integrations with Contentful, Sanity, WordPress, Storyblok, etc.
• Islands: Heavy carousel widget doesn’t block lightweight header

Example:

---
// Hero section - static HTML
---
<section class="hero">
  <h1>Product Name</h1>
  <p>Description</p>
</section>

<!-- Interactive demo - only this loads JS -->
<ProductDemo client:visible />

<!-- Testimonials - static HTML -->
<Testimonials />

Performance result: Lighthouse 100 score, sub-1s load time

When to choose Next.js:

• Need ISR for frequently changing content (pricing, inventory)
• Already React-heavy codebase
• Require server-side auth for gated content

E-commerce and Product Sites#

Requirements#

• Product catalog pages (SKUs)
• Dynamic pricing
• Inventory updates
• Checkout integration
• Product search
• Image galleries
• Performance at scale

Recommended SSGs#

Best Choice: Next.js with ISR#

Why Next.js:

• ISR: Update product pages without full rebuild (revalidate: 60 seconds)
• Hybrid rendering: Static product pages + server-rendered cart/checkout
• Image optimization: Automatic WebP/AVIF for product images
• Commerce integrations: Shopify, Stripe, CommerceJS official integrations

Architecture:

Product pages (SKU-123) → SSG + ISR (revalidate: 60)
Cart → Client-side state
Checkout → SSR (server-rendered)
Order confirmation → SSR (server-rendered)

Real-world:

• Shopify storefront uses Next.js
• Product pages pre-rendered, update every 60s
• Cart and checkout are dynamic

When to choose Hugo:

• Static catalog only (no live inventory updates)
• Massive catalog (10,000+ products, Hugo builds in seconds)
• Rebuild trigger: Webhook on product changes, rebuild entire site

When to avoid SSG:

• Real-time inventory critical → Use SSR or SPA

Multi-language Sites#

Requirements#

• Multiple locales (en, fr, es, ja, etc.)
• Per-locale content directories
• Language switcher
• SEO (hreflang tags)
• RTL support (Arabic, Hebrew)
• Build efficiency (don’t rebuild all locales every time)

Recommended SSGs#

Best Choice: Hugo#

Why Hugo:

• Fastest i18n builds: 10,000 pages × 5 locales in ~2 minutes
• Content organization:

  content/
    en/
      posts/
        post1.md
    fr/
      posts/
        post1.md
    es/
      posts/
        post1.md

• Language switcher: Automatic detection of translated pages
• SEO: hreflang tags generated automatically
• RTL: CSS direction switching built-in

Configuration:

[languages]
  [languages.en]
    languageName = "English"
    weight = 1
  [languages.fr]
    languageName = "Français"
    weight = 2
  [languages.ar]
    languageName = "العربية"
    languageDirection = "rtl"
    weight = 3

Build optimization:

# Build only French locale
hugo --config config.toml,config.fr.toml

When to choose Docusaurus:

• React ecosystem project
• Need versioning + i18n together
• Accept slower builds

Warning: Docusaurus memory grows sequentially with locales (known issue)

Large-Scale Sites (1000+ Pages)#

Requirements#

• Fast builds (avoid 30-minute CI times)
• Low memory usage (avoid OOM errors)
• Incremental builds (only rebuild changed pages)
• Efficient asset processing

Recommended SSGs#

Only Choice: Hugo#

Why Hugo is the only option:

• 10-100x faster than JS-based SSGs
• 10x less memory than React/Vue SSGs
• Scales linearly (10k pages = 10x time of 1k pages)
• No OOM errors even with 100k pages

Real-world example:

• Site with 339,000+ pages builds in <45 minutes with Hugo
• Same site would OOM with Gatsby/Docusaurus at 10,000 pages

Incremental builds:

hugo --gc --minify --cacheDir .cache --cleanDestinationDir

When scale matters, Hugo is non-negotiable.

Alternatives:

• Next.js with ISR: If you need React and can accept 10x slower builds
• Astro: If site is <5000 pages and you need modern framework features

Avoid:

• Docusaurus (OOM at 1000+ pages)
• Gatsby (OOM at 1000+ pages, declining ecosystem)

Enterprise Portals#

Requirements#

• SSO/SAML integration
• Role-based access control (RBAC)
• Audit logging
• Compliance (GDPR, HIPAA)
• On-premise deployment
• Versioned documentation
• Knowledge base

Recommended SSGs#

Best Choice: Hugo + Nginx/Apache Auth#

Why Hugo:

• Static files: No server-side vulnerabilities
• On-premise: Deploy to internal servers, no external dependencies
• Compliance: Static HTML = minimal GDPR/HIPAA concerns
• Auth: Integrate with Nginx/Apache basic auth, LDAP, SAML via reverse proxy
• Audit: Web server logs track access

Architecture:

User → Nginx (SAML SSO) → Hugo Static Files
                ↓
         Audit Logs (ELK Stack)

Example Nginx config:

location / {
  auth_request /auth;
  root /var/www/hugo-site;
}

location /auth {
  proxy_pass http://sso-service;
}

When to choose Docusaurus:

• React developers on team
• Need advanced versioning UI
• Accept slower builds

Why not Next.js:

• Node.js runtime: More attack surface
• Deployment complexity: Requires Node server
• SSG mode only: ISR requires server, not suitable for SSG-only enterprises

Agency/Client Work#

Requirements#

• Fast iteration (client feedback loops)
• Low hosting costs
• Easy client handoff
• CMS for non-technical editors
• Theme/template reusability
• Quick setup (<1 day per project)

Recommended SSGs#

Best Choice: Hugo + Forestry/NetlifyCMS#

Why Hugo:

• Fast iteration: 1-second builds = instant preview for client
• Themes: 300+ themes, many client-ready
• Hosting: $0 (Netlify/Cloudflare Pages free tier)
• CMS: Forestry.io or NetlifyCMS for content editing
• Handoff: Single binary + content folder, no Node/Ruby dependencies

Workflow:

1. hugo new site client-project
2. Add theme (hugo-theme-bootstrap)
3. Configure NetlifyCMS
4. Deploy to Netlify (git push)
5. Client edits via CMS UI
6. Builds automatically on save

Client value proposition:

• Fast: Changes appear in seconds
• Cheap: $0-5/month hosting
• No maintenance: No updates, no security patches
• Reliable: Static files = 99.99% uptime

When to choose Astro:

• Need interactive components (React product configurator)
• Client has existing Contentful/Sanity CMS
• Modern design requires component flexibility

When to choose Jekyll:

• Client wants GitHub Pages (free)
• Simple blog/portfolio
• No advanced features needed

Decision Matrix#

By Primary Requirement#

By Team Skills#

By Budget Constraints#

Anti-Patterns#

Don’t Use Gatsby for New Projects (2026)#

Reasons:

• Ecosystem momentum has slowed
• Company pivoted to Gatsby Cloud/Valhalla
• GraphQL layer adds complexity
• Memory issues on large sites
• Better alternatives exist (Astro, Next.js)

If you’re on Gatsby: Plan migration to Astro or Next.js

Don’t Use Docusaurus for Large Docs (1000+ pages)#

Reasons:

• Known memory leaks with i18n
• Build times >5 minutes for 500 pages
• OOM errors on 1000+ pages
• Hugo is 100x faster

If you’re on Docusaurus with large docs: Migrate to Hugo or Starlight

Don’t Use Jekyll for Performance-Critical Projects#

Reasons:

• Slower builds than Hugo/Astro/Eleventy
• Ruby dependency (setup friction)
• Declining ecosystem activity

When Jekyll is OK: GitHub Pages, simple blogs, existing Jekyll projects

Summary Recommendations#

Universal truth: Hugo is the safe, fast choice for almost any static site. The question is whether you need framework features (React/Vue components) badly enough to accept 10-100x slower builds.

S3-Need-Driven: Research Approach#

Objective#

Match static site generators to specific project types and real-world use cases.

Methodology#

1. Identify Key Use Cases#

Categorize projects by:

• Content type: Blogs, documentation, marketing, e-commerce
• Scale: Small (<100 pages), medium (100-1000), large (1000+)
• Team: Solo, agency, enterprise
• Requirements: Speed, i18n, versioning, CMS integration

2. Define Requirements Per Use Case#

For each use case, list:

• Must-have features
• Performance requirements
• Content workflow needs
• Deployment constraints
• Budget limitations

3. Map SSGs to Use Cases#

Evaluate each SSG against use case requirements:

• Feature alignment
• Performance fit
• Ecosystem support
• Team skill match

4. Identify Anti-Patterns#

Document common mismatches:

• Using Gatsby for large sites (OOM issues)
• Using Docusaurus for non-docs projects
• Using Jekyll for performance-critical projects

5. Decision Matrix#

Create matrices for:

• Use case → recommended SSG
• Team skills → best SSG
• Budget → hosting + SSG choice

Use Cases Analyzed#

1. Blogs and Personal Sites
2. Documentation Sites
3. Marketing and Landing Pages
4. E-commerce and Product Sites
5. Multi-language Sites
6. Large-Scale Sites (1000+ pages)
7. Enterprise Portals
8. Agency/Client Work

Research Approach#

• Synthesize findings from S1 and S2
• Apply performance benchmarks to use cases
• Consider real-world constraints (budget, skills, timeline)
• Validate against known success/failure stories

Deliverable#

Comprehensive use case guide with:

• Requirements table per use case
• Recommended SSG with rationale
• Alternative choices
• Anti-patterns to avoid
• Decision matrices

S3-Need-Driven: Use Case Recommendations#

Primary Recommendations by Use Case#

Blogs and Personal Sites → Hugo#

Why Hugo:

• Fastest builds (1000-post blog in <2s)
• Batteries included (RSS, sitemap, taxonomy)
• 300+ blog themes
• Low maintenance

Alternative: Eleventy (flexibility), Astro (modern DX)

Documentation Sites → Starlight#

Why Starlight:

• Beautiful out-of-the-box design
• Fast builds (Astro/Vite)
• Built-in search, i18n, dark mode
• Framework flexibility

Alternatives: VitePress (Vue), Hugo (scale 5000+ pages)

Avoid: Docusaurus for 1000+ pages (memory issues)

Marketing and Landing Pages → Astro#

Why Astro:

• Islands Architecture (zero JS by default)
• Pixel-perfect control (any framework)
• CMS integrations (20+)
• Lighthouse 100 scores

Alternative: Next.js (if React + ISR needed)

E-commerce → Next.js with ISR#

Why Next.js ISR:

• Static product pages (fast)
• Background updates (no full rebuild)
• Hybrid checkout (SSR)
• Commerce integrations (Shopify, Stripe)

Alternative: Hugo (static catalog only)

Multi-language → Hugo#

Why Hugo:

• First-class i18n (per-locale builds)
• Fastest for multiple locales
• RTL support built-in
• Efficient content organization

Alternative: Astro (good i18n, modern DX)

Large-Scale (1000+ pages) → Hugo#

Why Hugo is the only choice:

• 10,000 pages in 20 seconds
• 500 MB memory (vs Gatsby/Docusaurus OOM)
• Linear scaling

No alternative for sites >1000 pages without accepting slow builds or OOM risk

Enterprise Portals → Hugo#

Why Hugo:

• Static files (security)
• On-premise deployment (no external deps)
• Integrate with SSO via reverse proxy
• Compliance-friendly (GDPR, HIPAA)

Alternative: Docusaurus (React ecosystem, accept slower builds)

Agency/Client Work → Hugo#

Why Hugo:

• Fast iteration (1s builds = instant preview)
• Cheap hosting ($0-5/month)
• Easy client handoff (single binary)
• CMS integration (Forestry, NetlifyCMS)

Alternative: Astro (modern clients, interactive features)

Decision Framework#

By Primary Constraint#

By Team Skills#

By Project Timeline#

Universal Truth#

Hugo is the safe, fast choice for almost any static site.

The question is whether you need framework features (React/Vue components) badly enough to accept 10-100x slower builds.

If yes → Choose Astro (best modern alternative) If no → Choose Hugo (fastest, most mature)

Critical Anti-Patterns to Avoid#

1. Gatsby for any new project - Ecosystem dead
2. Docusaurus for 1000+ pages - Memory issues
3. Jekyll for performance-critical - Slow builds
4. Next.js pure export - Misses ISR benefits

S4-Strategic: Long-Term Viability Analysis#

Purpose: Assess the strategic risk of adopting each SSG for long-term projects (3-5 years+).

Table of Contents#

1. Community Health Metrics
2. Corporate Backing vs Community-Driven
3. Breaking Change Frequency
4. Migration Difficulty
5. Ecosystem Lock-In
6. Long-Term Risk Assessment
7. Future-Proofing Recommendations

Community Health Metrics#

Hugo#

Assessment: ✅ Healthy

Hugo continues to receive frequent updates with new features in 2024-2025 including:

• LaTeX and TeX typesetting
• Server-side math rendering with KaTeX
• “Million pages release” with streaming builds
• Content adapters for remote data sources
• Tailwind support
• Obsidian-style callouts

Source: CloudCannon - Top Five Static Site Generators 2025

Astro#

Assessment: ✅✅ Exceptionally healthy

Astro is the fastest growing web framework in both usage and satisfaction according to Netlify’s 2025 developer survey.

Growth trajectory:

• GitHub stars: 500 (2020) → 40,000 (2024) → 48,000+ (2026)
• Team of core maintainers continues to grow
• Major releases: View Transitions API, Content Layer API, Starlight theme, v5.0, v6.0 alpha

2026 outlook: v6 major release planned for early 2026 with new features from 2025 experimental flags

Sources:

• DEV - The Rise of Astro.js in 2025
• Astro - 2025 Year in Review
• The New Stack - Astro’s Journey from SSG to Next.js Rival

Next.js#

Assessment: ✅✅ Exceptionally healthy

Next.js is the largest React SSG/framework with strong corporate backing from Vercel. Continuous development and major version releases.

Docusaurus#

Assessment: ✅ Healthy (with caveats)

Docusaurus is actively maintained by Meta, but faces competition from newer docs frameworks (Starlight, VitePress). v3 upgrade (MDX v3) introduced significant breaking changes.

VitePress#

Assessment: ✅ Healthy

VitePress is officially maintained by the Vue.js team as a spiritual successor to VuePress. Stable and actively developed.

Jekyll#

Assessment: ⚠️ Declining but stable

Jekyll remains functional and works well for simple blogs and GitHub Pages, but faces “healthy competition” from faster, more feature-rich alternatives.

Market position: Jekyll powers GitHub Pages (millions of sites), ensuring it won’t disappear, but ecosystem growth has stagnated.

Source: Kinsta - Top 5 Static Site Generators in 2026

Gatsby#

Assessment: 🚨 Declining, avoid for new projects

Critical issues:

1. Acquisition and team departures: Netlify acquired Gatsby Inc. in 2023. Gatsby Cloud was sunset, and only one original Gatsby employee remains. Not enough maintainers to build new features.

2. Plugin support failures: In January 2025, gatsby-source-shopify plugin broke due to API version sunset with breaking changes not reflected in the plugin. Merchants using this plugin could no longer build their sites.

3. Development essentially stopped: Characterized as a “dead framework” with stagnant ecosystem.

4. Massive community decline: GitHub traffic shows developers slowly moving away from the framework.

5. Market position: Only 0.5% of top 1M sites vs Next.js at 2.1%.

Recommendation: ❌ Do not start new Gatsby projects. Plan migration for existing Gatsby sites.

Sources:

• Bejamas - Gatsby is Going Down
• GitHub Discussion - Is GatsbyJS Officially Dead?
• Encircle Technologies - Gatsby in 2025
• ikius - Is Gatsby.js Dead?

Eleventy#

Assessment: ✅ Healthy but dependent on creator

Eleventy is actively maintained with a dedicated creator, but lacks corporate backing. Risk: dependent on single maintainer’s availability.

Starlight#

Assessment: ✅✅ Healthy and rising

As part of the Astro ecosystem, Starlight benefits from Astro’s rapid growth and active development team.

Corporate Backing vs Community-Driven#

Corporate-Backed (Lower bus factor risk)#

Community-Driven (Higher bus factor risk)#

Acquired/Sunset (Highest risk)#

Key insight: Corporate backing reduces bus factor risk, but community-driven projects with healthy ecosystems (Astro, Eleventy) are also viable long-term.

Breaking Change Frequency#

Low Breaking Change Frequency (Stable APIs)#

Hugo ⭐

• Upgrade path: Smooth
• Breaking changes: Rare, well-documented
• Philosophy: Backward compatibility prioritized
• Risk: 🟢 Low

Eleventy

• Upgrade path: Smooth
• Breaking changes: Rare, minimal impact
• Philosophy: Zero-config, simple
• Risk: 🟢 Low

Moderate Breaking Change Frequency#

Astro

• Upgrade path: Major versions (v4 → v5 → v6) with breaking changes
• Frequency: Annual major releases
• Mitigation: Excellent migration guides, experimental flags for testing
• Philosophy: Move fast, but provide migration paths
• Risk: 🟡 Medium

Next.js

• Upgrade path: Major versions with breaking changes (Pages Router → App Router)
• Frequency: Major releases every 1-2 years
• Mitigation: Codemods, migration guides
• Philosophy: Rapid innovation, sometimes at cost of stability
• Risk: 🟡 Medium

VitePress

• Upgrade path: Stable, occasional breaking changes
• Frequency: Low
• Philosophy: Focused on docs, stability prioritized
• Risk: 🟢 Low

High Breaking Change Frequency (Ecosystem churn)#

Docusaurus ⚠️

• v2 → v3 breaking change: MDX v1 → MDX v3 upgrade
• Impact: Major - many sites failed to compile after upgrade
• Common issues:
  • {expression} must be valid JavaScript (MDX v3 stricter)
  • <link> autolink syntax no longer supported
  • ES Modules only (no CommonJS require())
  • Prettier doesn’t support MDX v3 yet
• Migration tool: npx docusaurus-mdx-checker to find failing files
• Risk: 🟡 Medium-High

Source: Docusaurus - Upgrading to v3

Gatsby 🚨

• v4 → v5 breaking changes: React 18, Node 18+, GraphQL updates
• Issue: Low community support for migrations (declining ecosystem)
• Risk: 🔴 High (avoid new projects)

Source: Gatsby - Migrating from v4 to v5

Migration Difficulty#

Easy Migrations (Content-Portable)#

From Jekyll/Hugo/Eleventy → Any SSG

• Difficulty: 🟢 Easy
• Why: Standard Markdown content, minimal framework-specific features
• Effort: 4-8 hours for small sites
• Approach: Copy Markdown, rewrite templates

Moderate Migrations#

Gatsby → Astro

• Difficulty: 🟡 Moderate
• Challenges:
  • GraphQL → ESM imports/getCollection()
  • React SPA → Multi-page site
  • Plugin replacements
• Effort: 1-2 days for medium sites
• Build time improvement: Gatsby triples duration vs Astro (~30s for Astro)

Source: Astro Docs - Migrating from Gatsby

Gatsby → Next.js

• Difficulty: 🟡 Moderate
• Challenges:
  • GraphQL data fetching → getStaticProps/Server Components
  • createPages API → Next.js file-based routing
  • Plugin ecosystem → DIY or find Next.js equivalents
• Effort: 4-8 hours with foundation-first approach
• Outcome: Clean codebase, better performance

Real-world report: “After restarting with the foundation-first approach, the migration took about 4 hours total. The resulting codebase is clean, follows Next.js best practices, and actually performs better than the original Gatsby site.”

Sources:

• Rob Marshall - Why My Gatsby to Next.js Migration Failed
• Marco Heine - Migrating from Gatsby to Next.js
• Flotiq - From Gatsby to Next.js

Difficult Migrations#

Docusaurus → Hugo/Astro

• Difficulty: 🔴 Difficult
• Challenges:
  • React components in MDX → Rewrite or find alternatives
  • Docusaurus-specific plugins → Recreate functionality
  • Versioning system → Manual implementation or switch to VitePress
• Effort: 1-2 weeks for large docs sites

Next.js → Hugo

• Difficulty: 🔴 Very Difficult
• Challenges:
  • React components → Go templates (complete rewrite)
  • Dynamic features (ISR, SSR) → Static only or remove
  • JavaScript interactivity → Vanilla JS or remove
• Effort: Complete rewrite (weeks)

Ecosystem Lock-In#

Low Lock-In (Easy to Migrate)#

Strategy: Keep content in standard Markdown, minimize framework-specific features.

Moderate Lock-In#

Strategy: Separate content from presentation. Use framework features sparingly.

High Lock-In (Difficult to Migrate)#

Gatsby lock-in: GraphQL data layer is unique to Gatsby. Migration requires:

1. Rewrite all GraphQL queries
2. Replace Gatsby-specific plugins
3. Restructure data fetching

Docusaurus lock-in: Versioning system, plugin architecture, MDX components tightly coupled.

Long-Term Risk Assessment#

Low Risk (Safe for 5+ Year Projects)#

Medium Risk (Safe for 2-3 Year Projects)#

High Risk (Avoid for New Projects)#

Future-Proofing Recommendations#

For New Projects (2026+)#

1. Default choice: Astro

   • Rapid growth, modern architecture, multi-framework
   • Low risk, high upside

2. If speed critical: Hugo

   • Mature, stable, fastest builds
   • Zero lock-in risk

3. If React ecosystem: Next.js

   • Largest React framework, Vercel-backed
   • Accept lock-in cost for ecosystem benefits

4. If documentation: Starlight

   • Modern, beautiful, fast
   • Backed by Astro team

For Existing Projects#

If you’re on Gatsby:

• Action: Plan migration to Astro or Next.js
• Timeline: Within 6-12 months
• Priority: High (ecosystem declining)

If you’re on Docusaurus (large site >1000 pages):

• Action: Evaluate Hugo or Starlight
• Timeline: When build times become painful
• Priority: Medium

If you’re on Jekyll:

• Action: If it works, keep it (low risk)
• Consider: Hugo if you need speed
• Priority: Low (GitHub Pages ensures longevity)

If you’re on Hugo, Astro, Next.js, VitePress:

• Action: Stay the course
• Priority: None (healthy ecosystems)

Content Architecture Best Practices#

Minimize lock-in regardless of SSG choice:

1. Standard Markdown: Use standard Markdown/MDX, avoid framework-specific extensions
2. Separate content from presentation: Keep content in /content or /posts, not in component files
3. Limit framework features: Use framework features where necessary, but keep core content portable
4. Document custom features: If you use framework-specific features, document them for future migration
5. Test migration: Periodically test migrating 10% of content to alternative SSG to ensure portability

Summary: Strategic Viability Matrix#

Conclusion: Safe Bets for 2026+#

Recommended for long-term projects:

1. Hugo - Safest choice, zero risk
2. Astro - Best modern choice, high growth
3. Next.js - React ecosystem leader
4. VitePress - Vue ecosystem leader

Avoid:

• Gatsby - Ecosystem collapsing, migrate ASAP

Monitor:

• Jekyll - Declining but stable due to GitHub Pages
• Docusaurus - Facing competition, breaking changes

Emerging winner:

• Astro - Fastest growing, best positioned for 2026+

S4-Strategic: Research Approach#

Objective#

Assess long-term viability and strategic risk of adopting each SSG for 3-5 year projects.

Methodology#

1. Community Health Metrics#

Collect quantitative data:

• GitHub stars (popularity)
• Release frequency (active development)
• Weekly downloads (adoption)
• Issue response time (maintainer engagement)
• Contributor count (bus factor)

Sources: GitHub API, npm trends, package registries

2. Corporate Backing Assessment#

Evaluate organizational support:

• Funding status (VC-backed, bootstrapped)
• Company ownership (Vercel, Meta, Vue team)
• Historical stability (acquisitions, pivots)
• Team size and growth

Risk factors: Single maintainer, recent acquisition, funding issues

3. Breaking Change Analysis#

Review upgrade paths:

• Major version breaking changes (frequency, severity)
• Migration guide quality
• Community support during upgrades
• Backward compatibility philosophy

Sources: CHANGELOG, migration docs, GitHub discussions

4. Migration Difficulty Assessment#

Evaluate ease of switching SSGs:

• Content portability (Markdown vs proprietary)
• Template complexity (standard vs framework-specific)
• Plugin dependencies
• Data layer complexity (GraphQL lock-in)

Real-world data: Migration blog posts, time estimates

5. Ecosystem Lock-In Evaluation#

Assess vendor lock-in risk:

• Framework specificity (React, Vue, or agnostic)
• Custom syntax (Astro components, Hugo shortcodes)
• Plugin ecosystem dependence
• Content format (standard Markdown or MDX/framework-specific)

6. Long-Term Risk Modeling#

Synthesize into risk assessment:

• Low risk (5+ years safe): Hugo, Next.js, Astro
• Medium risk (2-3 years): Eleventy, Docusaurus
• High risk (avoid): Gatsby, Jekyll (declining)

Research Sources#

• GitHub metrics and activity logs
• Company announcements (acquisitions, product changes)
• Community discussions (sentiment, concerns)
• Migration experience reports
• Breaking change documentation

Red Flags Identified#

• Gatsby: Acquisition, team departures, plugin failures
• Docusaurus: MDX v3 breaking changes
• Jekyll: Declining activity, stagnant ecosystem

Green Flags Identified#

• Astro: Rapid growth, 113 releases in 2025
• Hugo: Mature, stable, consistent updates
• Next.js: Vercel-backed, massive adoption

Deliverable#

Comprehensive strategic analysis with:

• Community health scorecards
• Corporate backing matrix
• Breaking change frequency analysis
• Migration difficulty matrix
• Lock-in risk assessment
• 5-year viability predictions

S4-Strategic: Long-Term Recommendations#

Safe Long-Term Bets (5+ Years)#

Tier 1: Very Low Risk#

Hugo

• Confidence: 95%
• Backing: Google sponsorship, large maintainer team
• Community: 86K stars, frequent releases
• Risk: Minimal - most mature SSG

Next.js

• Confidence: 95%
• Backing: Vercel (VC-funded), core to their business
• Community: 125K stars, 6M weekly downloads
• Risk: Minimal - React ecosystem leader

Astro

• Confidence: 90%
• Backing: Growing core team, MIT license
• Community: 48K stars, fastest growing (18% adoption)
• Risk: Low - exceptional growth trajectory

VitePress

• Confidence: 90%
• Backing: Official Vue.js team project
• Community: 12K stars, active development
• Risk: Low - official Vue project ensures longevity

Medium-Term Safe (2-3 Years)#

Eleventy

• Confidence: 80%
• Risk: Single-maintainer dependency
• Mitigation: Zach Leatherman is dedicated, healthy community

Docusaurus

• Confidence: 75%
• Risk: Facing competition from Starlight/VitePress
• Mitigation: Meta-backed, large existing user base

Starlight

• Confidence: 85%
• Risk: Young project (2023)
• Mitigation: Backed by Astro team, rapid growth

High Risk - Avoid New Projects#

Gatsby

• Confidence: 0% - AVOID
• Status: Ecosystem collapsing
• Evidence:
  • Netlify acquired, Gatsby Cloud sunset
  • Only 1 original employee remains
  • Plugin failures (gatsby-source-shopify broke Jan 2025)
  • Community exodus (0.5% market share vs Next.js 2.1%)

Action: Migrate existing Gatsby sites to Astro or Next.js within 6-12 months

Jekyll

• Confidence: 60%
• Status: Declining but GitHub Pages ensures survival
• Evidence: Stagnant ecosystem, slow builds
• Safe for: Simple blogs on GitHub Pages
• Migrate if: Need performance or modern features

Strategic Recommendations#

For New Projects in 2026#

1. Default: Astro

   • Best growth trajectory
   • Modern architecture
   • Low long-term risk

2. If speed critical: Hugo

   • Zero risk
   • Most mature
   • Fastest builds

3. If React ecosystem: Next.js

   • Vercel-backed
   • Largest community
   • Accept React lock-in

4. If Vue ecosystem: VitePress

   • Official Vue project
   • Safe long-term

For Existing Projects#

Critical Priority: Gatsby Sites

• Timeline: 6-12 months
• Target: Astro (modern) or Next.js (React ecosystem)
• Reason: Ecosystem dying, plugin failures increasing

Medium Priority: Docusaurus (Large Sites)

• Timeline: When build times become painful
• Target: Hugo (scale) or Starlight (modern)
• Reason: Memory issues at 1000+ pages

Low Priority: Jekyll

• Action: Stay if it works (GitHub Pages ensures longevity)
• Consider: Hugo for speed improvements
• Timeline: No urgency

No Action: Hugo, Astro, Next.js, VitePress

• Healthy ecosystems
• Stay the course

Future-Proofing Strategies#

Minimize Lock-In#

1. Use standard Markdown - Avoid framework-specific extensions
2. Separate content from presentation - Keep content portable
3. Document framework features - Track what needs migration
4. Limit framework-specific features - Use sparingly
5. Test migration - Periodically verify content portability

Content Architecture#

/content/           ← Standard Markdown (portable)
/templates/         ← Framework-specific (needs rewrite if migrating)
/components/        ← Framework-specific (needs rewrite if migrating)

Goal: 80% of work (content) is portable, 20% (templates) is framework-specific

Migration Priority Matrix#

2026 Emerging Winner: Astro#

Why Astro is best positioned for the future:

1. Fastest growth: 113 releases in 2025, 18% adoption
2. Modern architecture: Islands Architecture is the future
3. Framework-agnostic: Not locked to React/Vue
4. Strong team: Growing core maintainer team
5. Community momentum: Netlify survey: fastest growing framework

Prediction: By 2028, Astro will be the default recommendation for most static sites, with Hugo remaining the speed champion and Next.js dominating React-specific projects.

Final Recommendation#

Start with Astro.

It offers the best balance of:

• Long-term viability (low risk)
• Modern architecture (future-proof)
• Developer experience (high productivity)
• Performance (zero JS by default)
• Flexibility (multi-framework)

Exception: Choose Hugo if site scale (1000+ pages) or build speed is non-negotiable.