- Go 98.6%
- Shell 0.7%
- JavaScript 0.5%
- Makefile 0.2%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
All checks were successful
check / check (pull_request) Successful in 30s
- a list item with no text (only an image or a link without a label) has no empty bullet,
its links are still written
- paragraphs and table cells of a list item do not stick together, and a preformatted
block in an item stays a block after its bullet
- spaces in the address of a link line are written as %20
- a wide table with an empty first cell has no empty heading, a wide table with only a
header or only one column is written as bullets, and the header is not lost
- a post in another language than the news has its own line in .meta, before the lines
of the folders: the server uses the first line that matches a document (checked with
Agate 3.3.25)
- an empty {{news_archive}} or {{categories_list}} leaves nothing, with its heading, so
a site without news says so once
- images of the layout (class logo, mark or decorative, role presentation or none) leave
no link line and the file is not copied
- the command test names files instead of counting them, and -clean and the warning
about old files work for the gemini command too
Refs #10
|
||
| .forgejo/workflows | ||
| cmd/motorino | ||
| internal | ||
| scripts | ||
| .gitignore | ||
| CHANGELOG.md | ||
| go.mod | ||
| go.sum | ||
| LICENSE | ||
| Makefile | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| release.config.mjs | ||
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 and -clean work as for build
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/<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: anhttpsaddress, the post on Mastodon. The post page then has a link to reply there (the language needsreply_mastodon).Language: the language the post is written in; the default is the language of the news (below).Draft:trueoryeskeeps the post out of the site. So does aDatein the future, until that moment.motorino build -draftspublishes 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, besidespost_title,date,post_bodyandpost_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) andpost_nav(the newer post, the older post and all the news).og_typeisarticlethere andwebsiteon every other page, andarticle_metaholds the published time and a tag for each category, for the head ofbase.html. - The blog list: a paragraph with only
{{news_blog}}on the news index lists the posts as note panels (<p class="note" role="note">: 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, atpage/2/,page/3/, with a pager. The block needs an index page. - The archive: when
templates/archive.htmlexists, every year and month with posts gets a page,/news/2026/and/news/2026/11/, witharchive_name,archive_navandarchive_posts. The posts of an archive page, of a category page and of the blog list are the same panels; where the language has noread_morethe 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 indescriptionand the full text, with absolute links, incontent: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, elsegemini_languageinsite.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=enanden/**/*:;lang=en, because a*does not cross folders, and the same two lines fornews/when the news are not in the root language. It is for Agate run with--central-conf. A post that names anotherLanguagethan the news has a line of its own, with the path of its file (news/2026/11/slug.gmi:;lang=it). The server uses the first line that matches a document, so these come first, then the folders.- News. They exist once, under
/news/, as in the website: the index, the posts, the categories, the archives andnews/feed.gmi, a list of=> /news/2026/11/post.gmi 2026-11-14 Titlelines, 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 (its first cell) with a bullet for each other cell named by its column, a bullet for each row when there is no header or only one column, an image with an alt text is a link line, unless it belongs to the layout (it has the class
logo,markordecorative, or the rolepresentationornone: then nothing is written and the file is not copied), and emphasis is dropped. A list item with no text, only an image or a link, has no bullet; a preformatted block in an item follows its bullet. 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.htmlis/en/people.gmi), and a fragment is dropped. A file listed inassetsis copied when a page points to it, and only then.http,https,mailto,gemini,xmpp,irc,ircs,matrix,bitcoin,magnet,telandsmslinks 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 ofgemini_web_pathsinsite.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.