Static site generators

A static site generator is the build step between the content you write and the pages you ship

The build step#

Your starter repo began without one: index.html in the root, main.ts beside it, and Vite to bundle them. One page, written by hand, shipped close to how it was written. That holds up until the site has six pages and every one of them includes a separate copy of the nav.

A static site generator sits between what you write and what you ship. You author content in whatever form suits it — Markdown files, data files, components — and a build turns the lot into plain HTML, CSS and JavaScript. Astro is the course default from crit 2; Eleventy and Jekyll are the same idea with different input formats and configuration. The output is the same kind of thing either way: the files GitHub Pages serves are the files it was already serving in week 1.

Benefits of the build step#

Three benefits:

• one copy of the repeated parts. The layout, the nav and the footer are written once and applied everywhere. A hand-written site accumulates copies of them, and an agent will accumulate copies faster than you will
• content separated from its markup. A page’s text sits in a file of its own, so restyling the site touches the layout rather than every page in it
• a fixed output. The build emits the same plain static files you deployed by hand in week 1, so the hosting doesn’t change

The cost is equally real. A generator adds a config file, a dependency tree, and a build that can fail in ways a hand-written page cannot. Under about three pages you are carrying that for nothing. It becomes useful when a change would otherwise require editing the same markup in several places. An agent can apply that mechanical edit across a dozen hand-written pages, so plain HTML remains a reasonable choice for longer than it once was.

Dev server and hot reload#

pnpm dev starts a dev server. It serves the site from source and rebuilds on save, and hot reload pushes the result into the browser without a refresh, so the gap between an edit and its consequence is a second or two.

Fast feedback matters for the same reason described in guides and sensors. You and the agent can act on a result immediately while the change is still in context. A shorter loop also returns every other check sooner.

The dev server is not the built site, though. It resolves paths its own way and skips the production build entirely, so a site can run perfectly at localhost:4321 and fail once built. pnpm build followed by pnpm preview is what CI runs, and it is the check to trust before you push.

The repository contract#

The starter is deliberately SSG-agnostic. It specifies three requirements for the built output, whichever generator you choose.

• pnpm build emits the complete site into dist/
• the package.json scripts — check, check:evidence, build — keep working
• the files in dist/ still pass the invariants in spec/

One important piece of wiring is the base path. A project site is served from a subdirectory (…github.io/<repo>/) rather than the root of a domain, and most generators need telling. Get it wrong and every link and asset resolves against the wrong prefix: the site works on your machine and 404s at the live URL, which is the gap between your dev machine and GitHub’s webserver.

/comp4020:stack configures the generator, moves the files, sets the base path and adds the CI link check. It stages one diff for review. The scripted conversion is recommended because a wrong base path is not detected locally.