Table of Contents

Links and citations

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Generated from docs/reference/commands/links-and-citations.md at v10.1.0 – edit the repository, not this wiki.

Links and citations

Declaring the relationships between pages and the citations that tie a claim to its source, with the generated regions that hold both.

`xref add`

Declare that A B.

Synopsis

wikitool xref add --a "<A>" --b "<B>" --rel <label> [--dry-run]

Options

  --a <str>    Exact title of the page that asserts the edge  [required]
  --b <str>    Exact title of the page it points at  [required]
  --rel <str>  Label from instructions/link-taxonomy.md, e.g. depends-on
               [required]
  --dry-run    Preview the change instead of writing
  -h, --help   Show this message and exit.

Examples

tools/wikitool xref add --a "Gitea Actions" --b "Act Runner" --rel depends-on
tools/wikitool xref add --a "Gitea Actions" --b "Act Runner" --rel depends-on --dry-run

Behaviour

Declares one edge, A <label> B: written into A's related: as - <label>: B and rendered into A's generated links region.
B is not touched and does not point back - its inbound view is rendered from the graph.
Idempotent; re-running with a different label relabels rather than appending, since one page asserts one thing about another.
Refuses before writing when A's type does not declare related: - a source page declares entities:/concepts: instead, and the refusal names them and points at xref link-source.
Refuses before writing when <label> is not authorised by the source collection's outbound: block for the target's collection; the refusal lists the authorised set and points at instructions/link-taxonomy.md.
--dry-run reports the edge without writing.

Properties

Changes files: yes
Idempotent: yes
Atomic: Yes - a single write to A; B is never touched, and every refusal happens before it
Counts toward the session call budget: yes
Can reach the network: no

Exit codes

0 - success
1 - Page A or B not found
1 - A's type declares no related: field
1 - <label> is not authorised for this collection pair, or the source collection authorises no labels into the target's collection at all

See also

wikitool xref remove - removes a reference
wikitool links show - the edges out of and into a page
instructions/link-taxonomy.md - the labels and what each asserts

`xref remove`

Remove a cross-reference: the inverse of xref add.

Synopsis

wikitool xref remove --a "<A>" --b "<B>" [--dry-run]

Options

  --a <str>   Exact title of page A (must exist)  [required]
  --b <str>   Title to unlink from A; need not still exist as a page  [required]
  --dry-run   Preview changes instead of writing
  -h, --help  Show this message and exit.

Examples

tools/wikitool xref remove --a "Gitea Actions" --b "act_runner"
tools/wikitool xref remove --a "Gitea Actions" --b "Act Runner" --dry-run

Behaviour

Clears the reference in both directions: the cleanup command for a deleted or hand-renamed page rather than the strict inverse of a one-directional xref add.
Clears <B> from every page-ref frontmatter field <A>'s type declares (related:, sources:, entities:, concepts:) plus the matching bullets.
Also sweeps a page-ref field the type does not declare but some other type does, and drops that key once empty.
--b need not still exist as a page, so this clears a reference left by a hand-deleted or hand-renamed page without hand-editing frontmatter.
Idempotent: removing an absent link is a no-op. --dry-run reports without writing.

Properties

Changes files: yes
Idempotent: yes
Atomic: No - writes A then B, both idempotent
Counts toward the session call budget: yes
Can reach the network: no

Exit codes

0 - success
1 - Page A not found (B is allowed not to exist)

See also

wikitool xref add - declares an edge
wikitool rm - deletes a page and de-links it

`xref link-source`

Batch-link a source page to every entity/concept it mentions.

Synopsis

wikitool xref link-source --source "Source - X" --entities A,B,C [--dry-run]

Options

  --source <str>    Exact source page title, e.g. 'Source - Docker Cheatsheet'
                    [required]
  --entities <str>  Comma-separated entity/concept titles the source mentions
                    [required]
  --dry-run         Preview which pages would be linked instead of writing
  -h, --help        Show this message and exit.

Examples

tools/wikitool xref link-source --source "Source - Docker Cheatsheet" --entities Docker,Podman --dry-run
tools/wikitool xref link-source --source "Source - Docker Cheatsheet" --entities Docker,Podman

Behaviour

Each target gets the source page in its sources:, and the source page records each target in its own entities: or concepts:. No body bullet is written on either side - sources: is the record.
Which field a target lands in follows its collection (kb/entities/ -> entities:), so a new collection needs no code change.
A target whose collection matches no reference field the source type declares is linked one way and named in the output.
A target that does not exist is skipped and named; the others are still linked, and the run then exits 1.
A target that is itself a source page is refused, named with the cite add command to use instead, and handled like a missing page: nothing is written for it, the others are still linked, and the run exits 1. link-source means "A mentions X" and writes X.sources += A, which for X = another source would claim the citation in the wrong direction; a citation between two sources has a direction only cite add records.
Idempotent in both directions. --dry-run reports what would be linked.

Properties

Changes files: yes
Idempotent: yes
Atomic: No - one write per entity plus one for the source page, idempotent per page
Counts toward the session call budget: yes
Can reach the network: no

