Advanced URI

https://publish.obsidian.md/advanced-uri-doc/
Admin
Advanced URI is an Obsidian plugin that allows you to control various Obsidian features through...
Tokens:5,612
Snippets:46
Trust Score:10
Update:11 months ago
Show doc for...
Tokens:
Raw
### Advanced URI - Write Frontmatter Example (Simple)

Source: https://publish.obsidian.md/advanced-uri-doc/Actions/Frontmatter

Illustrates how to use the Advanced URI to write a new value to a frontmatter field. If the specified key does not exist, it will be created. This example shows updating a list item.

```url
obsidian://adv-uri?vault=<vault>&filepath=MyFile&frontmatterkey=[my_item,second_item,1]&data=NewValue
```

--------------------------------

### Advanced URI - Read Frontmatter Example

Source: https://publish.obsidian.md/advanced-uri-doc/Actions/Frontmatter

Shows how to construct an Advanced URI to read a specific value from a file's frontmatter. It utilizes the `vault`, `filepath`, and `frontmatterkey` parameters to locate and retrieve the data.

```url
obsidian://adv-uri?vault=<vault>&filepath=MyFile&frontmatterkey=[my_item,second_item,1]
```

--------------------------------

### YAML Frontmatter Structure Example

Source: https://publish.obsidian.md/advanced-uri-doc/Actions/Frontmatter

Demonstrates the standard YAML frontmatter format used in Markdown files, enclosed by triple hyphens (`---`). This metadata is typically used for file properties like title and tags.

```yaml
---
title: My Title
tags: [tag1, tag2]
---
```

--------------------------------

### Open Bookmark via URI (Obsidian Advanced URI)

Source: https://publish.obsidian.md/advanced-uri-doc/Actions/Bookmarks

This example demonstrates how to construct a URI to open a specific bookmark within Obsidian using the Advanced URI plugin. It requires the vault name, bookmark title, and optionally an open mode.

```plaintext
obsidian://adv-uri?vault=<your-vault>&bookmark=<your-bookmark-title>&openmode=tab
```

--------------------------------

### URI Encoding Example for Obsidian Advanced URI

Source: https://publish.obsidian.md/advanced-uri-doc/Concepts/Encoding

Demonstrates how to encode a key-value pair for use in an Obsidian Advanced URI. Special characters in the value are converted to their percent-encoded equivalents to ensure the URI is correctly parsed. This is crucial for passing complex data through URIs.

```url
obsidian://adv-uri?myKey=Hello%20World
```

--------------------------------

### Execute Obsidian Command by ID

Source: https://publish.obsidian.md/advanced-uri-doc/Actions/Commands

This example demonstrates how to close a specific tab in Obsidian by providing its filepath and the command ID. The URI first navigates to the specified file and then executes the 'Close current tab' command.

```uri
obsidian://adv-uri?vault=<your-vault>&filepath=<your-file>&commandid=workspace%3Aclose
```

--------------------------------

### Advanced URI - Write Frontmatter Example (Complex)

Source: https://publish.obsidian.md/advanced-uri-doc/Actions/Frontmatter

Demonstrates writing complex data structures, such as nested JSON objects or arrays, to a file's frontmatter using the Advanced URI. The `data` parameter requires URL encoding for special characters and structures.

```url
obsidian://adv-uri?vault=<vault>&filepath=MyFile&frontmatterkey=[my_item,second_item,1]&data=%7B%22data%22%3A%5B2,3%5D%7D
```

--------------------------------

### Writing to Files

Source: https://publish.obsidian.md/advanced-uri-doc/Actions/Writing

This section details the different actions available for writing content to files using the Advanced URI plugin. It covers writing new content, overwriting existing content, appending, and prepending.

