# motorino The static site generator of [kmalloc.org](https://kmalloc.org/). It turns Markdown pages, news, templates and language files into plain HTML with no JavaScript. It is made for that one site and is not a general-purpose generator. Licence: GPL-3.0-or-later, see `LICENSE`. ## Usage ``` motorino build -site DIR -out DIR build the site in DIR into the output folder (defaults: . and public) motorino build -drafts ... the same, with the drafts and the posts dated in the future, for a preview motorino build -clean ... empty the output folder first, if it is new, empty or holds .motorino-out motorino new -site DIR "A title" write news/a-title.md, a draft with the header ready, and print its path motorino version print the version ``` The binary is a single static Go program. The version comes from semantic-release. A build writes the files it makes and leaves the others in the output folder, so the pages of a list that got shorter (`news/page/3/`) stay behind. When that happens the command prints a warning that names the old files. The deploy never has them: it builds into a new folder and publishes it with `rsync --delete`. For a folder you reuse, `-clean` empties it first. It does that only for a folder that is new, empty or holds the `.motorino-out` file that an earlier `-clean` left, never for any other folder with files in it and never for the folder of the site or one that holds it. A build without `-clean` writes no extra file. ## What a site looks like ``` site.json shared strings (contact, addresses, base_url), the language list, the assets lang/.json menu, footer and other interface strings of one language content//**/*.md the pages; index.md is the home of a folder news/.md the news, one file each templates/**/*.html the page chrome, the layouts, the news post and category page static/style.css the stylesheet, inlined in every page ``` The first language in `site.json` is the default and lives at the root of the site; the others live under `//`. ### Header Every page and every news file starts with lines of `Key: value`, ended by a line that holds a single `-`. The body is Markdown, and raw HTML is allowed in it. News: ``` Title: GNU/Linux Day 2026 Author: Matteo Bini Date: 2026-09-18T17:00:45+0200 Categories: Linux Day, FLUG Description: An optional one-line summary. Mastodon: https://social.kmalloc.org/@squid/115000000000000000 Language: it Draft: true - The text of the news. ``` A news file `news/name.md` is published as `/news/YYYY/MM/name.html`, with the year and the month of `Date` as written. Every category gets a page, `/news/category/.html`. The optional keys: - `Description`: the summary of the post. When it is written the post page shows it under the title; when it is not, the first sentence of the text is used for the meta description and the lists, and the page does not repeat it. - `Mastodon`: an `https` address, the post on Mastodon. The post page then has a link to reply there (the language needs `reply_mastodon`). - `Language`: the language the post is written in; the default is the language of the news (below). - `Draft`: `true` or `yes` keeps the post out of the site. So does a `Date` in the future, until that moment. `motorino build -drafts` publishes both, for a preview. #### The news and their language The news exist once, not once per language. Their language is `news_language` in `site.json`, else `en` when the site has it, else the default language. The news index page (`content//news/index.md`, ID `news`) must be in that language; the posts, the lists, the archive, the categories and the feed are all in it, with the interface strings of its language file. A post can say another language with `Language`; its page then uses that language file. The other languages of the site link to the news from their home. #### The blog Everything below is opt in, so a site that does not use it builds as it did. - **The post page** (`templates/post.html`) has, besides `post_title`, `date`, `post_body` and `post_byline`: `date_long` (such as "14 November 2026"), `post_summary` (the written description as a lead paragraph), `post_meta` (a line with the date, the author, the category links and the reading time), `post_reading`, `post_mastodon` (the reply link) and `post_nav` (the newer post, the older post and all the news). `og_type` is `article` there and `website` on every other page, and `article_meta` holds the published time and a tag for each category, for the head of `base.html`. - **The blog list**: a paragraph with only `{{news_blog}}` on the news index lists the posts as note panels (`

`: a small line with the long date and the categories, the title in bold with a full stop unless it ends with `.`, `?` or `!`, the description, and a read more link named after the post), 10 to a page. The other pages are written under the index, at `page/2/`, `page/3/`, with a pager. The block needs an index page. - **The archive**: when `templates/archive.html` exists, every year and month with posts gets a page, `/news/2026/` and `/news/2026/11/`, with `archive_name`, `archive_nav` and `archive_posts`. The posts of an archive page, of a category page and of the blog list are the same panels; where the language has no `read_more` the title is the link instead, except on the blog list, where it is an error. `{{news_list}}` and the latest news of the home page stay plain lists. `{{news_archive}}` lists the years and the months with their counts, and needs the template. - **The feed** (`/news/feed.xml`) has the summary in `description` and the full text, with absolute links, in `content:encoded`, plus the categories and the author. The strings come from the language files. These are required when the feature is used: `read_more`, `pager_label`, `pager_newer`, `pager_older` and `pager_page` (`Page {n} of {total}`) for the blog list, and `reply_mastodon` for a post with a Mastodon address. These are optional, and without them the feature is left out: `date_long` (`{d} {month} {y}`) and `month_01` to `month_12` (without them the date is `2026-11-14`), `date_month_year` (`{month} {y}`), `reading_time` (`{n} min read`), and `post_older`, `post_newer` and `post_nav` for the links between posts. The archive uses `archive_h` in its template and, optionally, `archive_up`. A new post is a draft: `motorino new "A title"` writes `news/a-title.md` with the date of now and `Draft: true`, and the author from the `author` key of `site.json` when there is one. Pages: `Title`, `ID` (the same in every language, it links the translations), `Description`, and optionally `Layout` (`page`, `bare` or `manifesto`), `Note`, `Switch` (`lang=/path, lang=/path`, overrides the language links) and `ManifestoVersion` and `ManifestoDate` (a translation of an older manifesto says which version it translates). ### Placeholders `{{name}}`, with lowercase letters, digits and underscores, is replaced by a string from `site.json` or the language file. An unknown placeholder stops the build and names the file. Fenced code blocks (found the way CommonMark finds them, in lists and quotes too) are left as written, so an article can show a placeholder there. Anywhere else a backslash before the placeholder (`\{{name}}`) keeps it as written, in a code span too; two backslashes are one literal backslash followed by the value. Code spans are otherwise substituted, which is how a page shows a value in monospace. The id of a heading is not checked against ids that a template writes itself, such as the `news` of the latest news block. `{{news_list}}`, `{{latest_news}}` and `{{categories_list}}` stand alone in a paragraph and expand to generated lists. ## Development ``` make check gofmt, go vet, staticcheck and the tests make build a local binary in bin/motorino make dist the release binary and its SHA-256 in dist/ ``` Go code has a doc comment on every package and declaration, and is formatted with `gofmt`. Commits follow conventional commits. A Forgejo Actions workflow (`.forgejo/workflows/check.yml`) runs `make check` on every push to `main` and on every pull request, on the shared runner of git.kmalloc.org. ## Release semantic-release is run by hand from a clean `main`: `npm run release:dry`, then `npm run release`. It tags `vX.Y.Z`, updates `CHANGELOG.md`, builds the `linux/amd64` binary and publishes it, with its SHA-256, as a release on this repository. The site deploy pins a version and checks the hash before it runs the binary.