# catalogue
A ~120-line static-site indexer. It walks your HTML pages, reads three
`` tags per page, and writes one `archive/index.html` grouped by
content type and sorted newest-first. No Hugo, no build graph, no
runtime. Two files do the work: a scanner (`catalogue.py`) and a Jinja2
template (`catalogue.html.j2`).
Public domain (Unlicense) — take it, change the config block, ship it.
## The convention
Stamp each page's `` with three keyed metas. Separate keys, so
there is nothing to parse:
```html
```
- `type` — one bucket from your `TYPES` list (Products, Guides, …).
- `date` — `YYYY-MM-DD`, the page's own date (not the file mtime).
- `pin` — `1` to feature it on your front page; `0` (or absent) otherwise.
A page with no metas still shows up: the scanner falls back to a
`dir -> type` map and the file's last-modified time, so nothing goes
missing. Adoption is incremental — stamp pages as you touch them.
## Run
```sh
uv run --python 3.14 --with jinja2 catalogue.py
```
It writes `/archive/index.html`. The web root is inferred as
two directories up from the script (`tools/catalogue/` → site root), so
drop this folder anywhere under your web tree and it just works.
## Regenerate on every change
A git `pre-commit` hook regenerates the index and stages it inside the
same commit, so the catalogue is never stale:
```sh
#!/bin/sh
cd "$(git rev-parse --show-toplevel)" || exit 0
if [ -f public_html/tools/catalogue/catalogue.py ]; then
uv run --python 3.14 --with jinja2 public_html/tools/catalogue/catalogue.py >/dev/null 2>&1 \
&& git add public_html/archive/index.html 2>/dev/null
fi
exit 0
```
Every commit that touches a page → index rebuilt and committed with it.
No daemon, no polling. (Prefer a cron if you don't commit your site.)
## Configure
Everything you'd change lives in one block at the top of `catalogue.py`:
`BRAND`, `NS` (the meta namespace), `TYPES`, `ICON`, `OUTPUT`, `EXCL`
(directories to skip), and the optional `DIR` fallback map. The markup
lives entirely in `catalogue.html.j2` — restyle without touching Python.
## Why this and not a framework
For a site of hand-written pages, a full SSG (Hugo, Astro, 11ty) is a
build system you now own. This is the 20% of one that a personal site
actually uses: front-matter + a build-time index. When you outgrow it,
the same `type`/`date`/`pin` metadata ports straight into any of them.