# ~getz

The source of <https://dflund.se/~getz>. `make` builds it in place: every
page gets a `.html` file next to its source, and only pages whose
sources changed are rebuilt (`make force` rebuilds all, `make clean`
removes the output).

## Layout

    bin/mkws          the build script, see the comment at the top
    bin/pp            template preprocessor: sh code between "#!" lines
    share/l.upphtml   the page layout (sidebar, head, footer)
    share/lib.sh      helpers templates can call: md, post, postlist,
                      listing, gallery, dos, ...
    share/style.css   the stylesheet
    share/site.js     theme toggle, mobile menu, radio
    index.md          the home page
    Notes/            posts, one directory per post
    forest/           the wiki, one markdown file per tree
    Demos/            DOS things running in js-dos
    Pictures/         galleries, images live on the server only
    Synths/ Uploads/  directory listings
    fonts/ share/     static assets

## Writing a post

Make a directory under `Notes/<year>/` with an `index.md` and put the
images for the post next to it:

    Notes/2026/foo/index.md
    Notes/2026/foo/diagram.png

The file starts with its metadata, then the text:

    title: Something I did
    date: 2026-01-31

    Intro paragraph...

    ![a diagram](diagram.png)

That is all. `make` renders it to `Notes/2026/foo/index.html`, lists it
on the Notes page, adds it to `Notes/rss.xml`, and writes a plain text
copy to `Notes/ascii/` for the gopher hole. A markdown file without a
`date:` line is rendered but not listed, so unfinished notes can sit in
the tree. Files and directories whose name starts with `_` or `.` are
never built, and neither is `staging/`, which is for trying things out.

## Other pages

Any `foo.upphtml` is a page too. It is html, with sh code between lines
that contain only `#!`, run with the helpers from `share/lib.sh`:

    <!-- title: Uploads -->
    <h1>Uploads</h1>
    #!
    listing . 2
    #!

A page is rebuilt when it, the layout, the helpers, or anything in its
own directory tree changes. If it also depends on files elsewhere, say
so: `<!-- deps: ../Uploads/Synths -->`.

## The guestbook

`guestbook/guestbook.cgi` is a small Python cgi script: GET shows the
entries and a form, POST appends an entry to `guestbook/data/.htentries`
and redirects back. The page around it is the `index.html` next to the
script, built by mkws like any other page, with `<!-- guestbook -->`
where the entries go. The home page shows the guestbook as well: the
`index.cgi` in the site root is a symlink to the script, so it is run
with the home page as its template. The two `.htaccess` files turn on
cgi and make the directory urls run the scripts. The data files are made on first
use, seeded from `guestbook/seed.jsonl`, named `.ht*` so Apache never
serves them, and not in git. The web server runs cgi as its own user,
so make the directory for it once: `mkdir -m 1777 guestbook/data`.

## Needs

`lowdown`, `tree`, for the picture galleries `magick`, and for the
guestbook `python3` and a web server that runs cgi scripts. Nothing else.

## The forest

`forest/` is a small wiki: a map of things studied, one markdown file
per tree, all in that one directory. A tree looks like

    title: Virtual memory
    taxon: Concept
    parent: operating-systems
    math: yes

    Text with [[eigenvalues]] links to other trees, or
    [[eigenvalues|with other words]]. TeX between $...$ is typeset
    when math: yes is set.

`taxon`, `parent` and `math` are optional. `parent` builds the outline
on the forest page, and every tree page lists the trees under it and
the trees that link to it, so the structure takes care of itself. The
helpers behind it live in `forest/_forest.sh` and are used only by
`forest/_md.upphtml` and `forest/index.upphtml`; nothing in the rest of
the site, posts included, touches them.