Anomalies

Two structural facts colophon reports without judging them: a label nothing ever points back to, and a bibliography entry nothing ever cites. Neither is wired to contexture.diagnose/strict the way a diagnostic elsewhere in this ecosystem might be — an orphan label or an unused reference is often entirely deliberate (a supplementary figure described elsewhere, a reference cited only in a cover letter rather than the manuscript body), so colophon lists it and leaves the judgment to you.

orphan-labels(start, end): every labelled heading, figure, or equation in the manuscript’s span that no ref/@label anywhere in the whole bundle ever targets — deliberately bundle-wide on the referencing side (a figure could legitimately be cited from another package’s own satellite, an checkitoff checklist excerpt say), only the candidate labels themselves are scoped to the manuscript.
bib-keys(path) / uncited-references(path, start, end): every entry a .bib file defines that no @key/cite(<key>) in the manuscript’s span actually cites. path must be root-relative (a leading /, resolved against --root) — the same gotcha palimpsest’s own letter-bibliography already documents, for the same underlying reason: Typst resolves a path string against the file that calls the path-consuming builtin, not the file that wrote the literal.

A heading whose label is never referenced, a figure that is, and one that isn’t, plus one bibliography entry never cited:

#import "../../lib.typ": *
#import "../../../typst-contexture/lib.typ" as contexture

#let my-template(body) = {
  set page(width: 16.6cm, height: auto, margin: 12pt)
  set text(size: 10.5pt)
  set heading(numbering: "1.")
  body
}

#show: contexture.bundle.with(
  template: instrument(template: my-template),
  documents: (
    report(bib: "/typst-colophon/docs/manual-snippets/anomalies-basics-refs.bib"),
  ),
)

= Introduction <sec-intro>

Some background, citing prior work @smith2020 -- this heading's own
label, `<sec-intro>`, is never referenced anywhere, unlike the figure
below.

#figure(rect(), caption: [Referenced figure.]) <fig-a>

See @fig-a for the referenced figure above.

#figure(rect(), caption: [Orphan figure, never referenced anywhere.]) <fig-orphan>

#bibliography("anomalies-basics-refs.bib")

bib:, passed to report(...), is what turns the bibliography section on at all — omitted (none, the default), the “Bibliography entries never cited” heading doesn’t appear, since not every manuscript has one file to point at:

#report(bib: "/manuscript.bib")

An orphan figure never shows up here

Look closely at the example above: <fig-orphan> is a genuine orphan — captioned “Orphan figure, never referenced anywhere,” no @fig-orphan anywhere in the source — yet only the heading’s label, sec-intro, appears in “Labels never referenced.” This holds across every example in this manual that has an orphan figure, not just this one: figure-inventory (the previous chapter) itself renders each figure’s number via ref(label), and that call is, structurally, a real reference to that same label — so the moment a figure appears in the “Figures and tables” section above, it already counts as “referenced” for this check’s purposes, whether or not the manuscript’s own prose ever points back to it. In practice: this check reliably catches an orphan heading or equation, but never an orphan figure or table specifically — for those, the “Figures and tables” section itself, read by eye, is the real inventory to check against.

← Figure and table inventory

Wiring a real project →