Diagnostics: the addresses file and API specs

The diagnostics about ascribe.addresses, the addresses a base published, and the OpenAPI specs ascribe.toml declares.

For AI agents: the documentation index is at llms.txt, and this page is available as Markdown.

The problems Ascribe reports in ascribe.addresses and in comparing the addresses the docs publish with a base’s, and in the OpenAPI specs [apis] declares. Part of the diagnostics reference, which says what an entry’s severity, level, and next step mean, and has an index of every diagnostic.

Addresses file

ASC254 `addresses-file-invalid`

Error · file level · next step: write · SPEC §7.10

When: ascribe.addresses isn’t valid TOML, or doesn’t have the shape §7.10 gives it.

Message: ascribe.addresses can’t be read: {detail}

Fix: ascribe.addresses is written by ascribe rename, the editor’s moves, and ascribe addresses. Undo the change made to it by hand, other than to a retired address’s reason, or, for a file from a newer version of Ascribe, update Ascribe. Don’t delete the file to quiet this: it’s what keeps the addresses the docs have published working, and the build writes no redirects without it.

Read more: ascribe.addresses in the guide to keeping addresses.

ASC255 `address-lost`

Warning · file level · next step: write · SPEC §7.10

When: A page’s address, or its Markdown version’s, that the base published and nothing accounts for.

Message: {source} was published at {addresses}, and nothing publishes them now{builds}

Fix: Decide what a reader who follows an old link should get. When the content is somewhere else now, forward it: ascribe addresses move <old> <new> records where it went, and the build writes the redirect. When it’s gone on purpose, retire it: ascribe addresses retire <old> --reason "…". When it was deleted by mistake, restore the file. Moving a page with ascribe rename, or in the editor, records the move for you. When a routing setting moved them, as base-path, permalink-path, agents, or a build’s name, ascribe check --fix records the old value in [former], and the build forwards every address it moved. The base is the default branch, or --base; see Keep the addresses you’ve published.

Read more: What the check reports in the guide to keeping addresses.

ASC256 `anchor-lost`

Advice · file level · next step: write · SPEC §7.10

When: A heading’s explicit id that the base published on a page still published, and nothing accounts for.

Message: the id {id} in {path} was published at {addresses}, and the page doesn’t have it now{builds}

Fix: Put the @id back on the heading that covers it now, so links to it keep working, or record where it went: ascribe addresses move <file>#<old> <file>#<new>, or ascribe addresses retire <file>#<old> --reason "…". A link’s fragment never reaches the host, so no redirect can follow it yet; the entry is kept for when one can.

Read more: What the check reports in the guide to keeping addresses.

ASC258 `addresses-build-gone`

Advice · file level · next step: outside · SPEC §7.10

When: A build the base has and the working tree doesn’t, other than a line archived now.

Message: the base has the build {build}, and ascribe.toml doesn’t now, so its {count} addresses aren’t compared

Fix: Nothing to do when the build was removed on purpose: its addresses aren’t compared, since builds are matched by name. A line [releases] archives isn’t reported: ascribe versions retire records where its addresses go. When the build was renamed, its addresses are compared under its new name once the base has it.

Read more: What the check reports in the guide to keeping addresses.

ASC265 `addresses-entry-not-a-page`

Error · file level · next step: choose · SPEC §7.10

When: A [moved] value that isn’t a page, or a heading on one, in every build that published its key, or, for a permalink, a permalink the content declares.

Message: {key} is forwarded to {value}, which isn’t a page of the project, so no build writes its redirect

Fix: Forward it to a page every build that published it publishes: ascribe addresses move <old> <new> replaces the entry. A permalink, go:<name>, can also be forwarded to another permalink, go:<other>, that a heading’s @id {permalink=true} or a page’s permalink declares. When nothing replaces it, retire it instead: ascribe addresses retire <old> --reason "…". A fragment, a path outside the content root, or a page a build leaves out would send a reader to nothing.