mnema.work

The source of mnema.work: the presentation of mnema, its documentation at /docs/<page> and the page that verifies its own record at /record/.

This repository holds the build and the presentation. It holds no copy of the documentation, the README or the record: every page is read, at build time, from a checkout of one release tag of the product, and the site says which one in its footer (the version and the commit it was built from).

Build it

Build the product at a release tag, then the site against it:

git clone --depth 1 --branch v0.1.5 https://github.com/mnema-work/mnema.git product
(cd product && pnpm install --frozen-lockfile && pnpm build)

npm ci --ignore-scripts
node build/build.mjs --from product        # the site, in dist/
PRODUCT_DIR=product npm test               # the built pages held to their sources

Node ^24.15.0 || >=26.0.0. The checkout is given, never looked for: --from <dir> or PRODUCT_DIR. The build refuses a directory that is not exactly at a release tag, that has a tracked file changed or that was not built.

To check the docs of any commit of the product, for example the head of a pull request, add --check: node build/build.mjs --from <checkout> --check. The checkout may be at any commit and need not be built (a tracked file changed is still refused). It builds the pages of docs/ with the same links, table of contents and Starlight build as a release, and stops on what a release build stops on for them; it does not write /record/, og.png, llms.txt, robots.txt or the favicon, which need a release and the product built, and what it builds is for throwing away.

What the build does

1. Writes the pages of docs/ (folders included: docs/<folder>/<page>.md is at /docs/<folder>/<page>/, and a README item that points at an index page in a folder is a group of the sidebar), the table of contents at /docs/ and the 404 from the checkout (build/the-build.mjs, build/the-pages.mjs), with the links rewritten to where they land, and the facts the home page shows (the measured counts, the hosts and their rungs, the install commands, the verdict of the record), read from the same checkout (build/the-home.mjs). The home page itself, /, is src/pages/index.astro: its words are the page's, and a test holds every number, host and command in it to the file it is read from.
2. Lets Astro build the home page and Starlight the docs, both in the palette of build/the-palette.mjs and set in two typefaces served from this site (@fontsource, Open Font Licence: no page asks another host for anything), with its anonymous usage data off.
3. Writes /record/ with the binary built from the same checkout, and stops when the record does not verify. The binary is the one of that tag, built from its sources, and not a version taken from npm: the site is made of one tag, and a tag does not depend on when a package reaches a registry.
4. Adds og.png, llms.txt, robots.txt, the favicon (the bare M, drawn from the same sources as the extension's icon) and the CNAME.

The two addresses the build is made around are in build/the-site.mjs and nowhere else.

Publishing

.github/workflows/site.yml builds on every pull request, builds and deploys on a push to main, and every day asks the product for its latest release tag (git ls-remote, no token): it deploys only when the version the live site says it was built from is not that tag. The deploy job holds pages: write and id-token: write and nothing else.

.github/workflows/scanners.yml reads package-lock.json against OSV (osv-scanner, the pinned release binary) on every push and pull request and every Monday. It is not a required check: a red is read, not waived.

Licence

Apache-2.0, as the product: see LICENSE and NOTICE.