# 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](https://vite.dev) 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](https://astro.build) is the course default from crit 2;
[Eleventy](https://www.11ty.dev) and [Jekyll](https://jekyllrb.com) are the same
idea with different input formats and configuration. The output is the same kind
of thing either way: the files [GitHub Pages](https://comp.anu.edu.au/courses/comp4020-agentic-coding-studio/topics/github-pages-deployment/)
serves are the files it was already serving in week 1.

## Benefits of the build step {#what-the-build-step-buys}

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](https://comp.anu.edu.au/courses/comp4020-agentic-coding-studio/topics/backpressure/#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-contract-your-repo-keeps}

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](https://comp.anu.edu.au/courses/comp4020-agentic-coding-studio/topics/github-pages-deployment/#machines-map).

`/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.

Source: <https://comp.anu.edu.au/courses/comp4020-agentic-coding-studio/topics/static-site-generators/>\
Licence: [CC-BY-NC-SA-4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)\
Cite as: Swift, B. (2026). _COMP4020/COMP8020 Agentic Coding Studio_ [Course materials]. ANU School of Computing. https://doi.org/10.5281/zenodo.21395760