Documentation
¶
Overview ¶
Package resolve implements Obsidian-style link resolution for kb vaults and the link extraction shared by lint, refs and link: a target resolves by topic-relative path, topic-slug-prefixed path, vault-relative path, or file stem, case-insensitively. Titles and frontmatter aliases never resolve a link; aliases are display text only (`[[target|alias]]`).
Index ¶
- Constants
- func Aliases(values map[string]any) []string
- func DiscoverTopicRoots(vaultPath, topicPath string) ([]string, error)
- func FrontmatterLinks(values map[string]any) map[string][]string
- func InRanges(ranges []Range, start, end int) bool
- func LoadVaultIndex(vaultPath, topicPath string) (*Index, []File, error)
- func Normalize(target string) string
- func QuarantineOriginal(filePath string) (string, bool)
- func QuarantinePath(topicRel string) (string, bool)
- type File
- type Index
- type Link
- type Range
Constants ¶
const ( KindWikilink = "wikilink" KindMarkdown = "markdown" )
Link kinds reported by BodyLinks.
const DecisionsDir = ".decisions"
DecisionsDir is the per-topic directory of decision bookkeeping; it holds no vault documents and is never indexed.
const QuarantineDir = "raw/_quarantine"
QuarantineDir is the topic-relative directory that holds quarantined sources: `raw/articles/x.md` is quarantined to `raw/_quarantine/articles/x.md`.
Variables ¶
This section is empty.
Functions ¶
func Aliases ¶
Aliases reads the Obsidian `aliases` property: a list of strings or a single string. Empty entries are dropped.
func DiscoverTopicRoots ¶
DiscoverTopicRoots returns topicPath plus every sibling directory of vaultPath that carries a topic marker (`CLAUDE.md`), sorted.
func FrontmatterLinks ¶
FrontmatterLinks returns, per frontmatter key, the normalized wikilink targets found in string values or string list values (for example `sources`, `related`, `concepts`, `affects`, `supersedes`, `informed_by`). Keys without links are omitted; nested maps are ignored.
func LoadVaultIndex ¶
LoadVaultIndex walks the topic at topicPath and its sibling topics under vaultPath (see DiscoverTopicRoots), reads each markdown file's frontmatter title and aliases, and returns the index plus the files in preference order. `.decisions/` directories and the topic-root `AGENTS.md` are skipped; unparsable frontmatter leaves Title and Aliases empty.
func Normalize ¶
Normalize reduces a link target to its path part: it strips `[[`/`]]` (and a leading `!` embed marker), `|display`, `#heading`, surrounding spaces, backslashes (to `/`), a leading `./`, surrounding slashes and a trailing `.md`. The result keeps its case.
func QuarantineOriginal ¶
QuarantineOriginal maps a quarantined path (topic-relative `raw/_quarantine/<rest>` or vault-relative `<slug>/raw/_quarantine/<rest>`) to the path it had before quarantine (`raw/<rest>` or `<slug>/raw/<rest>`).
func QuarantinePath ¶
QuarantinePath maps a topic-relative `raw/<rest>` path to its quarantine location `raw/_quarantine/<rest>`.
Types ¶
type File ¶
type File struct {
// Path is the vault-relative slash path including the `.md` extension.
Path string
// TopicRel is the topic-relative path when the file is in the active
// topic, else "".
TopicRel string
// InTopic reports whether the file belongs to the active topic.
InTopic bool
// Quarantined reports whether the file lives under raw/_quarantine/.
Quarantined bool
// Title is the frontmatter title, when present.
Title string
// Aliases are the frontmatter aliases (display text only).
Aliases []string
}
File is one markdown document known to the index.
type Index ¶
type Index struct {
// contains filtered or unexported fields
}
Index resolves link targets against a set of vault files.
func NewIndex ¶
NewIndex builds an index over files for the topic named topicSlug. Quarantined files are detected from their paths (in addition to the Quarantined flag) and indexed under both their quarantine path and their original path, so a link to the original path resolves to the quarantined file. When several files match one key, non-quarantined files win, then files in the topic, then the lexicographically first path.
func (*Index) ResolveFrom ¶
ResolveFrom resolves target as written in the document at fromPath (vault-relative). Targets starting with `./` or `../` are joined with the directory of fromPath and matched as vault-relative paths; every other target resolves like Resolve.
func (*Index) ResolveWhere ¶
ResolveWhere resolves target like Obsidian and returns the first matching file accepted by accept (nil accepts all). The target is normalized with Normalize and matched case-insensitively, in order, as a topic-relative path, a topic-slug-prefixed path, a vault-relative path and a file stem.
type Link ¶
type Link struct {
// Target is the normalized link target (see Normalize); markdown link
// destinations are URL-unescaped first.
Target string
// Display is the display text: the `|alias` part of a wikilink or the
// label of a markdown link; "" when absent.
Display string
// Heading is the `#heading` (or `#^block`) part without the `#`, if any.
Heading string
Start int
End int
// Kind is KindWikilink or KindMarkdown.
Kind string
// Embed reports an embed (`![[x]]` or ``).
Embed bool
}
Link is one link found in a markdown body. Start and End are byte offsets of the whole link markup in the scanned text, so editors can replace text[Start:End].
func BodyLinks ¶
BodyLinks extracts wikilinks and internal markdown links from body in document order, skipping fenced code blocks and inline code. Markdown links are kept only when the destination has no URL scheme and either ends in `.md` or has no extension. A `[[label]](url)` construct is a markdown link whose label happens to be bracketed, not a wikilink.
Source Files