Concepts

Concepts are the guides with no single task at the end. They explain how something works or how to think about a decision, so that the how-tos make sense in context: what a static site generator really costs over five years, which signals predict maintenance pain, what a docs-as-code workflow asks of writers, where static export in Next.js stops being static.

There are fewer of them than any other kind on purpose. Most explanation on this site lives inside the how-tos and comparisons, next to the numbers that justify it; a separate concept guide exists only where the idea is large enough to need its own page and is referenced from several others.

Concepts are read before a decision; how-tos are read while carrying one out.

Docs Frameworks: Docusaurus, Starlight and VitePress

VitePress for Library DocumentationSet up VitePress docs next to a library's source: generated API reference from TypeDoc, live code samples, versioned deploys and sub-20-second builds.

The 4 topics with the most concepts, out of 4 topics that have any.

Next.js Static Export for Content Sites

Next.js App Router Static Export LimitationsWhich App Router features work with output export — route handlers, middleware, ISR, dynamic params, headers, images — and the static workaround for each.

SSG Framework Selection Matrix

Best SSG for Non-Developer Technical WritersChoose an SSG for authors who avoid the terminal — prioritize a Git-backed visual editor, schema-validated frontmatter, and cloud CI that deploys on every commit.
Choosing an SSG for API Reference DocumentationAPI docs are generated, versioned and enormous. Compare Hugo, Astro, Eleventy and Next export on build scale, schema-driven pages, versioning and search.
Choosing an SSG for a Marketing Site with Non-Technical EditorsPick a generator and editing setup for a marketing site edited by non-developers: visual editing, previews, publish speed, guardrails and page performance.
Evaluating SSG Accessibility DefaultsAudit what a generator or theme gets right and wrong for accessibility out of the box — landmarks, headings, focus, colour, code blocks — before committing.
Picking an SSG for a Multi-Language Docs SiteCompare i18n in Astro, Hugo, Eleventy, and Jekyll for multi-language documentation — routing, content organization, and build cost — with measured numbers across locales.
SSG Selection Checklist for Engineering TeamsA practical SSG selection checklist for engineering teams — score build scale, team skills, content model, i18n, hosting, ecosystem, and maintenance before you commit.
Scoring SSG Long-Term Maintenance RiskScore a static site generator’s five-year maintenance risk: project health, upgrade history, dependency surface, plugin ecosystem and your exit cost.
Total Cost of Ownership for Static Site GeneratorsEstimate the three-year cost of running a static site on Hugo, Eleventy, Astro, Next.js export or a docs framework: people time, builds, hosting, upgrades.
When a Static Site Generator Is the Wrong ChoiceThe signs a project has outgrown static generation, from per-user content to minute-level freshness and huge catalogues, and the hybrid options to use.

12 concepts in total. As a share of each section: framework selection 9%, performance 0%, deployment 1%.

Content Workflows for Documentation Teams

Docs-as-Code Review Workflow for WritersBranch naming, small pull requests, preview-first review and a two-pass checklist — a docs-as-code process that non-engineers can follow and reviewers can sustain.

Other kinds of guide

How-tosA task, end to end, with configuration and measured results.
FixesStarts from a symptom and ends at the cause and the fix.
ComparisonsWeighs two or more options against measured criteria.