ascribe addresses

Keep ascribe.addresses: make it, record a move or a retired address, and list the redirects each build writes, with each command’s options and output.

ascribe addresses keeps ascribe.addresses, the record of where the addresses the docs published went: it makes the file, records a move or a retired address, and lists the redirects each build writes. Keep the addresses you’ve published is the task the commands are used in.

The options every command accepts are in the command reference.

ascribe addresses

Keeps ascribe.addresses. Each takes --format json, and writes the document its schema describes. Each exits with 0 when it’s done, and 2 when it couldn’t run: the project doesn’t load, or the file can’t be read or written.

ascribe addresses init

Makes ascribe.addresses, with its header, its version, and empty tables. A file already there is left as it is, and it says so.

In a project whose ascribe.toml still has [permalinks], from before ascribe.addresses recorded permalinks, it moves the table’s entries into the file, made or already there, and takes the table out of ascribe.toml, keeping the rest of the file as written. Each of [permalinks.retired] goes in [retired] as go:<name>, or in [moved] to its to when it has one. Each of [permalinks.aliases] goes in [moved] as go:<name>, leading to go: and the name it leads to. Run ascribe permalinks sync after, when the project has ascribe.permalinks. A base whose ascribe.toml still has the table is read as if it had been moved, so the move itself loses no address.

• --dry-run: Say what it would change, and change nothing.
• --force: Change files even when git couldn’t put them back as they are: ones with changes not committed, ones git doesn’t track, or ones in no repository.
• --format <FORMAT>: How to show what was done.
  • text (the default): Short text, for people and agents to read.
  • json: One JSON document, for tools.

ascribe addresses move

Records that a page, or a heading’s id, moved, after a move made without Ascribe, as with git mv. The old path is gone; the new one is a page of the project, or a heading on one. A permalink no heading declares any more, go:<name>, moves to a page or a heading, or to another permalink, go:<name>.

$ ascribe addresses move guides/keys.md security/keys.md
Recorded in ascribe.addresses: guides/keys.md moved to security/keys.md.

Each page’s path is from the current folder or from the content root, and the entry is from the content root. So, from a repository’s root whose project is in docs/ with its content in docs/content/, ascribe addresses move --config docs docs/content/guides/keys.md docs/content/security/keys.md records the same entry, and so does ascribe addresses retire given such a path.

--from-git records every move git sees between the base and the working tree whose old path is gone, one entry for each page, so a reorganization made with git mv is recorded at once. The base is chosen as ascribe check chooses it, with --base and --base-exact. Git sees a file that’s renamed and added, as git mv leaves it, and only when the old and new files are mostly the same: a page rewritten as it moved is forwarded with ascribe addresses move <old> <new>.

$ ascribe addresses move --from-git
Recorded 1 move git sees: guides/setup.md → start/setup.md.

• [OLD]: Where it was: a page’s path, from the current folder or from the content root; a file’s path, #, and a heading’s id; an address from the host’s root, starting with /, from before the project used Ascribe; or a permalink, go:<name>, nothing declares now.
• [NEW]: Where it is now: a page’s path, from the current folder or from the content root, and optionally # and a heading’s id; or, for a permalink, another permalink, go:<name>.
• --from-git: Record every move git sees between the base and the working tree whose old path is gone, one entry for each page, as after a reorganization made with git mv. Git sees a file renamed and added, and only when the old and new files are mostly the same.
• --base <REV>: With --from-git, the revision git’s renames are seen from: anything git accepts. By default, the repository’s default branch, from its merge base with HEAD, as ascribe check chooses it.
• --base-exact: With --from-git, see the renames from the base revision itself instead of its merge base with HEAD.
• --dry-run: Say what it would change, and change nothing.
• --force: Change files even when git couldn’t put them back as they are: ones with changes not committed, ones git doesn’t track, or ones in no repository.
• --format <FORMAT>: How to show what was recorded.
  • text (the default): Short text, for people and agents to read.
  • json: One JSON document, for tools.

ascribe addresses retire

Records that a page, or a heading’s id, or a permalink, go:<name>, was removed on purpose, with the reason, which is for whoever reads the file later.

$ ascribe addresses retire reference/legacy-sync.md --reason "The sync agent was removed in 4.0"
Recorded in ascribe.addresses: reference/legacy-sync.md was retired.

• OLD: What was removed: a page’s path, from the current folder or from the content root; a file’s path, #, and a heading’s id; an address from the host’s root, starting with /; or a permalink, go:<name>, nothing declares now.
• --reason <TEXT>: Why it was removed.
• --dry-run: Say what it would change, and change nothing.
• --force: Change files even when git couldn’t put them back as they are: ones with changes not committed, ones git doesn’t track, or ones in no repository.
• --format <FORMAT>: How to show what was recorded.
  • text (the default): Short text, for people and agents to read.
  • json: One JSON document, for tools.

ascribe addresses list

Shows the redirects and retired addresses each build writes, as its _ascribe/redirects.json has them, and the entry of ascribe.addresses each comes from. It changes nothing.

• --build <NAME>: Show only this build. By default, every build in ascribe.toml.
• --format <FORMAT>: How to show the redirects.
  • text (the default): Short text, for people and agents to read.
  • json: One JSON document, for tools.

See also

• Keep the addresses you’ve published: what the check reports, how to fix a lost address, and what the build writes.