Check your repository

stemin check reads a repository and runs the compile that runs in the browser of a learner when they add it. It writes nothing. So a repository that passes the check imports, and a repository that fails the check does not. The checker reports every fault it finds, each with its file and its line. Run it before each push, and in CI.

Get the checker

Download it

Download the binary for your platform from the releases of the checker. Each file needs nothing else. The links below always give the latest release.

On Linux and macOS, download the binary and the hashes with curl, compare the hash, and put the binary on your path. On macOS, use curl: a browser marks a downloaded file, and macOS then refuses to run it. curl sets no mark.

curl -LO https://github.com/stemin-app/stemin-checker/releases/latest/download/stemin-aarch64-macos
curl -LO https://github.com/stemin-app/stemin-checker/releases/latest/download/SHA256SUMS
grep stemin-aarch64-macos SHA256SUMS | shasum -a 256 -c
chmod +x stemin-aarch64-macos
mv stemin-aarch64-macos /usr/local/bin/stemin

On Linux, use sha256sum in place of shasum -a 256, and the name of the Linux file. If you downloaded the file on macOS with a browser, remove the mark first:

xattr -d com.apple.quarantine stemin-aarch64-macos

On Windows, download the .exe file and run it from a terminal.

Build it from source

The checker is open source, in stemin-checker. You need Rust 1.93 or later. Get it through rustup.

cargo install --locked --git https://github.com/stemin-app/stemin-checker stemin

This puts the stemin command in ~/.cargo/bin.

Run it

stemin check
stemin check /path/to/your/repository
stemin check /path/to/your/repository --url https://github.com/alice/algebra

Without a path, it checks the current directory. The path is the root of the repository: the directory that holds the root index.md. --url is optional. The app makes the id of each domain from the address of the repository, and the check passes or fails the same way with any address.

A valid repository gives one line, and the exit code 0:

INFO . is a valid content repository

A repository with faults gives one line per fault, a count, and the exit code 1:

ERROR ./math/alg/linears/solving.md:6: the LaTeX `\frac{a}` will not render: parsing error: expected a token
ERROR ./math/alg/linears/solving.md:6: `reference:nope` names no reference in this domain
ERROR 2 faults

Each line gives the file, a line number where the checker knows one, and the fault. The file path starts with the path you gave. In a terminal the output has colour; in a CI log or a pipe it is plain text.

The checker works in two steps, as the import does:

1. The structure. It reads every file, and checks the tree, the front matter, the blocks, the plots and the graph of topics. It reports every fault of this step in one run.
2. The compile. It renders every card, flashcard, reference and exam, and resolves every link and every picture. It reports every fault of this step in one run.

The compile runs only when the structure has no fault, because a file that does not load would give false faults about the links to it. So fix the faults of the first step, and run the checker again. A fault that stops the parse of a file can also cause a second fault in its parent: fix the first one, and the second one goes too.

What the structure step finds

The messages below leave out the word ERROR and the path you gave.

What the compile step finds

One fault reaches no tool: an expression in a plot that gives no value. The mark then does not show. Open the card in the app and move each slider across its range (Live plots).

See the result

The checker writes nothing. To see what a learner gets, push the repository and add it in the app (Publish and add to Stemin). The app compiles it with the same code, so a course that passes the checker opens.

CI

This GitHub Actions job downloads the checker, compares its hash, and checks the repository on each push:

name: check
on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Get the checker
        run: |
          curl -LO https://github.com/stemin-app/stemin-checker/releases/latest/download/stemin-x86_64-linux
          curl -LO https://github.com/stemin-app/stemin-checker/releases/latest/download/SHA256SUMS
          grep stemin-x86_64-linux SHA256SUMS | sha256sum -c
          chmod +x stemin-x86_64-linux

      - name: Check the repository
        run: ./stemin-x86_64-linux check .

The job fails when the checker finds a fault, and its log lists each fault with its file and its line.