Advanced URI

Advanced URI is an Obsidian plugin that enables automation of Obsidian workflows by controlling features via URI schemes. Instead of manual mouse clicks or keyboard inputs, you can trigger actions using text-based URIs.

Key capabilities include:

• Navigation: Opening files, opening workspaces, and navigating to specific headings or blocks.
• Writing: Editing existing files and creating new files.
• Search & Replace: Performing automated search and replace operations within a file.
• Canvas: Controlling movement within Obsidian Canvas.

To read or target specific metadata in a file's YAML frontmatter, use the frontmatterkey parameter. The parameter accepts an ordered list of keys separated by commas, enclosed in square brackets [].

Key Selection Patterns

• Simple Structure: For a top-level key like my_item: my_value, use frontmatterkey=my_item.
• Complex/Nested Structure: For nested keys like my_item: { second_item: my_value }, use frontmatterkey=[my_item,second_item].
• List Access: To access an item in a list by its index, use the index as the last element in the key list. For example, to access the second item (index 1) in a list, use frontmatterkey=[my_item,second_item,1].

# Example: Accessing a nested list item
obsidian://adv-uri?vault=<vault>&filepath=MyFile&frontmatterkey=[my_item,second_item,1]

Each command URI supports a confirm parameter. When this parameter is truthy (not empty and not false), the plugin will automatically find the first main button in any resulting modal and click it.

This is useful for automating actions that trigger dialogs, such as automatically pressing the "Export to pdf" button in the PDF export modal.

When using append or prepend modes, you can target specific locations within a file using the following parameters:

• heading: Target a specific heading.
• block: Target a specific block. Note that data is inserted literally before or after the resolved block range. Lists are not handled specially; to create a new list item, include the list marker in your data (e.g., data=-%20new%20item).
• line: Target a specific line.

For detailed logic on how these targets are resolved, refer to the Navigation documentation.

When executing commands via Advanced URI, you can identify them in two ways:

1. commandname: The human-readable name seen in the Obsidian command palette.
2. commandid: The internal identifier used in the plugin's source code.

Recommendation: Use the commandid whenever possible because it is stable and less likely to change than the display name. You can use Helper Commands to automatically obtain the correct ID.

When using an Advanced URI action to open or focus a pane, you can specify how the file should be displayed using the viewmode parameter. This allows you to control whether the user sees the raw markdown, the live preview, or the rendered reading mode.

Accepted values for viewmode:

• source: Sets the editor to editing:source mode.
• live: Sets the editor to editing:live preview mode.
• preview: Sets the editor to reading mode.

Actions are constructed by combining different parameters within a URI. When multiple parameters are provided, they define a specific operation. For example, providing both a file path and content triggers a write operation to that file.

When defining an action, you must replace the <identification> placeholder with a valid file identifier (such as a file path, alias, or filename) as defined in the project's File Identifiers documentation.

Advanced URIs follow standard URL query parameter syntax. All URIs must start with the protocol obsidian://adv-uri.

To pass values, use a query string starting with ? containing key=value pairs. Multiple pairs are separated by the & character.

Important: Ensure all values are properly URL-encoded to prevent parsing errors.

Note: For versions prior to 1.44.0, the protocol was obsidian://advanced-uri and required double encoding; in the current version, use obsidian://adv-uri and single encoding.

obsidian://adv-uri?key1=value1&key2=value2

Advanced URIs can be launched using several methods:

• Web Browser: Paste the URI directly into the browser's address bar. The browser will prompt you to confirm the execution.
• Markdown Link in Obsidian: Because obsidian:// is a custom protocol, Obsidian may not recognize it as a direct link. To ensure it works, wrap the URI in standard Markdown link syntax.

[This here is shown](obsidian://adv-uri?filepath=Home%20Index%2Ftoday)

You can install the plugin via the Obsidian Community Plugins interface or manually via GitHub releases.

Via Obsidian Community Plugins

1. Open Settings -> Community plugins.
2. Disable Restricted mode.
3. Search for and install Advanced URI.
4. Enable the plugin.

Via GitHub (Manual Installation)

1. Download the latest release.
2. Move manifest.json and main.js to <vault>/.obsidian/plugins/obsidian-advanced-uri.
3. Reload Obsidian.
4. Open Settings -> Community plugins and disable Restricted mode.
5. Enable Advanced URI.