EditReferencesParams
Parameters for editReferences.
Import:
import type { EditReferencesParams } from '@mnaoumov/obsidian-lib/link';Signature:
export interface EditReferencesParams extends EditReferencesOptionsExtends: EditReferencesOptions
Properties
| Property | Type | Description |
|---|---|---|
| app | App | The Obsidian application instance. |
| offsetRange? | OffsetRange | A range within the file's content, in character offsets, restricting the pass to the links inside it. When omitted, every link is visited. A link is edited only when it is **fully contained** in the range; one that merely overlaps it is left alone, because rewriting part of a link corrupts it. Both bounds are inclusive, so a range whose offsets coincide exactly with a link's does include that link. A reference that carries no position within the file's content — a frontmatter link, a multi-link frontmatter value entry, or any canvas reference — is never in range and is skipped whenever a range is supplied. The offsets are into the content this function reads from the vault. Before reading, it saves any unsaved editor buffer for the file, so a range taken from an open editor via Editor.posToOffset is valid. The caller owns only the case where the buffer changes between computing the range and this call. |
| pathOrFile | PathOrFile | The path or file to edit the links for. |
| referenceConverter | (reference: Reference) => Promisable<MaybeReturn<null | string>> | The function that converts each reference: it returns the new link text, or null (or nothing) to leave the link unchanged. |
| referenceDefinitionConverter? | (definition: ReferenceLinkCache) => Promisable<MaybeReturn<null | string>> | The function that returns the new destination of each reference-style link definition ([id]: destination "title"). Obsidian reports those in CachedMetadata.referenceLinks, not among the references EditReferencesParams.referenceConverter receives, so without this function they are never edited.It returns the destination unescaped, in the form of ReferenceLinkCache.link, or undefined to leave the definition unchanged. Only the destination is rewritten: the id, the title, the angle brackets and every use of the definition ([text][id], [id]) stay as written. A definition whose content no longer matches its metadata is left unchanged. See referenceDefinitionToFileChange. A canvas file has no definitions.The offset range applies to the definition's whole position. The heading skip and EditReferencesParams.shouldSkipReference do not apply, since a definition is never in a heading and is not a Reference. |
| shouldEditExternalLinks? | boolean | Whether to also edit external links parsed from the note body. When true, the converter also receives references for external links. |
| shouldEditFrontmatterExternalLinks? | boolean | Whether to also edit external links parsed from frontmatter values. When true, the converter also receives references for frontmatter external links. |
| shouldEditMultiValueFrontmatterExternalLinks? | boolean | Whether to also edit external links parsed from multi-link (multi-value) frontmatter values. When true, the converter also receives references for each external link within a multi-link frontmatter value (each located by its offsets, so only that link is spliced back in place). |
| shouldSkipReference? | ((reference: Reference) => boolean) | null | A predicate choosing links to leave unchanged: for each reference it returns true for, the converter is not called, so the link stays byte-for-byte as written — its path, style, angle brackets and leading dot included. Use it to exclude links the caller decides on, for example by their resolved target path.Applied after the heading skip and the offset range. null behaves like an absent key, so a predicate factory that returns null when nothing is excluded can be passed straight through. |
| shouldSkipReferencesInHeadings? | boolean | Whether to leave every link inside a heading unchanged: the converter is not called for it, so it stays byte-for-byte as written. A link in a heading is part of the heading's text, so rewriting it changes that text and breaks every #heading subpath pointing at the heading. See isReferenceInHeading. |
Links to this page: