Using Hookmark 3.4.3 with Obsidian

This page documents using Hookmark with Obsidian for Hookmark 3.4.3.

If you have upgraded to Hookmark 3.5, then please refer to Using Hookmark with Obsidian.

Obsidian is an Electron-based note-taking app that treats links as first class data objects. It is “a powerful knowledge base that works on top of a local folder of plain text Markdown files.”

With Hookmark, you can easily link your Obsidian notes to just about anything. Not just to other Obsidian notes, but to emails, web pages, and more. Plus, Hookmark provides a native Mac user interface experience to linking Obsidian information. With Hookmark, you can use the same familiar interactions across all your favorite apps, including Obsidian.

As of Hookmark 3.4.3, Hookmark enables you to choose one of three different URL schemes for Obsidian (default, “advanced” URI, and hook file). The default option is available ‘out of the box’ with certain benefits. There are trade-offs between each. In addition, of course, Hookmark Pro users can customize Hookmark’s integration with Obsidian using Hookmark’s Script Editor.

Using the default integration between Hookmark and Obsidian

When you use the default integration with Obsidian, Hookmark’s Copy Link and Copy Markdown Link will return obsidian:// links. When you hook items together, using the menu bar icon or Hookmark’s contextual popup window, Hookmark will also use obsidian:// links for the note.

For most people this will be sufficient.

Summary of tradeoffs between URL schemes

Feature default “advanced URI” hook://file/
Reveal File in Finder x x √
requires advanced plugin x √ √
Hook to New x √ x. (creates file but hook is asymmetric from source to file)
open links/hooks directly in obsidian √ √ x
can move files in same vault x √ √
can move the file to a different vault, and anywhere on your Mac, and the hooks will still be there x x √
If you switch away from obsidian, your links will still work x x √
Avoids use of clipboard for interacting with Obsidian x v √
Avoids adding info to the body of the note file √ x √

Benefits of the default integration with Obsidian

  • Works out of the box; no configuration of Obsidian or Hookmark required.
  • Works with the Hookmark menu bar icon (not the case for the “advanced URI” or “hook file” integration with Obsidian).
  • Links generated by Hookmark can be used across devices even without Hookmark (e.g., on Windows or iPhone), as long as you sync your Obsidian files properly.

Limitations of default integration with Obsidian

