obsidian-dev-utils/dist/lib/cjs/obsidian/Link.d.cts

This is the collection of useful functions that you can use for your Obsidian plugin development

/**
 * @packageDocumentation
 *
 * This module provides utilities for handling and updating links within Obsidian vaults. It includes
 * functions to split paths, update links in files, and generate markdown links with various options.
 * The functions integrate with Obsidian's API to ensure that links are managed correctly within the vault.
 */
import type { App, CachedMetadata, Reference, TFile } from 'obsidian';
import type { Promisable } from 'type-fest';
import type { MaybeReturn } from '../Type.cjs';
import type { PathOrFile } from './FileSystem.cjs';
import type { ProcessOptions } from './Vault.cjs';
/**
 * Options for converting a link.
 */
export interface ConvertLinkOptions {
    /**
     * The Obsidian app instance.
     */
    app: App;
    /**
     * The reference for the link.
     */
    link: Reference;
    /**
     * The source file containing the link.
     */
    newSourcePathOrFile: PathOrFile;
    /**
     * The old path of the link.
     */
    oldSourcePathOrFile?: PathOrFile;
    /**
     * Whether to force markdown links.
     */
    shouldForceMarkdownLinks?: boolean;
    /**
     * Whether to update file name alias. Defaults to `true`.
     */
    shouldUpdateFileNameAlias?: boolean;
}
/**
 * Wrapper for default options for generating markdown links.
 */
export interface GenerateMarkdownLinkDefaultOptionsWrapper {
    /**
     * The default options for generating markdown links.
     */
    defaultOptionsFn: () => Partial<GenerateMarkdownLinkOptions>;
}
/**
 * Options for generating a markdown link.
 */
export interface GenerateMarkdownLinkOptions {
    /**
     * The alias for the link.
     */
    alias?: string;
    /**
     * The Obsidian app instance.
     */
    app: App;
    /**
     * Indicates if the link should be embedded. If not provided, it will be inferred based on the file type.
     */
    isEmbed?: boolean;
    /**
     * Whether to allow an empty alias for embeds. Defaults to `true`.
     */
    isEmptyEmbedAliasAllowed?: boolean;
    /**
     * Whether to allow non-existing files. If `false` and `pathOrFile` is a non-existing file, an error will be thrown. Defaults to `false`.
     */
    isNonExistingFileAllowed?: boolean;
    /**
     * Indicates if the link should be a wikilink. If not provided, it will be inferred based on the Obsidian settings.
     */
    isWikilink?: boolean;
    /**
     * The original link text. If provided, it will be used to infer the values of `isEmbed`, `isWikilink`, `useLeadingDot`, and `useAngleBrackets`.
     * These inferred values will be overridden by corresponding settings if specified.
     */
    originalLink?: string;
    /**
     * Indicates if the link should be relative. If not provided or `false`, it will be inferred based on the Obsidian settings.
     */
    shouldForceRelativePath?: boolean;
    /**
     * Whether to include the attachment extension in the embed alias. Has no effect if `allowEmptyEmbedAlias` is `true`. Defaults to `false`.
     */
    shouldIncludeAttachmentExtensionToEmbedAlias?: boolean;
    /**
     * Indicates if the link should use angle brackets. Defaults to `false`. Has no effect if `isWikilink` is `true`
     */
    shouldUseAngleBrackets?: boolean;
    /**
     * Indicates if the link should use a leading dot. Defaults to `false`. Has no effect if `isWikilink` is `true` or `isRelative` is `false`.
     */
    shouldUseLeadingDot?: boolean;
    /**
     * The source path of the link.
     */
    sourcePathOrFile: PathOrFile;
    /**
     * The subpath of the link.
     */
    subpath?: string;
    /**
     * The target path or file.
     */
    targetPathOrFile: PathOrFile;
}
/**
 * The result of parsing a link.
 */
export interface ParseLinkResult {
    /**
     * The alias of the link.
     */
    alias?: string;
    /**
     * The encoded URL of the link.
     */
    encodedUrl?: string;
    /**
     * The end offset of the link in the original text.
     */
    endOffset: number;
    /**
     * Indicates if the link has angle brackets.
     */
    hasAngleBrackets?: boolean;
    /**
     * Indicates if the link is an embed link.
     */
    isEmbed: boolean;
    /**
     * Indicates if the link is external.
     */
    isExternal: boolean;
    /**
     * Indicates if the link is a wikilink.
     */
    isWikilink: boolean;
    /**
     * The raw link text.
     */
    raw: string;
    /**
     * The start offset of the link in the original text.
     */
    startOffset: number;
    /**
     * The title of the link.
     */
    title?: string;
    /**
     * The URL of the link.
     */
    url: string;
}
/**
 * Options for determining if the alias of a link should be reset.
 */
