motorino/README.md
tgiachi 889edbfd63
All checks were successful
check / check (pull_request) Successful in 31s
feat(gemtext): write a table wider than 80 columns as records
A preformatted block is not wrapped by the readers, so a table with long cells
(the data retention table of the services page) became unreadable. A wide table
with a header row is now a heading for each row and a bullet for each other cell,
named by its column; without a header, one bullet per row.

Refs #10
2026-11-16 12:28:54 +01:00

10 KiB

motorino

The static site generator of kmalloc.org. It turns Markdown pages, news, templates and language files into plain HTML with no JavaScript, and into a Gemini capsule. 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 gemini -site DIR -out DIR   write the same site as gemtext, for a Gemini server (defaults: . and capsule)
motorino gemini -lang CODE ...       the language at the root of the capsule; -drafts works as for build
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.

Gemini

motorino gemini reads the same site and writes gemtext: the pages of each language, the news once and a .meta file for the server. It does not read the templates, the style or the layouts: a page is its title, its text and a few navigation links.

  • Language at the root. The language served by default sits at the root and the others under /<code>/, the default language of the site included. It is set with -lang, else gemini_language in site.json, else the default language of the site. The server must be started with the same default (Agate: --lang). It must be a language that has a home page.
  • .meta. The server reads the language of each document from <out>/.meta, which it never serves and no page links to. For every language other than the root one there are two lines, en/*:;lang=en and en/**/*:;lang=en, because a * does not cross folders, and the same two lines for news/ when the news are not in the root language. It is for Agate run with --central-conf. A post that names another Language than the news is not given its own line.
  • News. They exist once, under /news/, as in the website: the index, the posts, the categories, the archives and news/feed.gmi, a list of => /news/2026/11/post.gmi 2026-11-14 Title lines, newest first, which feed readers subscribe to. Every page ends with the navigation of its language, which has the news. {{news_blog}} lists all the posts, without pages of ten.
  • Conversion. A heading is a heading (three levels), a paragraph is a line, the links of a paragraph, list, quote or table follow it on lines of their own, a list is bullets (a list of only links is link lines), a quote or a note is a quote, code is a preformatted block, a table is a preformatted block of aligned columns, or, when it is wider than 80 columns, a heading for each row with a bullet for each cell, an image with an alt text is a link line, and emphasis is dropped. A page has one first level heading: its title; a first heading that says the title is dropped and the others go one level down. The blocks ({{news_list}}, {{latest_news}} and the others) become generated lines, with the texts of the language file.
  • Addresses. An address of the site becomes the address of its page in the capsule (/people.html is /en/people.gmi), and a fragment is dropped. A file listed in assets is copied when a page points to it, and only then. http, https, mailto, gemini, xmpp, irc, ircs, matrix, bitcoin, magnet, tel and sms links stay as they are. A path the website serves by other means (/~squid/) becomes a link to the website when it starts with one of the comma separated prefixes of gemini_web_paths in site.json. Any other address that leads nowhere stops the build and names the page.

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.