Module link 

Link text — the raw strings a relation field holds, the wikilinks embedded in body prose, and the path arithmetic around them.

A link target as written in metadata is either a bare path or a markdown-style labeled link ([Design](docs/design.md)), and its path may be relative to the document (notes/a.md), workspace-absolute from the root (/Blog/Blog.md), or wrapped in Markdown angle brackets when it contains spaces (</Creative Writing/index.md>, [Notes](</My Notes/x.md>)). This is prov’s link-syntax layer — the analogue of fig’s format layer: it recognizes the conventions a real workspace mixes and round-trips them on write (spaces re-acquire their brackets). A Wikilink is the body-text counterpart ([[notes/a.md]], [[colophon:ajp7eq|My file]]). Everything here is lexical: no filesystem access, no symlink resolution, and no markdown-structure awareness (a [[…]] inside a code span is still scanned) — resolution and code-fence discipline belong to the traversal and validation layers, which can report what they find.

Structs

BodyLink

One link found in body prose: the parsed Link (target, label, and whether it was an Obsidian [[…]] wikilink or a markdown/djot [label](target) link) together with the byte span of the whole construct — exactly what a rewrite replaces. The unifying body-link currency: census, check, and the rename machinery all consume this, blind to which syntax the link was written in.

Link

A parsed link string: an optional human label and the target it points at.

ReferenceStyle

How a durable reference is spelled: a Wrapper, an Addressing, whether an id link carries a title label, and the path rendering used when addressing by path. This is the per-workspace default and the per-relation override (see crate::relation::Relation::style).

Wikilink

A wikilink embedded in a document’s body: [[target]] or, with an Obsidian pipe label, [[target|label]].

Enums

Addressing

What a reference addresses its target by — the second style axis.

IdRef

What an id:-scheme target names.

LinkStyle

The write style for links a workspace authors — prov’s analogue of diaryx’s LinkFormat, and read from the same place: the link_format key in the root document’s frontmatter (a fact declared in the workspace, not an app-private config). Every link prov writes (autofix today; create/rename in time) uses this, so a repair never introduces a foreign style.

Notation

The syntactic form a reference is written in — the config-facing notation axis (references.notation), orthogonal to PathStyle. This is the clean split of what the internal Wrapper + plain_/markdown_ LinkStyle prefix fused: Bare is a path with no brackets, Markdown is [Title](…), Wikilink is [[…]].

PathStyle

The path-resolution a reference uses for a path target — the config-facing references.path_style axis, orthogonal to Notation. Applies to path targets only (id/alias ignore it).

Wrapper

The syntactic wrapper a reference is written in — the first of the two style axes (see docs/reference-styles.md).

Constants

ID_SCHEME

The target scheme marking a link-by-ID: id:<id>.

LEGACY_ID_SCHEME

The legacy scheme (colophon:<id>), still recognized on read so existing workspaces keep resolving. New links are authored with ID_SCHEME.

LOCATOR_SEPARATOR

The character that begins a sub-document locator on a link target.

WORKSPACE_SEPARATOR

The character separating the workspace qualifier from the id in a cross-workspace reference (id:<workspace>/<id>).

Functions

escapes_root

Whether path, resolved against a workspace root, would land outside it.

exclude_code_spans

Keep only the wikilinks in links whose span does not overlap any of code_spans — the code-awareness DESIGN §8 asks for: a [[…]] that is really code (inside a fenced/inline code span) must never be treated as a link.

foreign_id_target

Render a cross-workspace reference as a link target (id:<workspace>/<id>).

format_link

Format a link to target (a workspace-relative canonical path) as written in the document at from, in style, with title (used only by the Markdown styles). This is what keeps an authored link native to the workspace.

format_reference

Render a durable reference from the document at from to to (titled title) in style. id must be Some when the style addresses by id (the caller registers the target first); it is ignored otherwise. Returns the exact scalar to store in metadata (a wikilink scalar keeps its [[…]] — the metadata writer is responsible for any format-level quoting).

id_target

Render an ID as a link target (id:<id>).

is_valid_workspace_id

Whether name is a usable workspace self-name.

join_locator

Re-attach a locator to a document target — the inverse of split_locator. None returns the target unchanged, so this is safe on a target that never had one.

normalize

Lexically normalize a relative path: drop . components and fold parent/.. pairs. Leading .. components (escaping the workspace root) are kept — the caller decides whether that is an error.

parse_wikilinks

Scan body prose for every [[…]] wikilink, in source order, each carrying its byte span. Purely lexical: unclosed [[ is ignored, the first following ]] closes the span, and no markdown structure (code spans, escapes) is interpreted — a higher layer decides whether a match in a code fence counts.

parsed_link_spans

The spans of markdown/djot inline links in body, via twig — empty when path’s extension names no grammar twig understands or the parse fails (the same degrade-to-lexical rule as code_spans_for).

path_text

The bare path text a path reference points at, in the shape path_style selects: workspace-absolute (/canonical), relative, or canonical.

path_to_title

A human title generated from a path’s file stem: _/- become spaces and each word is capitalized (utility_index.md → Utility Index). The fallback when a target document declares no title.

relative

The relative path string that reaches to from from_dir (both normalized, same coordinate system). Rendered with forward slashes — link targets are text, not platform paths.

resolve

Resolve a link target written in doc to a normalized path in the same coordinate system as doc (workspace-relative when doc is). A target with a leading / is workspace-absolute — resolved from the root, not doc’s directory, and never against the filesystem root; any other target is relative to doc’s directory.

scan_body_links

Scan body for every link a move or a check must account for — Obsidian [[…]] wikilinks and markdown/djot [label](target) links — each as a BodyLink in source order. This is the single body-scan seam census/check/rename use; it supersedes the wikilink-only scan_wikilinks for callers that must also see markdown/djot links.

scan_wikilinks

Scan body for wikilinks the way census/check/the rename machinery actually should — never parse_wikilinks directly. When path’s extension names a format twig understands, every code span (fenced/inline code, raw escapes) is treated as opaque before the lexical [[…]] scan ever sees it: each prose run between code spans is scanned on its own and the results stitched back into body-relative spans. For an unrecognized extension — or if the parse fails — this is exactly parse_wikilinks over the whole body, the same behavior as before code-awareness existed.

slug

Turn a human title into a filesystem-friendly filename stem — the readable slug prov derives when a document is created by title (prov new "My Great Note" → my-great-note). The rough inverse of path_to_title: lowercase, runs of whitespace and separators (space / - / _ / /) collapsed to a single -, and any other punctuation dropped. Unicode letters and digits are kept, so a non-ASCII title still yields a legible name. A title with no slug-able characters (pure punctuation) falls back to "untitled" so the result is always a valid stem.

split_locator

Split a target into the part naming a document and its locator.

strip_id_scheme

Strip the ID scheme from a target, accepting the current id: spelling or the legacy colophon: one. None when the target names no ID.