export interface ShouldResetAliasOptions {
    /**
     * The Obsidian app instance.
     */
    app: App;
    /**
     * The display text of the link.
     */
    displayText: string | undefined;
    /**
     * Indicates if the link is a wikilink.
     */
    isWikilink?: boolean;
    /**
     * The source path of the link.
     */
    newSourcePathOrFile: PathOrFile;
    /**
     * The old source file containing the link.
     */
    oldSourcePathOrFile?: PathOrFile;
    /**
     * The old target path of the link.
     */
    oldTargetPath: PathOrFile;
    /**
     * The target path or file.
     */
    targetPathOrFile: PathOrFile;
}
/**
 * Splits a link into its link path and subpath.
 */
export interface SplitSubpathResult {
    /**
     * The link path.
     */
    linkPath: string;
    /**
     * The subpath.
     */
    subpath: string;
}
/**
 * Options for updating a link.
 */
export interface UpdateLinkOptions {
    /**
     * The Obsidian app instance.
     */
    app: App;
    /**
     * The reference for the link.
     */
    link: Reference;
    /**
     * The source file containing the link.
     */
    newSourcePathOrFile: PathOrFile;
    /**
     * The file associated with the link.
     */
    newTargetPathOrFile: PathOrFile;
    /**
     * The old source file containing the link.
     */
    oldSourcePathOrFile?: PathOrFile;
    /**
     * The old path of the file.
     */
    oldTargetPathOrFile?: PathOrFile;
    /**
     * Whether to force markdown links.
     */
    shouldForceMarkdownLinks?: boolean;
    /**
     * Whether to update file name alias. Defaults to `true`.
     */
    shouldUpdateFileNameAlias?: boolean;
}
/**
 * Options for updating links in a file.
 */
export interface UpdateLinksInFileOptions extends ProcessOptions {
    /**
     * The obsidian app instance.
     */
    app: App;
    /**
     * The file to update the links in.
     */
    newSourcePathOrFile: PathOrFile;
    /**
     * The old path of the file.
     */
    oldSourcePathOrFile?: PathOrFile;
    /**
     * Whether to force the links to be in Markdown format.
     */
    shouldForceMarkdownLinks?: boolean;
    /**
     * Whether to update only embedded links.
     */
    shouldUpdateEmbedOnlyLinks?: boolean;
    /**
     * Whether to update file name alias. Defaults to `true`.
     */
    shouldUpdateFileNameAlias?: boolean;
}
/**
 * The options for updating the links in a content string.
 */
interface UpdateLinksInContentOptions {
    /**
     * The Obsidian application instance.
     */
    app: App;
    /**
     * The content to update the links in.
     */
    content: string;
    /**
     * The new source path or file.
     */
    newSourcePathOrFile: PathOrFile;
    /**
     * The old source path or file.
     */
    oldSourcePathOrFile?: PathOrFile;
    /**
     * Whether to force markdown links.
     */
    shouldForceMarkdownLinks?: boolean;
    /**
     * Whether to update only embedded links.
     */
    shouldUpdateEmbedOnlyLinks?: boolean;
    /**
     * Whether to update file name alias.
     */
    shouldUpdateFileNameAlias?: boolean;
}
/**
 * Converts a link to a new path.
 *
 * @param options - The options for converting the link.
 * @returns The converted link.
 */
export declare function convertLink(options: ConvertLinkOptions): string;
/**
 * Edits the backlinks for a file or path.
 *
 * @param app - The Obsidian application instance.
 * @param pathOrFile - The path or file to edit the backlinks for.
 * @param linkConverter - The function that converts each link.
 * @param processOptions - Optional options for retrying the operation.
 * @returns A {@link Promise} that resolves when the backlinks have been edited.
 */
export declare function editBacklinks(app: App, pathOrFile: PathOrFile, linkConverter: (link: Reference) => Promisable<MaybeReturn<string>>, processOptions?: ProcessOptions): Promise<void>;
/**
 * Edits the backlinks for a file or path.
 *
 * @param app - The Obsidian application instance.
 * @param pathOrFile - The path or file to edit the backlinks for.
 * @param linkConverter - The function that converts each link.
 * @param processOptions - Optional options for retrying the operation.
 * @returns A {@link Promise} that resolves when the backlinks have been edited.
 */
