chore: remove the Python generator and the migration tools
The site is built by motorino. The manifesto texts live in content/, the migration and comparison tools did their job, and build.py is gone. Add the list of the categories to the news page, rewrite the README for the new layout and update the licence file to name the new folders.
This commit is contained in:
parent
04533836bb
commit
bb926a4b2f
1 changed files with 46 additions and 1797 deletions
70
README.md
70
README.md
|
|
@ -1,59 +1,69 @@
|
|||
# kmalloc.org
|
||||
|
||||
Sources of the kmalloc.org website: plain static HTML, no JavaScript, valid HTML5 and CSS.
|
||||
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
|
||||
|
||||
- `build.py` generates the site: `python3 build.py [output-dir]` (default `preview/`). Standard library only.
|
||||
- `site.json` holds what every language shares: the language list, contact address, Bitcoin address, shop address, manifesto version, services and people.
|
||||
- `lang/<lang>.json` holds every text of one language (`en`, `it`, `es`, `de`, `fr`): the menu, the footer and one entry per page. The texts are plain text and the build escapes them.
|
||||
- `templates/` holds the chrome (`base.html`, `header.html`, `footer.html`), one body per page type in `templates/pages/` and repeated blocks in `templates/parts/`.
|
||||
- `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.
|
||||
- `MANIFESTO.<lang>.md` are the manifesto texts. English and Italian are at version 1.2 (`manifesto_version` and `manifesto_date` in `site.json`); Spanish, German and French are machine translations of version 1.0 (overridden in their `lang/<lang>.json`) and show a note that the English text prevails. Every version is listed on the manifesto history page.
|
||||
- `news/` holds the news posts, written in English only.
|
||||
- `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).
|
||||
|
||||
## Languages
|
||||
## Writing a page
|
||||
|
||||
A new language is one file, `lang/<lang>.json`, plus its name in `site.json` and a `MANIFESTO.<lang>.md`. 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"`) and the other pages are not built for them. The language links in the header list every other language that has the same 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).
|
||||
|
||||
A page entry in `lang/<lang>.json` looks like this:
|
||||
Title: Services
|
||||
ID: services
|
||||
Description: The services on kmalloc.org and how to get an account.
|
||||
Layout: bare
|
||||
-
|
||||
# Services
|
||||
|
||||
"people": {
|
||||
"path": "/people.html",
|
||||
"title": "kmalloc.org: People",
|
||||
"description": "The people behind kmalloc.org.",
|
||||
"intro": "Who is behind kmalloc.org.",
|
||||
"bios": { "squid": "..." }
|
||||
}
|
||||
Write to **{{contact_shown}}**.
|
||||
|
||||
The page types are `home`, `manifesto`, `people`, `services`, `news` and `history` (the manifesto history). A list of plain strings in a page entry becomes `<li>` items. Placeholders such as `{{intro}}` or `{{url_news}}` in `templates/pages/*.html` are replaced at build time, and an unknown placeholder stops the build.
|
||||
## 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 post is a Markdown file named `YYYY-MM-DD-slug.md` in `news/`:
|
||||
A news item is a file `news/name.md`:
|
||||
|
||||
---
|
||||
title: Hello
|
||||
summary: One line shown in the list.
|
||||
---
|
||||
Text with a [link](https://kmalloc.org/) and `code`.
|
||||
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`.
|
||||
|
||||
## A heading
|
||||
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`.
|
||||
|
||||
The post is published at `/news/slug.html`. News are English only: the pages of the other languages list the same posts and link to them. The news index, the latest three posts on the home pages and an RSS 2.0 feed (`/news/feed.xml`, the latest 20 posts with full text) are built from the files. Every page links the feed in the head and shows the RSS icon in the footer. No em dashes: the build refuses them.
|
||||
## 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
|
||||
|
||||
Only the home pages and the manifesto pages may be indexed (`INDEXABLE` in `build.py`): they have no robots meta tag and `robots.txt` allows exactly their paths. Every other page has `noindex, nofollow, noarchive` and is blocked in `robots.txt`.
|
||||
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 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`, which builds `main` into a temporary directory and mirrors it into the web root. If the build fails nothing is copied.
|
||||
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.
|
||||
|
||||
I check every page with the Nu HTML Checker before pushing.
|
||||
To move to a new motorino: take the version and the SHA-256 from its release and write them in `.motorino-version`.
|
||||
|
|
|
|||
Loading…
Reference in a new issue