motorino/README.md
tgiachi 633da1c46b
All checks were successful
check / check (pull_request) Successful in 30s
feat: motorino new writes a draft, motorino build -drafts previews it
motorino new -site DIR "A title" writes news/a-title.md with the header ready:
the date of now, the author from site.json, the category News and Draft: true.
motorino build -drafts publishes the drafts and the posts dated in the future,
for a preview. The README describes the header keys, the news language, the blog
placeholders and blocks, and the language strings they use.

Refs #9
2026-11-16 12:10:30 +01:00

7.3 KiB

motorino

The static site generator of 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 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.

What a site looks like

site.json                    shared strings (contact, addresses, base_url), the language list, the assets
lang/<lang>.json             menu, footer and other interface strings of one language
content/<lang>/**/*.md       the pages; index.md is the home of a folder
news/<name>.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 /<lang>/.

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/<name>.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/<lang>/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 entries (title, long date, categories, description, a read more link), 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. {{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.