# The checked stamp
A one-line stamp on each page of your docs site that says what Staleproof checked on that page, against which commit and when, or how many references on it are out of date. One script tag adds it to any site; plugins do it for Docusaurus and MkDocs, and a snippet covers Mintlify and plain HTML. This page covers what the stamp says and what it means, how to add it, the JSON it reads, privacy, and its limits. It is for docs teams who want readers to see that the page in front of them was checked, and to see it when it is not.
## What it says
The stamp reads the repository's [docs audit](audit.md) on the Staleproof server and finds the page's source file in it. It renders one of three things:
| State | The stamp | When |
|---|---|---|
| Checked | ✓ Examples and references checked against `abc1234` · 2 days ago · Staleproof | Nothing on the page is out of date at the indexed commit |
| Drift | ⚠ 2 references on this page are out of date · checked against `abc1234` · 2 days ago · Staleproof | The page has error or warning findings, example lines that no longer fit the code, or examples that fail when run |
| No data | nothing | The repository was never audited on the server, or the page is not one of its docs pages |
The wording says exactly what was checked, never more:
- **References** are the paths, links, anchors, commands, CLI flags and env vars the page names, [linted](lint.md) at index time. A repository indexed before Staleproof 0.5 has no reference checks, so its stamps say "Examples checked".
- **Examples** are the page's code examples, checked statically against the signatures and names their calls reach. A page with no code examples says "References checked".
- **Runs**: only when examples on the page were actually run at the indexed commit does the stamp add "· 3 examples ran". The hosted service never runs examples, so on staleproof.dev this part appears only for repositories whose runs were recorded elsewhere. The stamp never says a page was verified by running when nothing ran.
- The commit is the one the repository was indexed at, and the time is when it was indexed: the stamp shows how fresh the check is, not when the reader opened the page.
"Staleproof" links to the repository's full audit, where every finding is listed with its line.
## Add it to your site
The repository must have been audited once on the server: open `https://staleproof.dev/#/audit?repo=owner/name` (or `POST /api/audit`). Hosted workspaces are indexed again when they are a week old, and the stamp follows. Pages show nothing until then.
### Docusaurus
```bash
npm install docusaurus-plugin-staleproof
```
```js
// docusaurus.config.js
export default {
plugins: [['docusaurus-plugin-staleproof', { repo: 'owner/name' }]],
};
```
The plugin loads the stamp script on every page, adds `` with each doc's source file (built into the static HTML), and wraps `DocItem/Footer` with the slot the stamp renders into, at the bottom of each doc. It renders the stamp again after client-side navigation. Options: `repo` (default `organizationName/projectName`), `server` (default `https://staleproof.dev`), `sitePath` (the site's folder in the repository, found from the nearest `.git`, so a site in `website/` names `website/docs/intro.md`). Docusaurus 3.
### MkDocs
```bash
pip install mkdocs-staleproof
```
```yaml
# mkdocs.yml
repo_url: https://github.com/owner/name
plugins:
- staleproof
```
The plugin adds the meta tag and the script to every page (`on_post_page`) and a slot under the page title (`on_page_content`). Options: `repo` (default from `repo_url`), `server`, `docs_path` (the docs folder relative to the repository root, worked out from `docs_dir` by default), `placement` (`top`, `bottom` or `none`). With Material for MkDocs' instant navigation the stamp renders again on each page; keep `placement` at `top` or `bottom` there, since the slot travels with the page content.
### Mintlify
Mintlify includes every `.js` file in the docs folder on every page. Add `staleproof.js`:
```js
// staleproof.js: the Staleproof stamp. Pages map to their .mdx source by URL.
(function () {
var s = document.createElement('script');
s.src = 'https://staleproof.dev/api/verified/owner/name/stamp.js';
s.async = true;
s.referrerPolicy = 'no-referrer';
s.setAttribute('data-map', 'docs/{path}.mdx docs/{path}/index.mdx');
document.head.appendChild(s);
// Client-side navigation: render again when the path changes.
var last = location.pathname;
setInterval(function () {
if (location.pathname !== last) {
last = location.pathname;
if (window.StaleproofStamp) window.StaleproofStamp();
}
}, 1000);
})();
```
Change `docs/` to where the `.mdx` files are in your repository.
### Any HTML page
```html
```
The script finds the page's source file, first match wins:
1. an element ``: the stamp renders inside it;
2. ``;
3. the script tag's `data-path="docs/install.md"`;
4. the script tag's `data-map`: patterns filled with the URL path, tried in order: `data-map="docs/{path}.md docs/{path}/index.md"` maps `/guide/install/` to `docs/guide/install.md`, then `docs/guide/install/index.md`, and `/` to `docs/index.md`. `data-base="/project/"` drops a prefix from the URL path first (GitHub Pages project sites).
Without a slot, the stamp goes into `data-target` (a CSS selector on the script tag), else right after the first `h1` in `article` or `main`, else at the end of the page. After client-side navigation, call `window.StaleproofStamp()`: it replaces the old stamp.
### Look
The stamp is a small bordered line in the page's own font and text colour, so it fits light and dark themes. Only the icon and border are tinted (green, amber), with colours for dark mode from `prefers-color-scheme` and from the site's own theme switch (`[data-theme=dark]` in Docusaurus, `.dark`, Material's `slate` scheme). It is an `aside` labelled "Staleproof docs check"; the icon is hidden from screen readers (the words carry the state), the time is a `