Exit codes

0 - success
1 - Source page not found
1 - A page in --entities does not exist, or a target could not be written; the others were linked
1 - A page in --entities is itself a source page; the others were linked
1 - The source page itself could not be written after its targets were

See also

wikitool sources trace - who a source is already linked to
wikitool xref add - one labelled edge between two pages
wiki-ingest skill - where a source is linked after it is written

`links show`

Show the edges out of and into a page.

Synopsis

wikitool links show --page "<Title>" [--json]

Options

  --page <str>  Exact page title  [required]
  --json        Print the edges as JSON
  -h, --help    Show this message and exit.

Examples

tools/wikitool links show --page "Act Runner"
tools/wikitool links show --page "Act Runner" --json

Behaviour

Shows the declared graph around one page in both directions: the edges it asserts (from its own related:, with labels) and the edges other pages assert about it.
The inbound half is computed across the corpus on every call, never stored, so it is complete.
--json prints both halves as JSON.
Read-only; exempt from the Iteration Budget Gate.

Properties

Changes files: no
Idempotent: yes
Atomic: Read-only
Counts toward the session call budget: no
Can reach the network: no

Exit codes

0 - success
1 - Page not found

See also

wikitool xref add / wikitool xref remove - change the outbound edges
wikitool search - finds the exact title

`cite id`

Print the deterministic footnote id cite add would use for this (title, file) pair.

Synopsis

wikitool cite id --title "Source - X" [--file <qualifier>]

Options

  --title <str>  Source page title, e.g. 'Source - Docker Cheatsheet'
                 [required]
  --file <str>   Qualifier for a multi-file source, e.g. 'storage-model.md'
  -h, --help     Show this message and exit.

Examples

tools/wikitool cite id --title "Source - Docker Cheatsheet"

Behaviour

Prints the footnote id cite add would use for this (title, file) pair.
A preview only: it does not check that the id is free on any given page.
Never fails; safe to retry freely. Read-only and exempt from the Iteration Budget Gate.

Properties

Changes files: no
Idempotent: yes
Atomic: Read-only
Counts toward the session call budget: no
Can reach the network: no

Exit codes

0 - success

See also

wikitool cite add - writes the definition

`cite add`

Upsert a [^cite-id]: [[Source - X]] definition in a page's footnotes region.

Synopsis

wikitool cite add --page "<Title>" --source "Source - X" [--file <qualifier>] [--dry-run]

Options

  --page <str>    Exact title of the page to add a citation on  [required]
  --source <str>  Exact title of the source page being cited, e.g. 'Source - X'
                  [required]
  --file <str>    Qualifier for a multi-file source, e.g. 'storage-model.md'
  --dry-run       Preview instead of writing
  -h, --help      Show this message and exit.

Examples

tools/wikitool cite add --page "Docker" --source "Source - Docker Cheatsheet"
tools/wikitool cite add --page "Docker" --source "Source - Docker Cheatsheet" --file part-2

Behaviour

Upserts a [^cite-id]: [[Source - X]] definition in the page's generated footnotes region, creating the region between  markers if absent.
Reuses the id when the page already cites this exact source/file pair, so a repeat changes nothing.
Adds Source - X to the page's frontmatter sources: - except on Source - X itself: a source page citing one of its own raw files (--file) gets the definition and leaves sources: untouched, since a page never lists its own title there.
A source page may cite another source page this way - cite add is the command that records a citation between two sources, in the direction it was made.
Prints the [^cite-id] marker; pasting it into the prose is a manual, editorial step.
--dry-run reports without writing.

Properties

Changes files: yes
Idempotent: yes
Atomic: Yes - single file write
Counts toward the session call budget: yes
Can reach the network: no

Exit codes

0 - success
1 - The page is not found
1 - The source page is not found - citing it would be a dangling reference

See also

wikitool cite sync - prunes and re-orders the region
wikitool cite id - previews an id

`cite sync`

Reconcile each page's footnotes region against its actual [^id] references.

Synopsis

wikitool cite sync [--page "<Title>" | --all] [--dry-run]

Options

  --page <str>  Sync just this page
  --all         Sync every page under kb/
  --dry-run     Report what would change instead of writing
  -h, --help    Show this message and exit.

Examples

tools/wikitool cite sync --page "Docker"
tools/wikitool cite sync --all --dry-run

Behaviour

Prunes definitions nothing references any more, re-renders the region in first-reference order, and reports every [^id] reference left with no definition.
An undefined-reference report is not a failure: fix the reference, or run cite add, and re-run.
A page still carrying the pre-4.0.0 undelimited footnote block is converted to a marked region in the same pass.
Each page's re-render is idempotent; safe to retry freely. --dry-run reports without writing.

Properties

Changes files: yes
Idempotent: yes
Atomic: No - one write per page, each idempotent
Counts toward the session call budget: yes
Can reach the network: no

Exit codes

0 - success
1 - Neither or both of --page/--all given, or the page is not found
1 - A page write failed partway

See also

wikitool cite add - writes a definition