HAP pointing upward with one finger, smiling encouragingly

Explanation

Where this goes next

Static site generators, and the pieces they are built from

A handwritten build script works until there are forty pages. What replaces it is a category of tool called a static site generator, built out of the pieces the previous pages covered.

The Problem They Solve

To give websites a sense of cohesiveness, we usually want to have parts of pages be identical. The navigation across the top and the footer at the bottom are just two examples. When a site has a few hand-written pages, keeping pages synced during edits is hard but manageable. As sites grow, the task becomes much harder and tedious. For example, if every page of a twenty-page site repeats the same head tag, the same header and the same footer, changing any of those means twenty edits and twenty chances of getting something wrong, followed by testing twenty changed pages.

Static site generators have the shared parts as templates and have a program include them in each page. Doing it this way ensures these parts remain consistent between pages.

What A Generator Does

It reads three kinds of input and writes one kind of output.

The shape of a generated project:
content/          markdown files, one per page
_includes/        templates: the shell every page goes into
_data/            structured data available to every template
        │
        ▼   the generator reads all three
        │
_site/            finished HTML, one file per piece of content

Content

This is usually Markdown, with one file per page holding the words. It often includes a small block of settings at the top called front matter, naming a title, date, and template.

Templates

These are HTML files containing placeholders. They act as the shell every page drops into, along with smaller reusable pieces for cards or navigation bars.

Data

This is structured information that is not prose, such as a list of projects, a set of links, or values fetched from an API at build time. It is available to every template.

Output

These are plain HTML files. Once the build finishes, the generator is out of the picture entirely. What gets deployed is ordinary HTML, CSS, and JavaScript that any web server can hand out.

HAP teaching at a chalkboard with HTML code on it

🟠 There is nothing new here

A generator is a package on the registry that npm installs and Node runs. It writes into an output folder that git ignores, and a dev server previews the result. Every piece of that came from an earlier page in this lab.

Popular Static Site Generators

Eleventy

Written in JavaScript, this tool is deliberately small and has no opinion about how content is structured. It is popular for teaching because very little of it is hidden.

Astro

Written in JavaScript, this tool ships zero JavaScript to the browser by default and lets interactive components opt in. This lab is built with it.

Jekyll

Written in Ruby, this is the oldest of the widely used generators. It is the reason GitHub Pages exists in its current form.

Hugo

Written in Go, this tool is distributed as a single downloaded program rather than an npm package. It is extremely fast on very large sites.

Next and Nuxt

These are application frameworks that can also generate static output. They use considerably more machinery and target sites that behave closer to apps.

What they share

Templates, content, and data go in, and HTML comes out. The syntax differs from one to the next, but that shape does not.

What Remains Consistent

A developer will typically choose a static site generator (SSG) based on build speed, language familiarity, and the level of interactivity the project requires. In most cases, here are the common features.

  1. The output folder is generated and disposable, and it belongs in .gitignore.
  2. package.json and package-lock.json are the record of what the project needs, and both get committed.
  3. Local previews require running a dev server because the output is a website rather than a standalone file.
  4. Deployment consists of running the build step and publishing the resulting output folder.
  5. Every problem resides in one of three places: your source, the configuration, or a dependency. Your first step in debugging is identifying which of these three areas is responsible.

Where To Go From Here

HAP's Static Site Generator lab picks up exactly here and works through templates, content, data, and a real build.

The command set and the package.json reference on this site stay useful the whole way through.