Universe

sanity checks for your Typst documents

Manual, as a PDF GitHub repository

sanity is a simple Typst package to find unreferenced figures, uncited sources and lost labels.

#import "@preview/sanity:0.1.0": *

#show: sanity

With these lines, whenever there is something to report, a page is attached listing what was found, just like this:

Six findings, each with its severity, its message, the id of the check that made it, and a link to the page it is on.

Needs Typst 0.14 or newer. The command line script additionally needs 0.15, since it uses typst eval.

Manual

It is worth checking docs/manual.pdf for package details. It contains a description of each check (what it reports) as well as the configuration and exceptions!

On this page you can check out what it checks, bibliography, the command line and recipes.

What it checks

Twelve checks are performed by default as soon as you apply the show rule, including checks for figures, tables, listings, and equations, and others. Only elements you labelled yourself are reported as unreferenced. An unlabelled figure cannot be pointed at and is often decorative.

The manual gives each check an entry of its own.

Bibliography

uncited-entry needs the bibliography data, and a package cannot read your .bib. From the command line, bin/sanity reads it for you. But inside the document you can hand it over:

#show: sanity.with(bibliography: read("refs.bib"))

BibTeX and Hayagriva files are both understood.

From the command line

You can also use bin/sanity script (and it reports on a document without touching it). It exits 1 on a warning/error, 0 when there is nothing to report, and 2 when the document does not compile.

$ bin/sanity paper.typ
warning: figure <fig:latency> is never referenced [unreferenced-figure]
  ┌─ page 4

sanity: 1 warning

You can download it here instead, since packages can’t include executables.

curl -sSLO https://raw.githubusercontent.com/techgustavo/sanity/main/bin/sanity
chmod +x sanity

--help lists the flags.

Recipes

Check a document without touching it

With the one-file script

bin/sanity paper.typ
Check the bibliography too

A package cannot open your .bib, so the document hands the data over

#show: sanity.with(bibliography: read("refs.bib"))
Let one figure go unreferenced

This one is decorative, so nothing is ever going to point at it

#sanity-ignore(<fig:cover>, reason: "decorative")
Silence one check on one element

The element stays under every other check

#sanity-ignore(<fig:map>, checks: "unreferenced-figure")
Turn a check on or off

By the id, which the manual lists for each check

#show: sanity.with(checks: ("reference-order": true, "empty-caption": false))
Fail the compilation instead of appending a page 
#show: sanity.with(strict: true)
Gate a pull request on the findings

A workflow that fails when the manuscript does

name: manuscript
on: [push, pull_request]

jobs:
  sanity:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: typst-community/setup-typst@v5
      - run: |
          curl -sSLO https://raw.githubusercontent.com/techgustavo/sanity/main/bin/sanity
          chmod +x sanity
          ./sanity paper.typ

Thanks for considering this package!