How do I show a doc by UUID?

Table of Contents

For finding the UUID in the first place by regex, tag, type, or folder, see How do I find docs matching a pattern?.

Question

I have a UUID (e.g. from an [[id:...]] link, a compass list row, or a glossary entry) — how do I see the document it points to, the context around it, and the docs that link to or from it?

Answer

Run ./projects/ores.compass/compass.sh show with the UUID. Any unambiguous prefix of 6 or more hex characters is accepted.

  1. By full UUID:

    ./projects/ores.compass/compass.sh show 47341fc6-b8fb-499e-aae0-f4ee0abfda05
    
  2. By prefix — short but unambiguous (typically 8 chars is plenty):

    ./projects/ores.compass/compass.sh show 47341fc6
    
  3. Heading-level anchors resolve too — sub-headings with their own :PROPERTIES: :ID: block (e.g. glossary entries, agile process phases, Cybernetic Levels systems) are indexed as anchors. The tool prints the parent doc and the section body:

    ./projects/ores.compass/compass.sh show fabb50e5   # Release entry in glossary
    ./projects/ores.compass/compass.sh show 7d72a9da   # Sprint closure phase
    

Output sections

For a file-level doc:

  • Title / Type / Path / Tags / Updated / Desc — header metadata.
  • Blurb — the paragraph between frontmatter and the first heading.
  • Outgoing links — every [[id:UUID]] reference in the body, resolved to uuid | type | title (path). Unresolved targets are flagged BROKEN. Anchors show as type anchor with their parent doc name.
  • Incoming links — every doc whose body links to this one, same shape.

For an anchor (heading-level :ID:):

  • Heading / In doc / Path / Parent — anchor identity.
  • Section — the heading body down to the next sibling-or-higher heading.
  • Incoming links — docs whose body links to this anchor.

Workflow

The two doc tools compose:

# 1. find — list candidates
./projects/ores.compass/compass.sh list --regex 'release'

# 2. focus — pick a UUID and inspect it
./projects/ores.compass/compass.sh show fabb50e5

Script

The wrapper is projects/ores.compass/compass.sh show. It calls projects/ores.compass/src/doc_show.py, which uses the shared doc_index.py library (file-level docs + heading anchors + inbound index, all built on a single walk of every .org file under the repo).

Tested by

Manual usage — read-only over the doc tree. Broken-link detection relies on every doc carrying a stable :ID:, audited by lifecycle / document types.

See also

Emacs 29.1 (Org mode 9.6.6)