# The roro9stack site

Source of https://roro9stack.net (docs/milestones/W1.md): a [Zola](https://www.getzola.org/) site. The home page, an Install page with a browser flasher, and the list of releases so far; the user guide, how-tos, FAQ and developer docs come next.

```
config.toml           base_url, the repository and API addresses
content/              the pages (Markdown, with their template named in the front matter)
templates/            base, home, install, downloads, 404; illustrations/ is generated
data/                 the App cards and the screenshots' captions
static/               css, js, fonts (self-hosted), img, screens (real screenshots), vendor/esp-web-tools
tools/                make_illustrations.py, check_site.py
```

## Build and look

```sh
docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/repo" -w /repo/site ghcr.io/getzola/zola:v0.22.0 build   # writes ./public
docker run --rm -u "$(id -u):$(id -g)" -p 1111:1111 -v "$PWD:/repo" -w /repo/site ghcr.io/getzola/zola:v0.22.0 serve --interface 0.0.0.0
python3 site/tools/check_site.py public    # what the pages promise, kept
```

Or `zola build` with a Zola of your own, in `site/` (or `zola --root site build` from the root). **The output goes to `public/` at the root of the repository,** not into `site/`: `output_dir` in `config.toml`, and git ignores that directory. The build reads the latest release and the list of releases from the Gitea API (`load_data`); if the server can't be reached, the pages say so instead of failing.

## Publishing

The web server pulls `main` and runs `zola build`, as for the blog. CI (`.gitea/workflows/site.yml`) builds the site and runs the checks when `site/`, `docs/`, `README.md` or `CONTEXT.md` change; the firmware workflow skips a change that touches only those.

## Things to know

- **The Install page needs Caddy's help.** Gitea's release downloads carry no CORS header, so the page asks the API from the browser only if Caddy, in front of Gitea, allows this origin:

  ```caddy
  @releases {
      method GET HEAD
      path /twisla/roro9stack/releases/download/* /api/v1/repos/twisla/roro9stack/releases*
  }
  header @releases Access-Control-Allow-Origin "https://roro9stack.net"
  header @releases Vary Origin
  ```

  Without it the page says it can't reach the release server and points to the esptool steps.
- **No third-party requests.** Fonts and the flasher library are served from here; `tools/check_site.py` fails the build if a page loads anything from another origin.
- **Illustrations.** `templates/illustrations/*.html` are generated by `tools/make_illustrations.py`; run it again rather than editing them.
- **Updating the flasher library:** see `static/vendor/esp-web-tools/README.txt`.
- **Fonts** are DM Mono and Hanken Grotesk, under the SIL Open Font License (the licences are in `static/fonts/`).