Publishing this site¶
The first proof of concept is the site itself: a static documentation site on
the same host that already serves osilayer8.net, with search that needs no
external service and two ways to edit it from a browser.
What it is made of¶
| Piece | Choice | Why |
|---|---|---|
| Generator | Material for MkDocs | Markdown plus one config file; search, blog and tags are built in |
| Search | lunr.js, built at publish time | Runs in the browser, so nothing to operate and nothing to leak |
| Source | Forgejo, web/docs.osilayer8.net |
Already self-hosted and already backed up |
| Edge | nginx behind nginx-proxy |
Certificates issue themselves from two environment variables |
| Deploy | Ansible, make docsite |
Same rsync-from-the-controller shape the main site uses |
The build¶
No Python, no Node, no MkDocs install — the build runs in the official image:
The image tag is pinned. The theme ships its own compiled asset bundle, so an unpinned image would quietly change the rendered output on a rebuild.
Publishing is deliberately manual¶
An edit — from the Mac, from Forgejo's editor, or from the CMS — lands in git and stops there. Publishing takes two commands on the workstation:
Why not build on the server
Forgejo runs on the same host that serves this site. A build triggered on that host would depend on the machine it exists to rebuild, which is the reason the main site is built on the workstation too. The cost is that browser edits wait for a publish; the benefit is that recovering the host never requires the host.
What it does not do¶
No CI runner, no webhooks, no scheduled pull. Those are all possible later and none of them are needed to write a page.