Skip to content

Latest commit

 

History

History
152 lines (100 loc) · 7.62 KB

نشانیِ اوبسیدین.md

File metadata and controls

152 lines (100 loc) · 7.62 KB
Raw
alias
Using Obsidian URI

Obsidian supports a custom URI protocol obsidian:// which can be used to trigger various actions within the app. This is commonly used on macOS and mobile apps for automation and cross-app workflows.

If you have Obsidian installed, this link will open the app on your device: Click here

Installing Obsidian URI

To make sure your operating system redirect obsidian:// URIs to the Obsidian app, there may be additional steps you need to perform.

  • On Windows, running the app once should be sufficient. This will register for the obsidian:// custom protocol handler in the Windows registry.
  • On macOS, running the app once should be sufficient, however, your app must be installer version 0.8.12 or later.
  • On Linux, there's a much more involved process:
    • First, ensure you create a obsidian.desktop file. See here for details
    • Ensure that your desktop file specifies the Exec field as Exec=executable %u. The %u is used to pass the obsidian:// URIs to the app.
    • If you're using the AppImage installer, you may have to unpack it using Obsidian-x.y.z.AppImage --appimage-extract. Then make sure the Exec directive points to the unpacked executable.

Using Obsidian URIs

Obsidian URIs are typically in this format:

obsidian://action?param1=value&param2=value
  • The action is usually the action that you would like to perform.

Encoding

==Important==

Ensure that your values are properly URI encoded. For example, forward slash characters / must be encoded as %2F and space characters must be encoded as %20.

This is especially important because an improperly encoded "reserved" character may break the interpretation of the URI. See here for details

Available actions

Action open

Description: Opens an Obsidian vault, and possibly open a file within that vault.

Possible parameters:

  • vault can be either the vault name, or the vault ID.
    • The vault name is simply the name of the vault folder.
    • The vault ID is the random 16-character code assigned to the vault. This ID is unique per folder on your computer. Example: ef6ca3e3b524d22f. There isn't an easy way to find this ID yet, one will be offered at a later date in the vault switcher. Currently it can be found in %appdata%/obsidian/obsidian.json for Windows. For macOS, replace %appdata% with ~/Library/Application Support/. For Linux, replace %appdata% with ~/.config/.
  • file can be either a file name, or a path from the vault root to the specified file.
    • To resolve the target file, Obsidian uses the same link resolution system as a regular [[wikilink]] within the vault.
    • If the file extension is md, the extension can be omitted.
  • path an absolute file system path to a file.
    • Using this parameter will override both vault and file.
    • This will cause the app to search for the most specific vault which contains the specified file path.
    • Then the rest of the path replaces the file parameter.

Examples:

  • obsidian://open?vault=my%20vault This opens the vault my vault. If the vault is already open, focus on the window.

  • obsidian://open?vault=ef6ca3e3b524d22f This opens the vault identified by the ID ef6ca3e3b524d22f.

  • obsidian://open?vault=my%20vault&file=my%20note This opens the note my note in the vault my vault, assuming my note exists and the file is my note.md.

  • obsidian://open?vault=my%20vault&file=my%20note.md This also opens the note my note in the vault my vault.

  • obsidian://open?vault=my%20vault&file=path%2Fto%2Fmy%20note This opens the note located at path/to/my note in the vault my vault.

  • obsidian://open?path=%2Fhome%2Fuser%2Fmy%20vault%2Fpath%2Fto%2Fmy%20note This will look for any vault that contains the path /home/user/my vault/path/to/my note. Then, the rest of the path is passed to the file parameter. For example, if a vault exists at /home/user/my vault, then this would be equivalent to file parameter set to path/to/my note.

  • obsidian://open?path=D%3A%5CDocuments%5CMy%20vault%5CMy%20note This will look for any vault that contains the path D:\Documents\My vault\My note. Then, the rest of the path is passed to the file parameter. For example, if a vault exists at D:\Documents\My vault, then this would be equivalent to file parameter set to My note.

Action search

Description: Opens [[جست‌وجو]] in the specified vault, and optionally perform a search query.

Possible parameters:

  • vault can be either the vault name, or the vault ID. Same as action open.
  • query (optional) The search query to perform.

Examples:

  • obsidian://search?vault=my%20vault This opens the vault my vault, and opens [[جست‌وجو]].

  • obsidian://search?vault=my%20vault&query=MOC This opens the vault my vault, opens [[جست‌وجو]], and performs a search for MOC.

Action new

Description: Creates a new note in the vault, optionally with some content.

Possible parameters:

  • vault can be either the vault name, or the vault ID. Same as action open.
  • name the file name to be created. If this is specified, the file location will be chosen based on your "Default location for new notes" preferences.
  • file a vault absolute path, including the name. Will override name if specified.
  • path a globally absolute path. Works similar to the path option in the open action, which will override both vault and file.
  • content (optional) the contents of the note.
  • silent (optional) set this if you don't want to open the new note.
  • append (optional) append to an existing file if one exists.
  • overwrite (optional) overwrite an existing file if one exists, but only if append isn't set.
  • x-success (optional) see [[#x-callback-url]].

Examples:

  • obsidian://new?vault=my%20vault&name=my%20note This opens the vault my vault, and creates a new note called my note.
  • obsidian://new?vault=my%20vault&path=path%2Fto%2Fmy%20note This opens the vault my vault, and creates a new note at path/to/my note.

Action hook-get-address

Description: Endpoint for use with Hook. Use: obsidian://hook-get-address

If x-success is defined, this API will use it as the x-callback-url. Otherwise, it will copy a Markdown link of the current focused note to the clipboard, as an obsidian://open URL.

Possible parameters:

  • vault (optional) can be either the vault name, or the vault ID. If not provided, the current or last focused vault will be used.
  • x-success (optional) see [[#x-callback-url]].
  • x-error (optional) see [[#x-callback-url]].

x-callback-url

Available since v0.14.3.

Some endpoints will accept the x-callback-url parameters x-success and x-error. When it's provided, Obsidian will provide the following to the x-success callback:

  • name the name of the file, without the file extension.
  • url the obsidian:// URI for this file.
  • file (desktop only) the file:// URL for this file.

For example, if we receive obsidian://.....x-success=myapp://x-callback-url The response could be myapp://x-callback-url?name=...&url=obsidian%3A%2F%2Fopen...&file=file%3A%2F%2F...

Shorthand formats

In addition to the formats above, there are two more "shorthand" formats available to open vaults and files:

  • obsidian://vault/my vault/my note is equivalent to obsidian://open?vault=my%20vault&file=my%20note
  • obsidian:///absolute/path/to/my note is equivalent to obsidian://open?path=%2Fabsolute%2Fpath%2Fto%2Fmy%20note