export declare function editLinks(app: App, pathOrFile: PathOrFile, linkConverter: (link: Reference) => Promisable<MaybeReturn<string>>, processOptions?: ProcessOptions): Promise<void>;
/**
 * Edits the links in a content string.
 *
 * @param app - The Obsidian application instance.
 * @param content - The content to edit the links in.
 * @param linkConverter - The function that converts each link.
 * @returns The promise that resolves to the updated content.
 */
export declare function editLinksInContent(app: App, content: string, linkConverter: (link: Reference) => Promisable<MaybeReturn<string>>): Promise<string>;
/**
 * Encodes a URL.
 *
 * @param url - The URL to encode.
 * @returns The encoded URL.
 */
export declare function encodeUrl(url: string): string;
/**
 * Extracts the file associated with a link.
 *
 * @param app - The Obsidian application instance.
 * @param link - The reference cache for the link.
 * @param sourcePathOrFile - The source path or file.
 * @param shouldAllowNonExistingFile - Whether to allow non-existing files. Defaults to `false`.
 * @returns The file associated with the link, or null if not found.
 */
export declare function extractLinkFile(app: App, link: Reference, sourcePathOrFile: PathOrFile, shouldAllowNonExistingFile?: boolean): null | TFile;
/**
 * Fixes the frontmatter markdown links in the provided metadata cache.
 *
 * @param cache - The metadata cache to fix the frontmatter markdown links in.
 * @returns Whether the frontmatter markdown links were fixed.
 */
export declare function fixFrontmatterMarkdownLinks(cache: CachedMetadata): boolean;
/**
 * Generates a markdown link based on the provided parameters.
 *
 * @param options - The options for generating the markdown link.
 * @returns The generated markdown link.
 */
export declare function generateMarkdownLink(options: GenerateMarkdownLinkOptions): string;
/**
 * Parses a link into its components.
 *
 * @param str - The link to parse.
 * @returns The parsed link.
 */
export declare function parseLink(str: string): null | ParseLinkResult;
/**
 * Parses all links in a string.
 *
 * @param str - The string to parse the links in.
 * @returns The parsed links.
 */
export declare function parseLinks(str: string): ParseLinkResult[];
/**
 * Determines if the alias of a link should be reset.
 *
 * @param options - The options for determining if the alias should be reset.
 * @returns Whether the alias should be reset.
 */
export declare function shouldResetAlias(options: ShouldResetAliasOptions): boolean;
/**
 * Splits a link into its link path and subpath.
 *
 * @param link - The link to split.
 * @returns An object containing the link path and subpath.
 */
export declare function splitSubpath(link: string): SplitSubpathResult;
/**
 * Tests whether a link uses angle brackets, possibly embed:
 * `[title](<link>)`, `![title](<link>)`.
 *
 * @param link - Link to test
 * @returns Whether the link uses angle brackets
 */
export declare function testAngleBrackets(link: string): boolean;
/**
 * Tests whether a link is an embed link:
 * `![[link]]`, `![title](link)`.
 *
 * @param link - Link to test
 * @returns Whether the link is an embed link
 */
export declare function testEmbed(link: string): boolean;
/**
 * Tests whether a link has a leading dot, possibly embed:
 * `[[./link]]`, `[title](./link)`, `[title](<./link>)`,
 * `![[./link]]`, `![title](./link)`, `![title](<./link>)`.
 *
 * @param link - Link to test
 * @returns Whether the link has a leading dot
 */
export declare function testLeadingDot(link: string): boolean;
/**
 * Tests whether a link is a wikilink, possibly embed:
 * `[[link]]`, `![[link]]`.
 *
 * @param link - Link to test
 * @returns Whether the link is a wikilink
 */
export declare function testWikilink(link: string): boolean;
/**
 * Updates a link based on the provided parameters.
 *
 * @param options - The options for updating the link.
 * @returns The updated link.
 */
export declare function updateLink(options: UpdateLinkOptions): string;
/**
 * Updates the links in a content string based on the provided parameters.
 *
 * @param options - The options for updating the links.
 * @returns A {@link Promise} that resolves to the content with updated links.
 */
export declare function updateLinksInContent(options: UpdateLinksInContentOptions): Promise<string>;
/**
 * Updates the links in a file based on the provided parameters.
 *
 * @param options - The options for updating the links.
 * @returns A {@link Promise} that resolves when the links are updated.
 */
export declare function updateLinksInFile(options: UpdateLinksInFileOptions): Promise<void>;
export {};