kmalloc.org/README.md

71 lines
5.1 KiB
Markdown

# kmalloc.org
Sources of the kmalloc.org website: plain static HTML, no JavaScript, valid HTML5 and CSS. The site is built with [motorino](https://git.kmalloc.org/squid/motorino), the generator I wrote for it.
## Layout
- `content/<lang>/` holds the pages as Markdown, one file per page and language (`en`, `it`, `es`, `de`, `fr`). `index.md` is the home of a folder. The file path is the address: `content/it/servizi.md` is `/it/servizi.html`.
- `news/` holds the news, written in English only: one `name.md` file each.
- `site.json` holds what every language shares: the language list, the contact and security addresses, the Bitcoin and shop addresses, the manifesto version and date, and the assets that are copied as they are.
- `lang/<lang>.json` holds the interface strings of one language: the menu, the footer and the other short texts.
- `templates/` holds the chrome (`base.html`, `header.html`, `footer.html`), the layouts in `templates/pages/` (`page`, `bare`, `manifesto`), the news post (`post.html`) and the category page (`category.html`).
- `static/style.css` is the one stylesheet, inlined into every page.
- `badges/` holds the official W3C badges, served from our own site.
- `logo/` holds the shrike logo: SVG and PNG exports (`og-1200x630.png` is the preview image of shared links), `build_logo.py`, the original PNG and the favicons in `logo/web/`.
- `.motorino-version` pins the version of motorino (line 1) and the SHA-256 of its `linux/amd64` binary (line 2).
## Writing a page
Every page starts with a header of `Key: value` lines ended by a line with a single `-`, then Markdown. Raw HTML is allowed, for the few things Markdown cannot say (the data table, the hero of the home page).
Title: Services
ID: services
Description: The services on kmalloc.org and how to get an account.
Layout: bare
-
# Services
Write to **{{contact_shown}}**.
## Get an account {#account}
`ID` is the same in every language: it links the translations. `Layout` is `page` (the title as a heading, then the body), `bare` (the body only, which writes its own `# heading`) or `manifesto`. A heading can set its id with `{#id}`; the others get one from their words. `{{name}}` is replaced by a string of `site.json` or of the language file, and an unknown one stops the build. `{{news_list}}`, `{{latest_news}}` and `{{categories_list}}` stand alone in a paragraph and expand to lists. The full list of keys is in the motorino README.
A new language is one file `lang/<lang>.json`, its name in `site.json` and its pages in `content/<lang>/`. A language lists only the pages it has: Spanish, German and French have the manifesto only, so they use the short header (`"header": "header-min"`). A translation of an older manifesto says which version it translates with `ManifestoVersion` and `ManifestoDate`.
## News
A news item is a file `news/name.md`:
Title: Hello from kmalloc.org
Author: squid
Date: 2026-09-18T17:00:45+0200
Categories: News
Description: One line shown in the list.
-
The text, with a [link](https://kmalloc.org/) and `code`.
It is published at `/news/YYYY/MM/name.html`, with the year and month of `Date`. Every category has a page at `/news/category/<name>.html`. The news index, the latest three news on the home pages and an RSS 2.0 feed (`/news/feed.xml`, the latest 20 news with full text) are built from the files. No em dashes: the build refuses them. The first three news also answer at their old addresses (`/news/status-page.html` and so on) through permanent redirects in the Caddyfile of `shrike-infra`.
## Preview
motorino build -site . -out preview
cd preview && python3 -m http.server 8197 --bind 127.0.0.1
Get the binary of the pinned version from the releases of motorino, or build it from its repository with `make build`. I check the output with the Nu HTML Checker before I push.
## Indexing
Every page, news item and category page may be indexed. `robots.txt` allows exactly their addresses and blocks the rest (the downloads and the assets). The personal pages under `/~name/` are not built here and carry `noindex`.
## License
The texts are released under CC BY-SA 4.0, see `LICENSE`. The code and the logo are not covered; the logo pack has its own terms in its README.
## Publishing
Pushing to `main` publishes the site. A post-receive hook in the Forgejo repository touches a trigger file, `deploy-kmalloc-site.path` on the server notices it and runs `deploy-kmalloc-site`. The script builds `main` into a temporary directory with the pinned motorino and mirrors it into the web root. It downloads the binary once, checks it against the hash in `.motorino-version` and keeps it in `/var/cache/kmalloc-deploy`. If the hash or the build is wrong nothing is copied.
To move to a new motorino: take the version and the SHA-256 from its release and write them in `.motorino-version`.
A Forgejo Actions workflow (`.forgejo/workflows/check.yml`) builds the site with the pinned motorino and runs the Nu HTML Checker on every page, on every push to `main` and on every pull request, on the shared runner of git.kmalloc.org. The publishing itself stays the hook on the server.