Scoring SSG Long-Term Maintenance Risk

Generator comparisons are usually written at the moment of choice: build speed, features, developer experience today. The costs that dominate a site's life arrive later. A documentation site chosen in 2019 has, by now, been through several major versions of its generator, lost a plugin or two to abandonment, fought a Node or Ruby upgrade, and possibly migrated to another generator altogether. Those costs are predictable from signals available on the day of choice, if you look for them.

This guide scores five-year maintenance risk for a generator and a specific site plan across five areas — project health, upgrade history, dependency surface, plugin reliance, and exit cost — and calibrates the scoring against the actual maintenance hours of eight sites the author's teams have run. It is part of SSG Framework Selection Matrix, complementing the cost view in Total Cost of Ownership for Static Site Generators.

Prerequisites

• A shortlist of generators and a rough site plan: content types, plugins you expect to need, hosting.
• Access to each project's repository, release notes and migration guides.
• Maintenance records from your own past sites, if you have them, to calibrate.

The Calibration Data

Eight sites, between three and seven years old, with maintenance time logged (upgrades, dependency fixes, plugin replacements, migrations; content work excluded):

The pattern was clearer than expected: hours per year tracked the number of third-party plugins far more closely than the choice of generator itself. The Gatsby site's 24 plugins, several abandoned when Gatsby's momentum faded, made it the most expensive by a wide margin and forced a migration; the full story is in Migrating from Gatsby to Astro.

Area 1: Project Health (weight 20%)

Score 1 (low risk) to 5 (high risk) from signals that indicate whether the generator will be maintained for the next five years:

• Maintainers and funding. More than one active maintainer with commits in the last three months; a sustainable funding source (company backing, foundation, sponsorship covering maintainers' time).
• Release cadence. Regular releases, security fixes for the previous major version.
• Issue response. Median time to first response on bug reports.
• Adoption by organisations that will keep using it. Large documentation sites on the generator are a signal that someone will keep it alive.

Stars and weekly downloads were deliberately left out: Gatsby had both in abundance the year before its decline.

Area 2: Upgrade History (weight 20%)

Read the migration guides for the last two major versions and count breaking changes that would have affected a site like yours. Then do one real upgrade of a small sample site across the last major version and time it.

For the generators in the calibration set, upgrades across one major version on a representative sample site took: Hugo (no major versions in the traditional sense; breaking changes across 0.1xx releases handled with deprecation warnings) 1 hour; Eleventy 2 to 3 1.5 hours; Astro 3 to 4 2 hours and 4 to 5 3 hours; Docusaurus 2 to 3 (MDX 1 to 3) 9 hours; Next.js Pages to App Router not attempted as an "upgrade" because it is a rewrite.

Area 3: Dependency Surface (weight 20%)

The size of the dependency tree predicts how often upgrades are forced by something else — a vulnerable transitive package, a Node version drop, a native module that stops compiling. Count it on a freshly scaffolded site:

npm ls --all --parse | wc -l        # transitive npm packages
bundle list | wc -l                 # Ruby gems for Jekyll
hugo mod graph | wc -l              # Hugo modules (single binary otherwise)

A new Astro site had about 380 transitive packages, Eleventy about 210, Docusaurus about 1,100, Next.js about 320, Jekyll 38 gems, Hugo a single binary. Dependency count correlated with the number of Dependabot security alerts per year on the calibration sites, as described in Auditing npm Dependencies in SSG Pipelines.

Area 4: Plugin Reliance (weight 25%)

The strongest predictor in the calibration data. For your site plan, list every feature that needs a third-party plugin rather than a built-in feature or code you would own: image processing, sitemaps, feeds, search, syntax highlighting, i18n, redirects, CMS integration. For each plugin, check maintainer count, last release, and whether the same feature is built into another generator.

Score by the number of third-party plugins that would be critical to the site: 0–2 scores 1, 3–5 scores 2, 6–9 scores 3, 10–15 scores 4, more than 15 scores 5. Owning a small plugin in your own repository counts as zero — you pay for it once and it never disappears.

Area 5: Exit Cost (weight 15%)

How hard would it be to leave? Content in plain Markdown with conventional frontmatter is portable; content full of generator-specific shortcodes, MDX components, Liquid includes or data-file structures is not. Estimate the share of content files that use generator-specific syntax on a sample of your planned content. The calibration sites ranged from 4% (Hugo docs with a handful of shortcodes) to 71% (Docusaurus with MDX components on most pages). The practical cost of high exit cost is visible in Porting Shortcodes and Includes Between Generators.

Putting the Score Together

Each area is scored 1–5 and weighted. The weighted scores for the calibration sites, computed as they would have been at the time of choice, correlated with actual maintenance hours per year with a Pearson coefficient of 0.87 — good enough to rank options, not to predict hours precisely.

The score is most useful for comparing plans rather than generators. On a new documentation project, the same team scored "Astro with 11 community integrations" at 3.1 and "Astro with 3 integrations and 4 small features owned in the repository" at 1.9; the second plan was chosen, and after two years maintenance had averaged 12 hours a year.

Measured Impact

Pitfalls & Rollback

• Using popularity as health. Stars and downloads lag decline by years.
• Scoring the generator, not the plan. The same generator can be low or high risk depending on plugins.
• Ignoring exit cost. Heavy use of generator-specific syntax makes every future decision more expensive.
• Treating the score as a prediction. It ranks options; revisit it yearly with real hours.
• Rollback: the score changes nothing by itself; if an early choice scores badly, the cheapest time to change course is before content is written.

Conclusion

Five-year maintenance cost is mostly decided on day one, and the biggest lever is not which generator but how many third-party plugins the site will depend on. Score project health, upgrade history, dependency surface, plugin reliance and exit cost for each concrete plan, prefer plans that own small features instead of depending on plugins, and recheck the score annually against real maintenance hours.

FAQ

Why score maintenance risk when choosing a generator?

A documentation or marketing site often lives for five to ten years, longer than many generator versions and some generator projects. The cost of a generator over that time is dominated by upgrades, abandoned plugins and eventually migration, not by the initial build, so it is worth estimating before choosing.

Which signals best predict maintenance cost?

In the sites reviewed here, the strongest predictors were the number of third-party plugins the site depended on, the generator's history of breaking changes per major version, and the size of the transitive dependency tree. Stars and download counts predicted very little.

How do I measure a generator's upgrade history?

Read the migration guides for the last two or three major versions and count the breaking changes that would have affected your site, then check how long the previous major version kept receiving security fixes. Trying one real upgrade on a sample site is the best test.

What is exit cost?

The effort to move the site to another generator if the current one is abandoned or stops fitting. Content in plain Markdown with portable frontmatter has a low exit cost; content full of generator-specific shortcodes, components or data formats has a high one.

Related

• Parent: SSG Framework Selection Matrix — the full selection framework.
• Total Cost of Ownership for Static Site Generators — the cost side of the decision.
• SSG Selection Checklist for Engineering Teams — a practical checklist.
• Replacing Jekyll Plugins When Migrating to Eleventy — what plugin reliance costs later.
• Upgrading Jekyll and Ruby Versions Safely — upgrade history in practice.