```APIDOC
## Writing Actions

### Description
These actions allow you to write, overwrite, append, or prepend data to files within your Obsidian vault using the Advanced URI.

### Actions Available
- **write**: Writes `data` to the file if the file does not already exist.
- **overwrite**: Writes `data` to the `filepath`, overwriting existing content if the file exists.
- **append**: Appends `data` to the end of the file.
- **prepend**: Prepends `data` to the beginning of the file.
- **new**: Creates a new file with the specified `filepath` and `data`. If the `filepath` exists, an incrementing number is appended to the filename.

### Parameters
#### Common Parameters
- **vault** (string) - Required - The name of the vault to target.
- **filepath** (string) - Required for `write`, `overwrite`, `new` - The path to the file (without extension).
- **data** (string) - Required for most actions - The content to write to the file. Ensure values are properly URL-encoded.
- **mode** (string) - Optional - Specifies the writing mode: `overwrite`, `append`, `prepend`, `new`.
- **daily** (boolean) - Optional - If `true`, targets today's daily note instead of a specific `filepath`.
- **clipboard** (boolean) - Optional - If `true`, uses the content from the clipboard as `data` instead of providing it directly. Cannot be used with `data` parameter.
- **heading** (string) - Optional - Used with `append` or `prepend` to target a specific heading within the file.
- **line** (string) - Optional - Used with `append` or `prepend` to target a specific line number within the file.

### Request Examples

#### 1. Write 'Hello World' to 'my-file.md'
```
obsidian://adv-uri?vault=<your-vault>&filepath=my-file&data=Hello%20World
```

#### 2. Overwrite 'This text is overwritten' to 'my-file.md'
```
obsidian://adv-uri?vault=<your-vault>&filepath=my-file&data=This%20text%20is%20overwritten&mode=overwrite
```

#### 3. Append 'Hello World' to today's daily note
```
obsidian://adv-uri?vault=<your-vault>&daily=true&data=Hello%20World&mode=append
```

#### 4. Append content from the clipboard to today's daily note
```
obsidian://adv-uri?vault=<your-vault>&daily=true&clipboard=true&mode=append
```

#### 5. Prepend to a specific heading in a file
```
obsidian://adv-uri?vault=<your-vault>&filepath=my-file&data=Content%20to%20prepend&mode=prepend&heading=My%20Heading
```

### Response
- **Success Response (200 OK)**: Typically, a successful URI action does not return a specific JSON response but performs the action silently or relies on Obsidian's UI feedback.

- **Error Handling**: Errors may result in Obsidian showing an error notification. Specific error codes are not detailed in this documentation.
```

--------------------------------

### Prepend Data to File using Advanced URI

Source: https://publish.obsidian.md/advanced-uri-doc/Actions/Writing

Prepends data to the beginning of a specified file. Ensure data is properly URL-encoded. This action can also be used with daily notes.

```uri
obsidian://adv-uri?vault=<your-vault>&filepath=my-file&data=Data%20to%20prepend&mode=prepend
```

--------------------------------

### Basic Advanced URI Structure

Source: https://publish.obsidian.md/advanced-uri-doc/Concepts/Schema

Demonstrates the fundamental structure of an advanced Obsidian URI, utilizing key-value pairs for parameters.

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

--------------------------------

### Canvas Actions

Source: https://publish.obsidian.md/advanced-uri-doc/Actions/Canvas

This section details URI actions for interacting with Obsidian Canvas, such as focusing nodes and setting the viewport.

```APIDOC
## Canvas Actions

### Description
Actions to manipulate the Obsidian Canvas, including focusing specific nodes and adjusting the viewport.

### Method
GET

### Endpoint
`obsidian://adv-uri`

### Parameters
#### Query Parameters
- **vault** (string) - Required - The name of the vault to target.
- **canvasnodes** (string) - Optional - A comma-separated list of node IDs to focus on. If omitted, the currently opened canvas is used.
- **canvasviewport** (string) - Optional - Viewport details (x, y, zoom) separated by commas. Can include `++` or `--` for relative adjustments.

### Request Example

#### Focus nodes `abc` and `xyz` in the current vault:
```json
{
  "request": "obsidian://adv-uri?vault=<your-vault>&canvasnodes=abc%2Cxyz"
}
```

#### Set viewport to x=100, y=-300, zoom=0.5:
```json
{
  "request": "obsidian://adv-uri?vault=<your-vault>&canvasviewport=100%2C-300%2C0.5"
}
```

#### Only set y to -300, leaving other values untouched:
```json
{
  "request": "obsidian://adv-uri?vault=<your-vault>&canvasviewport=-%2C-300%2C-"
}
```

#### Increase x by 100, subtract y by 300, increase zoom by 0.5:
```json
{
  "request": "obsidian://adv-uri?vault=<your-vault>&canvasviewport=++100%2C--300%2C++0.5"
}
```

### Response