There are some limitations to the default integration which are due to the fact that Obsidian is an Electron app that lacks a built-in API that Hookmark can use to get the file path and name of the current note, and to create new notes. With the default integration:

  1. You won’t be able to use the Hook to New > Obsidian note feature. If you want to hook anything (such as an email, web page, etc.) to a new Obsidian note, you’ll first need to create the note in Obsidian, then hook the note to that.
  2. You won’t be able to use Hookmark’s Reveal File in Finder feature in Obsidian. You’ll need to use Obsidian’s UI which it calls Show in system explorer or a custom keyboard shortcut in Obsidian.
  3. If you switch away from Obsidian to a different note-taking app in the future, you won’t be able to use these (obsidian://) links.

These limitations may be overcome in the future if Dyna List, the makers of Obsidian, add more built-in APIs for linking. (That’s something which is discussed on the Obsidian forum.)

Using the “Advanced URI” integration between Hookmark and Obsidian

There is a free Obsidian community integration plugin called “Advanced URI” made by Vinzent. This plugin provides a number of useful functions. The main effect of this plugin is to change the URI scheme of notes within Obsidian itself to obsidian://advanced-uri. The main benefit of this plugin, whether you use Hookmark or not, is that links created with it are robust, meaning you can move the notes around within the same vault (not between vaults, let alone outside Obsidian) and the links will still work.

This plugin works by adding an ID to any Obsidian file to which it generates links. For example, it may add the following to the top of the file:

---
id: 2d73ce68-9e27-4463-8d21-443bc4a9cb02
---

When you create a link with this plugin installed, the link’s address (URL) includes the ID. An example is obsidian://advanced-uri?vault=myVault&uid=2d73ce68-9e27-4463-8d21-443bc4a9cb02. Notice the “UID” field. (The “UID” keyword is configurable).

If you would like Hookmark to use the “advanced URI” integration, you’ll need to:

  1. Install the “Advanced URI” plugin from within the Obsidian app. Search for “Advanced URI” in the community plugin browser interface. See Plugins mini FAQ.
  2. Enable Use UID instead of file paths in the Advanced URI plugin’s settings. To get there, you can use the gear menu at the bottom right of the plugin’s UI. Or click on Obsidian > Settings > Advanced URI. You can also configure the UID field in frontmatter field (e.g., with ui or uid.
  3. Issue the following command from the /Applications/Utilities/Terminal app:

defaults write com.cogsciapps.hook integration.obsidian.URL.scheme obsidian-advanced-URI

To learn more about this plugin, visit Vinzent03/obsidian-advanced-uri: Advanced modes for Obsidian URI.


How to switch between integration schemes

Using /Applications/Utilities/Terminal you can manipulate the URL scheme (“integration.obsidian.URL.scheme”) used by Hookmark with Obsidian.

  • defaults write com.cogsciapps.hook integration.obsidian.URL.scheme obsidian-default
  • defaults write com.cogsciapps.hook integration.obsidian.URL.scheme obsidian-advanced-URI
  • defaults write com.cogsciapps.hook integration.obsidian.URL.scheme hook-file

Using the hook://file/ URL scheme with Obsidian

To use the hook://file/ URL scheme with Obsidian you will need to:

  1. Install and enable the Advanced URI Obsidian plugin described above. Hookmark needs the advanced URI plugin to get the note’s filepath (i.e., its location).
  2. Do this from the command line: defaults write com.cogsciapps.hook integration.obsidian.URL.scheme hook-file.

Advantages of hook://file/ scheme over the advanced URI scheme (and the default):

  1. You can move the file to a different vault, anywhere on your Mac, and the hooks will still be there.
  2. Reveal File in Finder works.
  3. If you switch away from Obsidian, your links will still work.

Disadvantage of hook://file/ scheme in Obsidian: hook://file/ links cannot be opened directly in Obsidian.

A fourth alternative

On 2022-03-12, @voostindie published an alternative integration script that uses the default obsidian:// scheme. He reports its links are robust. It does not require a plugin. It requires adding a shell script that is accessible to the macOS user account in which the Hookmark instance is running.

That scheme parses the library file to get its file path. However, as the Obsidian developers say, this relies on an implementation detail that may change at any time. Caveat emptor applies. Having said that, if that particular implementation breaks, users should still be able to switch to one of Hookmark’s built-in schemes. Hence no work would be lost.

“Can I switch integration schemes later?”

The links generated by Copy Link and Copy Markdown Link will continue to work even if you switch schemes.

However, for any given Obsidian note, you will not see any “hook” (in the Hookmark window) that was associated with this note if it was generated when a different scheme was in place. (That’s because hooks are based on URI address of the item). If you change back to the other scheme, the hooks will appear again. Regardless, you should be able to find the links in Hook’s search, which is context agnostic.

Other information

Forum discussion

See Link Obsidian with AdvancedURI Plugin for the discussion that led to the advanced URI integration.

There are other discussions about Obsidian on the Hookmark Forum.

April 2022: Obsidian Default being updated

Insider build of Obsidian v0.14.5 now has x-callback-url to support integration with Hookmark. This is more reliable. And it means Hook to New is now supported. We will roll out the integration after Obsidian v0.14.5 is available generally.

If you have access to insider builds, you can use these scripts in Hookmark. Click on Obsidian in the Script Editor pane, and apply these two:

get address


-- to use Obsidian's advanced URL script, type this at the command line
-- defaults write com.cogsciapps.hook integration.obsidian.URL.scheme obsidian-advanced-URI
-- https://hookproductivity.com/help/integration/using-hook-with-obsidian

set prefUrl to ""
try
    set prefUrl to (do shell script "defaults read com.cogsciapps.hook integration.obsidian.URL.scheme")

on error errMsg
end try

if prefUrl is not "" and prefUrl is not "obsidian-default" and prefUrl is not "hook-file" then

    if prefUrl is "obsidian-advanced-URI" then
        set urlKey to "advanceduri"

        -- An invalid value for com.cogsciapps.hook integration.obsidian.URL.scheme  has been set. There, we present the following options and set the default here.
    else
        set thePrefChoices to {"obsidian-default (obsidian://)", "obsidian-advanced-URI (obsidian://advanced-uri)", "hook-file (hook://file/)"}
        set thePrefChoice to choose from list thePrefChoices with prompt "Please select one of the following URL schemes with which to interact with Obsidian:" default items {"obsidian-default (obsidian://)"}
        if thePrefChoice is not false then
            set x to thePrefChoice as text
            set AppleScript's text item delimiters to {" "}
            set urlKey to text item 1 of x

            do shell script "defaults write com.cogsciapps.hook integration.obsidian.URL.scheme  " & urlKey

        end if
        return

    end if


    set callbackURL to "hook://x-callback-url/setCurrentNode%3FurlKey%3D" & urlKey & "%26plusencoded%3Dyes"
    set callbackURLError to "hook://x-callback-url/setCurrentNodeError"


    set myURL to "obsidian://hook-get-advanced-uri?" & "x-error=" & callbackURLError & "&x-success=" & callbackURL

    set myScript to "open '" & myURL & "'"

    do shell script myScript

else
    if prefUrl is "" or prefUrl is "obsidian-default" then
        set urlKey to ""
    else
        set urlKey to "%26urlKey%3Dfile"
    end if
    set callbackURL to "hook://x-callback-url/setCurrentNode%3FtitleKey%3Dname" & urlKey
    set callbackURLError to "hook://x-callback-url/setCurrentNodeError"

    set myURL to "obsidian://hook-get-address?" & "&x-error=" & callbackURLError & "&x-success=" & callbackURL
    set myScript to "open '" & myURL & "'"
    do shell script myScript

end if

return "hook://x-callback-url/setCurrentNode"

New Item Script


use framework "Foundation"
use scripting additions


property NSString : a reference to current application's NSString
property NSMutableCharacterSet : a reference to current application's NSMutableCharacterSet

set fileType to ".md"

set prefUrl to ""
try
    set prefUrl to (do shell script "defaults read com.cogsciapps.hook integration.obsidian.URL.scheme")

on error errMsg
end try

set callbackURL to "hook://x-callback-url/link-to-new"
set encodedSrc to "$encoded_link"
set callbackURLError to "hook://x-callback-url/error"

set encodedTitle to "$encoded_title"
set encodedLink to "$user_link"

set theString to NSString's stringWithString:encodedLink
set charset to NSMutableCharacterSet's URLQueryAllowedCharacterSet's mutableCopy
charset's removeCharactersInString:"&=?"
set encodedLink to theString's stringByAddingPercentEncodingWithAllowedCharacters:charset

if encodedTitle ends with fileType then
    set fileType to ""

end if

set theString to NSString's stringWithString:encodedTitle

--remove /  :  because Obsidian would not create a file if the file name contains those characters
set theString to theString's stringByReplacingOccurrencesOfString:"/" withString:""
set theString to theString's stringByReplacingOccurrencesOfString:"%5C" withString:""
set theString to theString's stringByReplacingOccurrencesOfString:":" withString:""

--remove | ^ because they will cause file existence validation problem
set theString to theString's stringByReplacingOccurrencesOfString:"%5E" withString:""
set theString to theString's stringByReplacingOccurrencesOfString:"%7C" withString:""

set encodedTitle to theString as string

if prefUrl is not "" and prefUrl is not "obsidian-default" and prefUrl is not "hook-file" then

    if prefUrl is "obsidian-advanced-URI" then
        set urlKey to "advanceduri"

        -- An invalid value for com.cogsciapps.hook integration.obsidian.URL.scheme  has been set. There, we present the following options and set the default here.
    else
        set thePrefChoices to {"obsidian-default (obsidian://)", "obsidian-advanced-URI (obsidian://advanced-uri)", "hook-file (hook://file/)"}
        set thePrefChoice to choose from list thePrefChoices with prompt "Please select one of the following URL schemes with which to interact with Obsidian:" default items {"obsidian-default (obsidian://)"}
        if thePrefChoice is not false then
            set x to thePrefChoice as text
            set AppleScript's text item delimiters to {" "}
            set urlKey to text item 1 of x
            do shell script "defaults write com.cogsciapps.hook integration.obsidian.URL.scheme  " & urlKey

        end if
        return

    end if

    set encodedTitle to theString's stringByAddingPercentEncodingWithAllowedCharacters:charset

    set callbackURL to callbackURL & "?src=" & encodedSrc & "&titleKey=name&urlKey=advanceduri"


    set theString to NSString's stringWithString:callbackURL

    set callbackURL to theString's stringByAddingPercentEncodingWithAllowedCharacters:charset

    set myURL to "obsidian://advanced-uri?filename=" & encodedTitle & fileType & "&data=[" & encodedTitle & "](" & encodedLink & ")&mode=new&x-success=" & callbackURL & "&x-error=" & callbackURLError
    set myScript to "open " & quoted form of myURL

    do shell script myScript

    return "hook://link-to-new"


end if

if prefUrl is "" or prefUrl is "obsidian-default" then
    set urlKey to ""
else
    set urlKey to "%26urlKey%3Dfile"
end if


set callbackURL to callbackURL & "%3Fsrc%3D" & encodedSrc & "%26titleKey%3Dname" & urlKey


set myURL to "obsidian://new?name=" & encodedTitle & fileType & "&content=[" & encodedTitle & "](" & encodedLink & ")&x-success=" & callbackURL & "&x-error=" & callbackURLError
set myScript to "open " & quoted form of myURL

do shell script myScript

return "hook://link-to-new"

Customer support for Obsidian integration

Please note that the “advanced URI” plugin is created by a third-party developer. CogSci Apps Corp. is not responsible for it and may not necessarily provide support for it. You should direct your questions about it to the Obsidian forum or Hookmark forum.

Default Obsidian integration is also limited due to the fact that Obsidian’s linking API does not meet the requirements of the Manifesto for Ubiquitous Linking, as noted above.

Gratitude