SSG Selection Checklist for Engineering Teams

Picking a static site generator usually goes wrong the same way: a team chooses on popularity or a single blog post, then hits a wall six months later — builds that crawl, writers who can't publish, or a missing internationalization story. A checklist fixes this by forcing you to score each candidate against the constraints that actually bind your project, weighted by how much each one matters to you. This guide gives you the seven criteria engineering teams use and how to score them. It's the hands-on companion to the SSG Framework Selection Matrix, within the broader Choosing the Right Static Site Generator for Production work.

Prerequisites

• A shortlist of two to four candidate generators (commonly Astro, Eleventy, Hugo, Jekyll, or a Next.js static export).
• A representative slice of real content — at least a few dozen pages — to build a proof of concept on.
• Agreement on who the authors are (engineers, technical writers, or a mix) and roughly how many pages you'll reach.
• Access to your intended host so you can test the deploy path, not just the local build.

How to Use the Checklist

Score each candidate 1-5 on every criterion below, multiply by a weight you set (a small integer like 1-5) reflecting how much that criterion matters to your project, and sum the weighted scores. The highest total is your default choice. If two totals land within ~10% of each other, the matrix isn't deciding for you — run a proof of concept on the top two and let measured build time and hands-on authoring break the tie. The mechanics of the scoring sheet itself are covered in the SSG Framework Selection Matrix.

1. Build Scaling

How does build time grow as the page count grows? This is the criterion that quietly breaks teams a year in.

• Build your proof-of-concept slice, then duplicate the content to ~5,000 pages and time a clean build with hyperfine 'rm -rf dist && npm run build' (or hugo).
• Hugo stays in the low seconds at thousands of pages; Astro and Eleventy are fast but grow more steeply with per-page JavaScript or transforms; Jekyll is the slowest at scale.
• Score 5 for sub-10 s at your target page count, 1 for multi-minute clean builds.

For a concrete head-to-head method, see How to Benchmark Hugo vs Astro Build Speeds. Weight heavily if you'll exceed a few thousand pages; near zero for a small marketing site.

2. Team Skills

Who maintains this, and what do they already know?

• A JavaScript/React team will be productive in Astro or a Next.js export immediately; a Ruby shop has a head start with Jekyll; Hugo's Go templating is unfamiliar to most front-end engineers and has the steepest learning curve.
• Score against your team's current skills, not what they could learn — the cost of fighting an unfamiliar templating language shows up in every future change.

3. Content Model and Authoring

How is content structured, and who writes it?

