Writing HTML by hand is easier than debugging your static site generator

Original Article ↗ Hacker News Discussion ↗

Static site generators promise templates, RSS feeds, and reusable components, but many developers find their toolchains fragile, overcomplicated, or hard to resurrect years later compared with plain hand-written HTML. Others counter that even small sites quickly need partials, consistency checks, and higher-level formats like Markdown, and that simple approaches—single-binary generators, tiny custom scripts, or CI/Docker-based builds—avoid most of the pain. The debate centers on where to place complexity: in generators, server-side includes, or client-side tricks, and how to keep personal and documentation sites maintainable without drowning in dependencies.

Hand-written HTML vs Static Site Generators (SSGs)

  • Many agree hand-writing a small site (1–4 pages) is simpler and pleasant.
  • Skeptics say this breaks down quickly with many pages, frequent posts, or multiple authors.
  • Some maintain fully manual sites even with many pages, arguing simplicity and longevity trump automation.
  • Others with large sites (hundreds–thousands of pages) insist an SSG or custom generator is essential.

Complexity, Dependencies, and Longevity

  • A recurring complaint: Jekyll/Ruby and similar stacks break over time (dependency updates, security warnings, Ruby version changes).
  • Single-binary tools (Hugo, Zola, gojekyll) are praised for avoiding language and package-manager headaches.
  • Some argue SSGs can remain stable for a decade if kept simple; others say modern toolchains are “abstraction soup” that won’t build in 10 years.
  • Several people build tiny, custom SSGs (shell + pandoc, small Ruby/ERB scripts, Swift, Rust/Go, etc.) to stay in control.

Templates, Partials, and “Includes”

  • The main reason to use SSGs: shared headers/footers/nav, templates, and auto-generated RSS, sitemaps, tag pages, etc.
  • Many see native HTML includes (<include src="...">) as an obvious missing feature.
  • Alternatives discussed:
    • Server Side Includes on nginx/apache.
    • PHP/“static PHP” include("header.html").
    • JS/Web Components (custom <include> elements), iframes, <object>, XSLT, m4, framesets.
    • Objection: many of these require JS or custom server config, undermining “pure static hosting”.

Workflow and Tooling Strategies

  • Some push builds into CI (GitHub Actions, similar) to avoid per-machine setup and pin versions; critics note CI images also change, but pinning or containers can help.
  • Containers/DevContainers/Docker images are suggested to freeze the toolchain across machines.
  • A few treat SSGs as disposable build tools: once HTML is generated, it can be edited by hand even if the generator later breaks.

Non-technical Authors & CMS-like Needs

  • Static generators are described as painful or impossible for non-technical users, especially around media, embeds, and custom markup.
  • File-based CMSes and lightweight systems (e.g., Kirby, Django+admin + wget, Obsidian publishing, mkdocs, Astro, Pelican, etc.) are mentioned as middle-ground options.