Skip to content

D0017 book-build-stamp

Rule: The book's footer shows the crate's version, commit and build age.

Code D0017 (stable, never reused)
Id book-build-stamp
Category book
Source spirit_level
Fix by hand

Level per tier

Tier Level Reason
small warn without a version, commit and age in the footer, a reader cannot tell which build they are looking at
small-workspace warn without a version, commit and age in the footer, a reader cannot tell which build they are looking at
medium warn without a version, commit and age in the footer, a reader cannot tell which build they are looking at
big warn without a version, commit and age in the footer, a reader cannot tell which build they are looking at
ai off
embedded off
ui off
egui off
units-strict off
units-paranoid off

Parameters

Name Type Default Meaning
partial string "partials/copyright.html" the override template, relative to the theme's custom_dir, that is expected to carry the footer's build stamp
marker string "stamp" text that marks a build stamp in the partial, an extra_javascript file or the built site's index.html
age-marker string "ago" text that marks the stamp showing the build's age from the reader's own clock, beside the absolute build time

Why

A reader of a built book cannot tell which version of the project they are looking at, or how stale the page is: two tabs of the same URL opened months apart look the same. exact_units' book answers this in its footer: the crate's version, the git commit it was built from (-dirty when the tree had changes) and the build time in UTC, written into a generated overrides/partials/stamp.html that overrides/partials/copyright.html includes. A small script turns the build time into the age the reader actually cares about, coarser as it grows ("built 40 s ago", "12 min ago", "3 h ago", "5 days ago"), with the absolute UTC time kept beside it.

The lint looks for this practice: an override partial (or the built site) that carries a build stamp, and a script that shows the stamp's age from the reader's own clock, not only its absolute time.

How to fix

Give the theme a custom_dir ([project.theme] custom_dir = "overrides" in zensical.toml), add an override partial your footer includes (partial, partials/copyright.html by default) that pulls in a generated stamp with the crate's version, commit and build time, and add a script, inline or as an extra_javascript file, that renders the build's age from Date.now(), coarser as it grows. See the pattern in exact_units (docs_ext/eu_docs_ext/stamp.py, overrides/partials/copyright.html).

Configure

[lints.book-build-stamp]
level = "deny"
partial = "partials/copyright.html"
marker = "stamp"
age-marker = "ago"
reason = "why this project wants it at this level"

Allow one finding in the code with // spirit-level: allow(book-build-stamp) <reason> (waivers); the code works there too, as in [lints.D0017].