Capstone: Build a Static Site Generator

This is the last lesson, so let’s build something real. A static site generator takes a folder of markdown files and turns it into a folder of HTML — the same job Jekyll, Hugo and Eleventy do, and the same job the site you are reading does.

Underneath the tooling, it is three steps: read, transform, write. We will build each stage separately and run it, then assemble them.

Stage 1 — Split Metadata From Content

Every post carries data about the post — title, date — separated from the body by --- fences. That block is called front matter.

Note line.partition(':'): unlike split, it always returns three parts, so a malformed line without a colon cannot crash the unpack.

def parse_front_matter(text):
    if not text.startswith('---'):
        return {}, text
    _, fm, body = text.split('---', 2)
    meta = {}
    for line in fm.strip().splitlines():
        key, _, value = line.partition(':')
        meta[key.strip()] = value.strip()
    return meta, body.strip()

page = '''---
title: Hello World
date: 2026-08-01
---
# My first post
'''

meta, body = parse_front_matter(page)
print(meta['title'])
print(meta['date'])
print(body)

Hello World
2026-08-01
# My first post

The first line of that function is the one that matters in production. A file without front matter still has to build:

text = 'no front matter here'

def parse_front_matter(t):
    if not t.startswith('---'):
        return {}, t
    _, fm, body = t.split('---', 2)
    return {'raw': fm.strip()}, body.strip()

meta, body = parse_front_matter(text)
print(meta)
print(body)

{}
no front matter here

Stage 2 — Render Markdown

Now the transformation. Headings first, then inline formatting. Watch the order inside the else branch: escape first, then insert tags. Do it the other way round and html.escape will mangle the <strong> you just added.

import re, html

def render(md):
    out = []
    for line in md.splitlines():
        if line.startswith('## '):
            out.append(f'<h2>{html.escape(line[3:])}</h2>')
        elif line.startswith('# '):
            out.append(f'<h1>{html.escape(line[2:])}</h1>')
        elif line.strip() == '':
            continue
        else:
            text = html.escape(line)
            text = re.sub(r'\*\*(.+?)\*\*', r'<strong>\1</strong>', text)
            text = re.sub(r'\*(.+?)\*', r'<em>\1</em>', text)
            out.append(f'<p>{text}</p>')
    return '\n'.join(out)

print(render('# Title\n\nHello **world** and *friends*.\n\n## Section\n\nDone.'))

<h1>Title</h1>
<p>Hello <strong>world</strong> and <em>friends</em>.</p>
<h2>Section</h2>
<p>Done.</p>

The Two Bugs Hiding In Stage 2

The first is security. Every generator must escape, or a stray < silently eats the rest of the page:

import html

user_text = '<script>alert(1)</script>'
print(html.escape(user_text))

<script>alert(1)</script>

The second is the regex. .+? is non-greedy — it stops at the first closing marker. Drop the ? and it runs to the last one, merging two separate bold spans into a single mangled one. Run both and compare:

import re

text = '**one** and **two**'
print(re.sub(r'\*\*(.+?)\*\*', r'<b>\1</b>', text))
print(re.sub(r'\*\*(.+)\*\*', r'<b>\1</b>', text))

<b>one</b> and <b>two</b>
<b>one** and **two</b>

That second line is a real bug that ships in hand-rolled markdown parsers constantly.

Stage 3 — Work Out Where Files Go

posts/hello-world.md has to become public/hello-world.html. pathlib does this without any string surgery:

from pathlib import Path

source = Path('content/posts/hello-world.md')
print(source.stem)
print(source.suffix)
print((Path('public') / source.with_suffix('.html').name).as_posix())

hello-world
.md
public/hello-world.html

Stage 4 — Build the Index

While looping over files you collect each page’s metadata. That collection is your home page — sort it newest-first and you have a blog index:

pages = [
    {'title': 'Older', 'date': '2026-01-05'},
    {'title': 'Newest', 'date': '2026-08-01'},
    {'title': 'Middle', 'date': '2026-04-17'},
]

for page in sorted(pages, key=lambda p: p['date'], reverse=True):
    print(page['date'], page['title'])

2026-08-01 Newest
2026-04-17 Middle
2026-01-05 Older

Assembling It

Each stage above ran on its own, which is exactly why the finished loop works first time. On a real filesystem the whole generator is roughly this:

from pathlib import Path

def build(src_dir='content', out_dir='public'):
    pages = []
    Path(out_dir).mkdir(exist_ok=True)

    for md_file in sorted(Path(src_dir).glob('*.md')):
        meta, body = parse_front_matter(md_file.read_text(encoding='utf-8'))
        html_body = render(body)
        out_path = Path(out_dir) / md_file.with_suffix('.html').name
        out_path.write_text(
            f"<!doctype html><title>{meta.get('title', '')}</title>{html_body}",
            encoding='utf-8',
        )
        pages.append({**meta, 'url': out_path.name})

    index = '\n'.join(
        f"<li><a href=\"{p['url']}\">{p['title']}</a></li>"
        for p in sorted(pages, key=lambda p: p.get('date', ''), reverse=True)
    )
    (Path(out_dir) / 'index.html').write_text(f'<ul>{index}</ul>', encoding='utf-8')
    return len(pages)

# build() writes public/*.html and public/index.html, and returns the page count

Thirty lines. No framework, no dependencies — just the standard library and the ideas from the last sixty lessons: file handling, comprehensions, regular expressions, pathlib, dictionaries, sorting with a key.

Where To Take It

You have finished the Python track, so here are the natural next moves — each one reuses a lesson you have already done:

• Add a template system. Right now the HTML is an f-string. Swap in Jinja2 for loops, inheritance and partials.
• Make it a package. Turn it into a proper distribution with pyproject.toml and publish it — that is the packaging lesson, applied.
• Add plugins. A registry of renderers, so someone can add reStructuredText support without touching your core — the architecture lesson, applied.
• Make it fast. Profile it on a thousand files, then parallelise the render step with multiprocessing. Measure before and after; do not guess.

Watch Out

Myth: A static site generator needs a template engine and a framework to be real. Reality: Read, transform, write. An f-string is a perfectly good template right up until you need loops and inheritance — and knowing exactly when you crossed that line is the mark of an expert.

Myth: Escaping is only for content other people submit. Reality: It is what stops your own code sample containing <div> from destroying the page. Escape by default; unescape deliberately.