The source of truth says so. A built site has no such route. A control was in the application at a known revision and is not now.
Open source · MIT · on npm
Know which pages a change broke.
~/acme/docs $ npx pagebeam check
612 pages checked against dashboard (pagebeam.config.yaml)
ran links, config-keys, openapi, strings, undocumented · compared with 0053b5b2
docs/api/hooks.md
✗ DELETE /v1/hooks/{id} is documented but not in the dashboard specification:12
review 41d0e2c7a9f0
This page describes DELETE /v1/hooks/{id}. The dashboard specification has no such operation.
docs/guides/webhooks.md
✗ /settings/webhooks does not resolve:42
proven 9f3a1c07b2e4
This page links to /settings/webhooks. No built page and no public asset answers to it.
! "Retry delivery" was removed from dashboard:88
proven new c02e7d41a9b8
This page tells the reader to look for "Retry delivery". It was a button in dashboard and is gone.
1 openapi, 1 links, 1 strings
exit 0nothing blocks: check reports and blocks nothing
pagebeam checks every page of your documentation against the application it describes, says how sure it is, and opens the pull request that fixes what it can. In the repository you already have.
npx pagebeam initSound familiar
You shipped on Tuesday. The docs still describe Monday.
A route moves, a setting is renamed, an endpoint loses a parameter. The pull request passes review. Nobody remembers the guides that mention it, and a checklist asking them to remember fails for the same reason the drift happened.
- Changed
/settings/webhooks moved to /settings/integrationsStill documented indocs/guides/webhooks.md - Changed
RETRY_LIMIT renamed to DELIVERY_RETRIESStill documented indocs/reference/configuration.md - Changed
DELETE /v1/hooks/{id} left the OpenAPI specStill documented indocs/api/hooks.md
Docs should not depend on somebody remembering.
How it works
Three commands, in the repository you already have.
Point it at your docs
npx pagebeam initLooks at the repository and writes pagebeam.config.yaml: where the pages live and any application beside them. It says what it worked out and what it could not, so you correct it before the first run.
See what drifted
npx pagebeam checkChecks every page and reports findings grouped by the page you would open to fix them. It reads and reports: nothing is written, and nothing reaches a remote.
Get the fix as a pull request
npx pagebeam fix --publishOpens or updates one pull request with the changes it can work out from the source. Drafts written by a model open as a draft and are marked as such.
Checks
Six checks, each against a source of truth.
Each check compares a page with something that cannot be wrong about the product: the built site, the application source, its example config, its OpenAPI spec, its history.
linkson by defaultA page pointing at a route or a file that is not there.
configKeyson by defaultA setting the documentation describes that no example config declares.
openapion by defaultAn endpoint documented that the specification lacks, and operations nothing documents.
stringsoff by defaultA control named in the documentation that the application no longer has.
movedoff by defaultCode changing under a page that did not change with it.
undocumentedon by defaultA screen of controls the documentation never mentions.
strings and moved compare against an earlier revision, so they are off until you ask for them.How each check works
GitHub Actions
One workflow file, and every pull request is checked.
Add the pagebeam action to the product repository. It checks out the docs beside the product, runs pagebeam from the docs and writes what it found to the job summary. The config that works on your laptop works in CI.
Report
profile: observeThe default. Every run reports in the job summary and blocks nothing.
Gate
profile: enforceFails a pull request only on proven findings that it introduced.
Fix
command: fixIn the docs repository, on a schedule. Opens or updates one pull request with the fixes it can work out.
Docs and product in one repository? Leave out docs.Run in CI
.github/workflows/docs-drift.ymlname: docs drift
on:
pull_request:
push:
branches: [main]
jobs:
drift:
runs-on: ubuntu-latest
steps:
- uses: pagebeam/pagebeam@v1
with:
docs: your-org/docs
token: ${{ secrets.PAGEBEAM_TOKEN }}
Standing
It tells you how sure it is.
Worth a person’s time, and not proof. A label may be assembled at runtime, or live in an application no parser covers.
Only proven findings can fail a build, and only under an enforcing profile. Read about standing
No migration
Works on the docs you already have.
No migration and no new editor. pagebeam reads the pages where they live and the application beside them, or in another repository you check out next to it.
- Vue
- React
- Svelte
- Astro
- HTML
- Markdown
- MDX
- OpenAPI
Each framework is read through its own compiler. Anything else is searched as text, and the finding says so.
Bring your own model, or none.
Where a check proves a page wrong but cannot say what it should say, name a provider and pagebeam asks it once, with the page and the evidence. Any endpoint answering the OpenAI chat completions shape works. pagebeam ships no provider code and never sees a key, only the name of the variable holding one.
What leaves this machine
check sends nothing. A proposal sends the page, the finding and its evidence. Source is sent only with sendSource: true, every file sent is named in the output, and one that looks like it holds a credential is held back.
Proposals and privacyCompare
What you do today, and what changes.
| Question | A PR checklist | A link checker | pagebeam |
|---|---|---|---|
| Finds a link to a route that no longer exists | If someone notices | Yes, by crawling the site | Yes, against the built site |
| Finds a renamed setting or a removed control | If someone remembers | No | Yes, from the source |
| Finds an endpoint the spec no longer has | If someone remembers | No | Yes, from the spec |
| Says how sure it is | No | No | proven or review |
| Proposes the fix | No | No | A pull request, for what it can |
| Cost | Review time | Free | Free, MIT |
Try it on the docs you already have
Two commands, in the repository holding your documentation.
Nothing is written outside one file, and nothing reaches a remote.
npx pagebeam init npx pagebeam checkQuestions people ask first.
Do I have to move my docs?
No. pagebeam runs against the documentation where it already is: Markdown, MDX or Astro pages in your repository. If the product lives in another repository, check both out and point the config at each.
Will it fail my build?
Only if you ask it to. check reports and blocks nothing. check --profile enforce fails on proven findings the change introduced. Exit 0 means nothing blocks, 1 means a proven finding blocks, 2 means the answer cannot be trusted because nothing was read or a requested check could not run.
Does my code leave my machine?
check reads locally and sends nothing. Proposals go to the provider you name, with the page, the finding and its evidence. Source goes only when you set sendSource: true.
Which frameworks can it read?
Vue, React, Svelte, Astro, HTML and server-side templates, each through that framework’s own compiler. It can also open a running application on the routes you list, which catches labels assembled at runtime.
What does it cost?
Nothing. The CLI is open source under the MIT licence. If you use a model for proposals, that provider bills you directly.