ADR-001: Static Site Generator Over CMS-Driven Architecture
Why static site generation beats CMS-driven architecture for client website delivery.
Context
We needed a repeatable architecture for client websites that minimises long-term maintenance obligations without sacrificing build quality or SEO.
Decision
Use Hugo as a static site generator. Deliver client sites as pre-built HTML with no runtime dependencies, no database, and no CMS backend.
Consequences
Client sites require a build step for content updates — changes are not live instantly. Clients who need to edit their own content without touching code can use a CMS layer (CloudCannon, Decap CMS) as a separate UI concern — it writes to the same markdown files Hugo reads. The architecture does not change. Clients who rarely update content need no CMS at all.
Options Considered
Option A — WordPress The industry default. Large plugin ecosystem, familiar to clients, widely hosted. Carries a persistent maintenance obligation: core updates, plugin updates, security patches, database management. Every plugin is a future problem. Complexity compounds over time regardless of whether the site needs it.
Option B — Headless CMS + Frontend Framework Separates content management from presentation. More control over the frontend, better performance potential. Introduces two systems instead of one — a CMS API and a frontend runtime. Operational complexity increases. More moving parts means more failure surfaces.
Option C — Hugo Static Site Generator Pre-builds the entire site at deploy time. Output is pure HTML, CSS, and JS. No runtime, no database, no server-side processing. Content lives in version-controlled markdown files. Build times are fast. Hosting is trivial and cheap.
Rationale
The core question for client website delivery is not “what can this system do?” It is “what does this system demand from the client after launch?”
WordPress demands ongoing attention by design. Updates are frequent, necessary, and carry real risk if ignored. Security exposure grows with plugin count. A site left untouched for six months is a liability.
Hugo demands nothing after launch. The site is pre-built. There is no attack surface to patch, no runtime to maintain, no database to back up. A site left untouched for two years is identical to a site launched yesterday.
For small business clients — who do not have developers on staff and do not think about their website between updates — the maintenance obligation difference is the entire argument.
The CMS Layer Question
The most common objection to static sites is content editing. Clients cannot edit markdown files directly in a code editor — that requires technical knowledge most small business owners do not have and should not need.
This is a real constraint, not a dismissal.
When a client needs to edit their own content, a Git-based CMS (CloudCannon, Decap CMS) sits on top of Hugo as a separate UI layer. The client sees a visual editor. Behind the scenes, the CMS writes to the same markdown files. Hugo builds from those files exactly as before. The CMS is a UI concern — it does not change the architecture.
Most small business sites do not need this. Content updates are infrequent. The developer handles them. A CMS layer adds operational overhead for a problem that does not exist on most client engagements.
The decision is made per client, not per architecture.
Trade-offs Accepted
- Content updates require a build and deploy step — typically seconds with CI/CD, not a meaningful constraint in practice
- Highly dynamic features (user authentication, personalisation, real-time data) are out of scope by design
- Clients migrating from WordPress need expectation-setting — the editing experience is different, not worse
These trade-offs are accepted. The sites we build are not applications. They are business infrastructure — designed to be reliable, fast, and ignored.