motorino/README.md

65 lines
2.8 KiB
Markdown

# 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 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.
-
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`.
Pages: `Title`, `ID` (the same in every language, it links the translations), `Description`, and optionally `Layout` (`page`, `bare` or `manifesto`), `Note` and `Switch`.
### 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. `{{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.
## 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.