{"canonical_url":"https://engineer.company/glossary/ssg/","content_markdown":"# Static site generator\n\n## What it is\n\nA static site generator is a build tool that takes a folder of source files,\nusually pages written in Markdown and a set of templates, and turns them into a\nfinished website made only of files: HTML, stylesheets, scripts and images that\na web server sends exactly as they are. The term is often shortened to SSG, and\n“static” describes how the result is served, the same bytes to everyone who asks\nfor an address, not how a page behaves once it reaches a browser.\n\nIt sits opposite the dynamic approach of a content management system or a web\napplication, where a program on the server assembles each page when it is\nrequested, usually by querying a database and filling in templates. A generator\nruns the same kind of templates over the same kind of content, but once per\nchange instead of once per visit, and leaves the result in a folder that an\nordinary web server, a storage bucket or a content delivery network can serve\nwithout knowing how the pages were made.\n\nHugo is one such generator. Its documentation introduces it as “a static site\ngenerator written in Go, optimized for speed and designed for flexibility” that\n“renders a complete site in seconds, often less”. The usual loop is to write\nwith its embedded web server running, which rebuilds on every change and reloads\nthe open browser pages, then build the site and deploy it to a host:\n\n```sh\nhugo server     # build, serve, rebuild and reload on every save\nhugo --minify   # write the finished site into public/\n```\n\n## Why it matters\n\nThe choice is about when the work happens. A generator moves it from request\ntime to build time, and almost everything that follows comes from that.\n\nSending a file is about the cheapest thing a web server does, so a generated\nsite answers quickly and can run on a very small machine, and because every\nvisitor to an address gets the same bytes, caching is simple. With no\napplication code or database running behind the pages, there is far less to\nsecure and patch. The output is a folder, so moving to another host means\ncopying files, and the source lives in version control, where every change to\nevery page can be reviewed and traced.\n\nThe costs come from the same place. Every change, a corrected typo included,\nmeans a fresh build and a deploy, so build speed matters more as the page count\ngrows. Anything that depends on who is asking, such as search, comments, sign-in\nor a form that stores what it receives, needs code in the browser, a separate\nservice, or a way to be settled at build time, because there is no program on\nthe server to do it. Time stands still between builds: Hugo by default leaves\nout a page whose date lies in the future, so a page scheduled for Monday appears\nwith the first build on or after Monday. Even redirects change shape. With no\nprogram to send an HTTP redirect, Hugo's default for a moved page is a small\nHTML file at the old address that sends the browser on, an approach its\ndocumentation calls portable across all hosting providers.\n\n## What it looks like in practice\n\nThis site is built with one. [The credits page](/credits/) names Hugo as the\nstatic site generator and credits it with the templates, the taxonomies, every\nlanguage and the feeds. Of what reaches a browser, it says the HTML is written\nout in full before anyone asks for it: every page is a file on disk, not a\ntemplate assembled per request. Even the look is settled at build time, since\nthe light theme's wall is drawn while the page is built and the site is dressed\nafresh each time it is published. The quality gate runs locally, on the\ncomputer the site is edited on, without a hosted build service anywhere in the\nchain; it treats every diagnostic as an error, and in October 2026 the site built 2,268 pages.\nThey are served from a single-core server with 512 MB of memory, where the web\nserver and the three other services that answer for the site read the same\nfolder of files, so one deploy updates all four.\n\n[The portfolio entry on building this site in Hugo](/portfolio/built-a-multilingual-hugo-site-in-3-languages/)\ndocuments the August 2026 implementation stage and gives the reasoning. Three\nlanguages, no separately billed application service and no visitors handed to third parties ruled out\nalmost every content management system, because a backend that runs is something\nto secure, patch, pay for and explain on a privacy page. The site then had 108\ntemplate files, 53 of them partials, published every page in four representations\nfrom one content tree, and built that tree seven more times for focused\nsubdomains by pointing the generator at a different content directory. The\nwrite-up records the trade-off of adding capability at build time rather than\nin the browser: beyond the recorded scoped JavaScript exception for a portfolio filter, interactive features had to be solved at build time or omitted, which is why a search index was costed and parked rather than shipped.\n\n## Where it goes wrong\n\n**A deleted page stays online.** A page removed from the source is still served\nat its old address, and search engines go on finding it. Hugo does not clear its\noutput folder before a build: existing files are overwritten but never deleted,\nso `public/` can keep pages from earlier builds, drafts and expired pages among\nthem, and anything that copies that folder to a server copies them too. Its\n`resources/` cache has a cousin of the problem: this site's design rules warn\nthat it can serve a stale CSS bundle when only the source CSS has changed. Build\ninto a clean folder, with Hugo's `--cleanDestinationDir` flag or a delete step\nof your own; this site's build removes both `public/` and `resources/` before it\nstarts.\n\n**A finished page never appears.** A post is written, committed and deployed,\nthe build reports success, and the site has no page for it. By default Hugo\nleaves out content marked as a draft, content whose date or publish date lies in\nthe future, and content whose expiry date has passed, and none of that counts as\nan error. A date typed a day ahead is enough. Check those four fields first,\nkeep `--buildDrafts`, `--buildFuture` and `--buildExpired` for previews, and for\na scheduled page arrange a build after its date.\n\n**Every page claims to have changed at once.** The sitemap gives nearly every\naddress the same last-modified time, which tells a crawler the whole site\nchanged and says nothing about which pages did. A generator has to take each\npage's modification date from somewhere, and the file's own timestamp is the\nwrong source when a step rewrites files whose content stays the same. This\nsite's configuration records that its sync step rewrites all 189 content files\non every run, so 172 of the 176 sitemap addresses shared one timestamp. Take the\ndate from version control instead: Hugo reads the date of a file's last Git\nrevision when `enableGitInfo` is on, and a re-sync that produces identical bytes\nmakes no commit, so a re-sync after a month of edits touched 8 of 186 files.\n\n**Files nobody meant to publish go out.** Anyone who guesses the name can fetch\na file that lists other files. A generator publishes whatever sits in the\nfolders it reads, minus what an exclusion rule removes, and a rule that does not\nreach every folder leaves the rest exposed. This site's configuration records\nthat its site-wide ignore list did not reach a module mount: the build published\nall six `.DS_Store` files the macOS Finder had left under icons/, images/ and\nwebmanifest/, on every host, and each listed the names beside it, so the one in\nimages/ named a folder the site withholds. A filter missing one space after its\n`!` once excluded every image in a mount instead. Exclude on every mount that\npublishes, then check the built output for files that do not belong; two of this\nsite's checks fail a build that serves one.\n\n## Further reading\n\n- [Hugo: Introduction](https://gohugo.io/about/introduction/) — what Hugo is,\n  what it is used for, and how its write, build and deploy loop runs.\n- [Hugo: Basic usage](https://gohugo.io/getting-started/usage/) — building and\n  serving a site, why `public/` keeps old files, and which content a build\n  leaves out.\n- [Hugo: Configure front matter](https://gohugo.io/configuration/front-matter/)\n  — how Hugo picks a page's dates, including the `:git` and `:fileModTime`\n  tokens.\n- [Hugo: Configure modules](https://gohugo.io/configuration/module/) — mounts,\n  the `files` filter each one takes, and the rule that defining a mount removes\n  the default one.\n- [Hugo: URL management](https://gohugo.io/content-management/urls/) — aliases,\n  and the redirect files a static host serves in place of a server redirect.\n\n\u003chttps://engineer.company/glossary/ssg/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"How a static site generator turns text and templates into files ahead of time, what that buys and costs, and the build traps that publish the wrong pages.","formats":{"gemtext":"https://engineer.company/glossary/ssg/index.gmi","gopher":"https://engineer.company/glossary/ssg/gophermap","html":"https://engineer.company/glossary/ssg/","json":"https://engineer.company/glossary/ssg/index.json","markdown":"https://engineer.company/glossary/ssg/index.md","pdf":"https://engineer.company/glossary/ssg/index.pdf"},"kind":"page","language":"en","title":"What is a static site generator?","url":"https://engineer.company/glossary/ssg/","version":1}