#### Success Response (200)
This action typically performs an immediate UI update and does not return a specific JSON response body. The success is indicated by the canvas updating as per the request.
```

--------------------------------

### Open Workspace URI

Source: https://publish.obsidian.md/advanced-uri-doc/Actions/Navigation

Constructs a URI to open a specific Obsidian workspace. Requires the vault name and the workspace name.

```uri
obsidian://adv-uri?vault=<your-vault>&workspace=main
```

--------------------------------

### Navigation Actions

Source: https://publish.obsidian.md/advanced-uri-doc/Actions/Navigation

These actions allow you to navigate and open specific content within Obsidian using the advanced URI.

```APIDOC
## Navigation Actions

### Description
These endpoints allow for various navigation actions within Obsidian, such as opening workspaces, files, specific lines, headings, or blocks.

### Method
GET

### Endpoint
`obsidian://adv-uri`

### Parameters
#### Query Parameters
- **vault** (string) - Required - The name of the vault to open.
- **workspace** (string) - Optional - Opens the specified workspace. Used with `load workspace` or `copy URI for current workspace`.
- **clipboard** (boolean) - Optional - If set to `true`, copies the URI for the current workspace to the clipboard. Used with `copy URI for current workspace`.
- **saveworkspace** (boolean) - Optional - If set to `true`, saves the current workspace. Can be combined with `workspace` to open a new workspace afterwards.
- **filepath** (string) - Optional - The path to the file to open.
- **line** (integer) - Optional - The line number (1-indexed) to navigate to within a file.
- **column** (integer) - Optional - The column number (1-indexed) to navigate to within a file.
- **offset** (integer) - Optional - The character offset from the start of the file to set the cursor at.
- **heading** (string) - Optional - The heading text to navigate to within a file.
- **block** (string) - Optional - The block ID to navigate to within a file, or to search for globally.
- **settingid** (string) - Optional - The ID of the settings tab to open.

### Request Example
```json
{
  "example": "obsidian://adv-uri?vault=<your-vault>&workspace=main"
}
```

### Response
#### Success Response (200)
Navigates to the specified location or performs the requested action.

#### Response Example
```json
{
  "example": "// No explicit JSON response, action is performed by Obsidian client."
}
```
```

--------------------------------

### Search Actions

Source: https://publish.obsidian.md/advanced-uri-doc/Actions/Search

This section covers the different ways to perform searches within files using the Advanced URI.

```APIDOC
## Search Actions

This section details the search and replace functionalities available through the Advanced URI.

### Per File Search

This endpoint allows searching for a specific query within a file.

### Method
GET

### Endpoint
`/`

### Parameters
#### Query Parameters
- **search** (string) - Required - The text to search for within the current file.
- **identification** (string) - Optional - The name of the file to search within. If not provided, the current file is used.

### Request Example
```json
{
  "example": "/search?search=myterm"
}
```

### Response
#### Success Response (200)
This action does not return a specific JSON response but performs the search operation.

### Per File Search and Replace

This endpoint allows replacing occurrences of a search term with a replacement term within a file. It supports both normal string replacement and regular expression replacement.

### Method
GET

### Endpoint
`/`

### Parameters
#### Query Parameters
- **search** (string) - Required - The text to search for and replace in the current file.
- **replace** (string) - Required - The text to replace the search term with.
- **searchregex** (string) - Required - The regular expression to search for and replace.
- **identification** (string) - Optional - The name of the file to perform the replace operation on. If not provided, the current file is used.

### Request Example (Normal Search and Replace)
```json
{
  "example": "/search?search=oldterm&replace=newterm"
}
```

### Request Example (RegEx Search and Replace)
```json
{
  "example": "/search?searchregex=/[a-z]+/&replace=word"
}
```

