Static site generators and Markdown

A static site generator is a program that turns Markdown files, data and a shared template into ready HTML files. Only those files go to the server.

Another way: a site as the result of a build

In the previous lessons a page was put together on every request: the server took the content from a database and inserted it into a template. There’s another way, which you met in part 6 as “static”: the pages are built once, beforehand, and the finished files go on the server. The program that does it’s called a static site generator. When sites in the 2010s began to be hacked, slowed down and costly to maintain, this approach came back, because such a site has no database and no code on the server, so there’s almost nothing to break.

Markdown: text without HTML

To write pages without typing tags, Markdown was invented (John Gruber, 2004). It’s a few characters that read well to the eye and turn into HTML:

# A first-level heading
## A second-level heading

An ordinary paragraph with a **bold** word and a [link](https://example.com).

- a list item
- another item

Gruber’s rules were described by examples, and different programs understood them differently. So later a strict common version appeared, CommonMark. A Markdown file is plain text: any editor opens it, it’s stored in Git, and its content isn’t tied to the look. If you change the template tomorrow, the texts are unharmed.

Front matter: a page’s passport

Above a page’s text goes a small block of settings between lines of three hyphens. It’s called front matter:

---
title: Catalog
description: What we do and what it costs
---
# Catalog

It’s the page’s “passport”: the title, the description for a search engine, a date, any fields of your own. The template takes them from there (page.title), and collections are sorted by them. Jekyll introduced this idea, and now it’s almost everywhere.

What a generator does

Move the diagram below. On the left is Markdown with its front matter, on the right the finished page. The services are printed by a loop over the data.

<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><title>Catalog | My site</title></head>
<body>
<header><strong>My site</strong>
<nav><a href="index.html">Home</a> <a href="catalog.html">Catalog</a> </nav></header>
<main><h1>Catalog</h1>
<p>Every service is printed from the data, not typed by hand:</p>
<ul>
<li><strong>First service</strong>, from $300</li>
<li><strong>Second service</strong>, from $500</li>
<li><strong>Third service</strong>, by quote</li>
</ul></main>
<footer>My site, all rights reserved</footer>
</body>
</html>

{% for item in site.items %}
  <li>{{ item.title }}</li>
{% endfor %}

A generator’s work fits in five steps: read the files and the data; parse the front matter; substitute the data into the text and turn Markdown into HTML; place the result in the shared template; write the finished files to a folder. This work is called the build, and it runs on your computer or on a build server. The result is an ordinary folder of HTML, CSS and images that can be put anywhere.

Three ideas that turn up in every generator:

• The template (layout) sets the common frame: the header, the menu, the footer. There’s one, so the phone number in the header is edited in one place.
• Data and collections: a set of records of one kind (all the services, all the articles). The template goes through them in a loop and prints a list. A new service is a new file, not an edit to a page.
• Filters and includes: small functions in the template (escaping, formatting a date) and reusable pieces of markup.

Jekyll, Hugo, Eleventy, Astro, SvelteKit

There are hundreds of generators, and the principle is the same. They differ in language, speed and habits. Here are the five most useful to get to know.

The course you’re reading is built the same way. Each lesson is a Markdown file with metadata (what we call front matter here), Svelte components for the live diagrams, and the site is built into a folder of ready HTML files that sits on free hosting. That is SvelteKit in prerender mode.

How to choose? If you just need a site with pages and collections, any will do. People take Hugo for speed on big sites, Eleventy for simplicity, Astro when pages need almost no scripts, and SvelteKit when the site needs live interfaces as well. Getting to know one will help you learn the others.

What we get, and what we pay

The pros of a static site: fast (a ready file is handed out), safe (no code or database on the server), cheap (hosting for static files is often free), with a history (every edit is in Git, and a rollback is one command) and portable (the folder can be put anywhere).

The cons:

• no familiar admin panel: the editor has to be able to edit files and send changes to Git (later we’ll see how a “headless” CMS makes this easier);
• nothing dynamic: forms, search, comments, payment and customer accounts are added as outside services or functions (lesson 7);
• the build grows with the number of pages: thousands of pages need a fast generator and a clever way of publishing.

Practice

You’re in the era of 2019: “static” is back in fashion, and you move your site onto a generator. The page holds a project of four kinds of files: settings, a shared template, a Markdown page for each section of the brief, and a collection made of your services. Finish the settings and the template (the language, a header with a menu, a footer), fill in the pages, and print the services in the catalog with a loop.

Notice one oddity. The course’s editor itself substitutes your brief’s values into plain double braces, so in the task’s templates there’s a harmless filter next to each value: {{ site.title | escape }}. In a real Jekyll you would simply write {{ site.title }}.

What was wrong with 2019

The generators of 2019 were wonderful for developers and hard on everyone else. Installing Jekyll on Windows became an ordeal, building a large site took minutes, and an editor had to learn Git to fix one typo. The next steps solved these same problems: fast builders, visual editors on top of Git, and the “headless” CMSs that the next lesson is about.