• If authors are engineers, plain Markdown in Git is fine and every candidate qualifies. If authors are non-technical writers, weight a Git-backed visual editor and schema-validated frontmatter heavily — see Best SSG for Technical Writers Without Coding Experience.
• Check for typed content collections (Astro's content collections validate frontmatter against a schema at build time), data-file support, and how cleanly the tool handles structured content beyond prose.
• Score 5 when the model matches your content and catches authoring errors at build time; 1 when authors will routinely break the build.

4. Internationalization (i18n)

Will you ship more than one language now or on the roadmap?

• Look for native locale routing, per-locale builds, and a content structure that translators can work with. Astro and Hugo have first-class i18n routing; Eleventy and Jekyll lean on plugins or conventions.
• Retrofitting i18n is expensive, so if multiple languages are even plausible, weight this early. The dedicated decision is covered in Picking an SSG for a Multi-Language Documentation Site.
• Score 5 for native multi-locale routing and per-locale builds; 1 if you'd be assembling i18n from scratch.

5. Hosting and Deploy Path

Does the generator deploy cleanly to where you're hosting?

• Test the actual deploy, not just the local build: pin the runtime version, confirm the output directory, and run one preview deploy. A generator that builds locally can still trip on a host's build image.
• All four major generators deploy to Cloudflare Pages, Netlify, and Vercel; the differences are in version pinning and build-image quirks — see Deploying Hugo to Cloudflare Pages and Workers for a worked example of getting that right.
• Score 5 when a preview deploy works on the first try with version pinning; 1 when the deploy needs custom build images or workarounds.

6. Ecosystem and Integrations

What do you get for free, and what will you build?

• Inventory the plugins/integrations you need: image optimization, syntax highlighting, search, sitemaps, RSS, analytics. Astro's integration ecosystem and Jekyll's mature gem ecosystem are broad; Hugo's batteries-included core covers a lot without plugins; Eleventy is minimal but composable.
• Score by how much of your required functionality is officially supported versus something you'll maintain yourself.

7. Long-Term Maintenance

What does ownership cost over years?

• Weigh release cadence and breaking-change history, dependency surface (a Hugo single binary versus a large node_modules tree), the size and health of the community, and how often you'll be forced to migrate across major versions.
• A smaller dependency surface and a stable release history lower the long-run carrying cost even if the day-one experience is similar.
• Score 5 for a stable, well-maintained project with a small dependency surface; 1 for a tool with frequent breaking changes or a fading community.

Worked Example

A 12-person docs team with ~6,000 pages, engineer-authors, and a two-language roadmap weighted build scaling and i18n at 5, team skills (JS-heavy) at 4, and ecosystem/maintenance at 3. Scoring four candidates 1-5 and summing:

Astro and Hugo finished within ~6% of each other (103 vs 97), so the team ran a proof of concept: a hyperfine build of the 6,000-page slice came in at 4 s for Hugo and 31 s for Astro, but the JS team shipped the authoring components far faster in Astro. They chose Astro, accepting the build gap as solvable with caching. The lesson is the one the checklist is built to surface: a close total is a signal to measure, not to argue.

Pitfalls & Rollback

• Choosing on popularity: the most-starred generator is irrelevant if it scores low on your binding constraint. Trust the weighted total, not the hype.
• Equal weights: flat weights hide the trade-off that decides the choice. Always reflect real constraints in the weights.
• Scoring from docs alone: documentation claims optimistic build times and smooth authoring. Score build scaling and authoring from a proof of concept, not the README.
• Ignoring i18n until later: retrofitting locales is among the most expensive migrations. Weight it now if it's plausible.
• Skipping the real deploy: a local build that works can still fail on a host's build image. Test one preview deploy per finalist.
• Rollback: because the output is portable Markdown/HTML, a wrong choice isn't fatal — content migrates between generators. But templates, integrations, and i18n routing don't, so the checklist exists to make the right call before that cost is sunk.

Conclusion

A good SSG choice isn't about the best generator in the abstract — it's about the best fit for your build scale, your authors, your content, your languages, your host, your ecosystem needs, and your maintenance appetite. Score each candidate 1-5 across the seven criteria, weight by your real constraints, sum, and let a proof of concept settle anything close. That discipline turns a months-later regret into a defensible, written decision. To formalize the scoring sheet, continue with the SSG Framework Selection Matrix.

FAQ

What is the single most important factor when picking an SSG?

There isn't one universal factor; it's whichever criterion is your hardest constraint. For a large repo it's build scaling, for a writer-heavy team it's authoring experience, for a global product it's internationalization. The checklist exists so you weight criteria by your actual constraints instead of by popularity.

Should I weight the checklist criteria equally?

No. Assign weights that reflect your project. A team with thousands of pages should weight build scaling heavily, while a small marketing site can weight it near zero and put the weight on authoring and ecosystem instead. Equal weights hide the trade-off that actually decides the choice.

How do I score a criterion I can't measure yet?

Run a small proof of concept. Build a representative slice of real content on the top two candidates and measure build time, then score authoring and ecosystem from that hands-on experience rather than from documentation claims.

When should i18n change my SSG choice?

When you ship more than one or two languages, or expect to. Native routing, per-locale builds, and translation-friendly content structure differ sharply between generators, and retrofitting them later is expensive, so weight i18n early if it's on the roadmap.

Related

• Parent: SSG Framework Selection Matrix — the scoring sheet this checklist feeds.
• Best SSG for Technical Writers Without Coding Experience — the authoring criterion in depth.
• Picking an SSG for a Multi-Language Documentation Site — the i18n criterion in depth.
• Choosing the Right Static Site Generator for Production — the full framework for matching a generator to your constraints.