### Response
#### Success Response (200)
This action does not return a specific JSON response but performs the search and replace operation.
```

--------------------------------

### Create New File using Advanced URI

Source: https://publish.obsidian.md/advanced-uri-doc/Actions/Writing

Creates a new file with the specified data. If a file with the same name already exists, an incrementing number will be appended to the filename to ensure uniqueness.

```uri
obsidian://adv-uri?vault=<your-vault>&filepath=new-file.md&data=Content%20for%20new%20file&mode=new
```

--------------------------------

### Open Heading URI

Source: https://publish.obsidian.md/advanced-uri-doc/Actions/Navigation

Constructs a URI to open a specific heading within a file. Requires the vault name, file path, and the heading text.

```uri
obsidian://adv-uri?vault=<your-vault>&filepath=my-file&heading=Goal
```

--------------------------------

### Open Block URI

Source: https://publish.obsidian.md/advanced-uri-doc/Actions/Navigation

Constructs a URI to open a specific block within a file. Requires the vault name, file path, and the block ID.

```uri
obsidian://adv-uri?vault=<your-vault>&filepath=my-file&block=12345
```

--------------------------------

### Advanced URI with Specific Vault

Source: https://publish.obsidian.md/advanced-uri-doc/Concepts/Schema

Shows how to specify a particular vault for executing an advanced Obsidian URI by using the 'vault' parameter.

```uri
obsidian://adv-uri?vault=myVault&key1=value1
```

--------------------------------

### Write Data to File using Advanced URI

Source: https://publish.obsidian.md/advanced-uri-doc/Actions/Writing

Writes data to a specified file if the file does not already exist. Ensure data is properly URL-encoded.

```uri
obsidian://adv-uri?vault=<your-vault>&filepath=my-file&data=Hello%20World
```

--------------------------------

### Append Clipboard Content to Daily Note using Advanced URI

Source: https://publish.obsidian.md/advanced-uri-doc/Actions/Writing

Appends the content currently in the clipboard to the current day's daily note. This is useful for quickly adding external text.

```uri
obsidian://adv-uri?vault=<your-vault>&daily=true&clipboard=true&mode=append
```

--------------------------------

### Search Block URI

Source: https://publish.obsidian.md/advanced-uri-doc/Actions/Navigation

Constructs a URI to search the entire vault for a specific block ID. Requires the vault name and the block ID.

```uri
obsidian://adv-uri?vault=<your-vault>&block=12345
```

--------------------------------

### Append Data to Daily Note using Advanced URI

Source: https://publish.obsidian.md/advanced-uri-doc/Actions/Writing

Appends data to the current day's daily note. The data needs to be URL-encoded. This action supports appending to specific files as well.

```uri
obsidian://adv-uri?vault=<your-vault>&daily=true&data=Hello%20World&mode=append
```

--------------------------------

### Focus Canvas Nodes via URI

Source: https://publish.obsidian.md/advanced-uri-doc/Actions/Canvas

This action allows you to programmatically focus on specific nodes within an Obsidian canvas. You provide a comma-separated list of node identifiers. If no file identification is provided, the currently opened canvas is used.

```uri
obsidian://adv-uri?vault=<your-vault>&canvasnodes=abc%2Cxyz
```

--------------------------------

### Set Canvas Viewport via URI

Source: https://publish.obsidian.md/advanced-uri-doc/Actions/Canvas

This action sets the absolute x, y, and zoom level of the canvas view. You can specify values for each parameter, separated by commas. A hyphen '-' can be used to leave a parameter unchanged. If no file identification is provided, the currently opened canvas is used.

```uri
obsidian://adv-uri?vault=<your-vault>&canvasviewport=100%2C-300%2C0.5
```

```uri
obsidian://adv-uri?vault=<your-vault>&canvasviewport=-%2C-300%2C-
```

--------------------------------

### Change Canvas Viewport via URI

Source: https://publish.obsidian.md/advanced-uri-doc/Actions/Canvas

This action allows for incremental changes to the canvas viewport's x, y, and zoom. Prefix values with '++' to add or '--' to subtract. Values are comma-separated, and a hyphen '-' can be used to leave a parameter unchanged. If no file identification is provided, the currently opened canvas is used.

```uri
obsidian://adv-uri?vault=<your-vault>&canvasviewport=++100%2C--300%2C++0.5
```

--------------------------------

### Overwrite Data in File using Advanced URI

Source: https://publish.obsidian.md/advanced-uri-doc/Actions/Writing

Overwrites the content of a specified file with new data, even if the file already exists. Data must be URL-encoded.

```uri
obsidian://adv-uri?vault=<your-vault>&filepath=my-file&data=This%20text%20is%20overwritten&mode=overwrite
```

--------------------------------

### Advanced URI with Last Used Vault

Source: https://publish.obsidian.md/advanced-uri-doc/Concepts/Schema

Illustrates an advanced Obsidian URI that defaults to using the last accessed vault when the 'vault' parameter is omitted.

```uri
obsidian://adv-uri?key1=value1
```
Tokens:
Raw