Using Hook 3.4.3 with Obsidian
This page documents using Hook with Obsidian for Hook 3.4.3
If you have upgraded to Hook 3.5, then please refer to Using Hook with Obsidian – Hook.
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 Hook, 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, Hook provides a native Mac user interface experience to linking Obsidian information. With Hook, you can use the same familiar interactions across all your favorite apps, including Obsidian.
As of Hook 3.4.3, Hook enables you to choose one of three different URL schemes for Obsidian (default, “advanced” URI, hook file. The default option is available ‘out of the box’ with certain benefits. There are trade-offs between each. In addition, of course, Pro users can customize Hook’s integration with Obsidian using Hook’s Script Editor.
Using the default integration between Hook and Obsidian
When you use the default integration with Obsidian, Hook’s Copy Link
and Copy Markdown Link
will return obsidian://
links. When you hook items together, using menu bar icon or Hook’s contextual popup window, Hook 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 outside the box, no configuration of Obsidian or Hook required
- works with Hook menu bar icon (not the case for the “advanced URI” or “hook file” integration with Obsidian
- links generated by Hook can be used across devices even without Hook (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 Hook can use to get the file path and name of the current note, and to create new notes. With the default integration,
- 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 thing.
- You won’t be able to use Hook’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. - 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.)
- you can overcome limitations 1 by using the “advanced” URI integration.
- you can overcome limitations 1, 2 and and 3 by using the hook file (
hook://file/
) integration schemes.
Using the “Advanced URI” integration between Hook and Obsidian
There is a free Obsidian community plugin integration 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 Hook 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 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 Hook to use the “advanced URI” integration, you’ll need to:
- install the “advanced URI” plugin from within the Obsidian app. Search for “Advanced URI” in the community plugin browser interface. See Plugins mini FAQ – FAQ – Obsidian Forum.
- enable the
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 theUID field in frontmatter
field (e.g., withui
oruid
. - 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.
If you configure Hook to use the Advanced URI integration scheme with Hook, then whenever you link items with Hook (whether via Copy Link
, Copy Markdown Link
, or Hook to New
) then
How to switch between integration schemes
Using /Applications/Utilities/Terminal you can manipulate the URL scheme (“integration.obsidian.URL.scheme”) used by Hook 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:
- install and enable the Advanced URI Obsidian plugin described above. Hook needs the advanced URI plugin to get the note’s filepath (i.e., its location).
- 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):
- you can move the file to a different vault, and anywhere on our Mac, and the hooks will still be there.
Reveal File in Finder
in works.- 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 Hook instance is running.
However, 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 Hook’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 hook 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 link in Hook’s search, which is context agnostic.
Other information
Forum discussion
See Link Obsidian with AdvancedURI Plugin – Discussion & Help – Hook Productivity Forum for the discussion that led to the advanced URI integration.
There are other discussions Obsidian on the Hook Productivity Forum
April 2022: Obsidian Default being updated
Insider build of Obsidian v0.14.5 now has x-callback-url to support integration with Hook. 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 Hook. Click on Obsidian in 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 Hook 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
- Thanks to Lisa Sieverts for being a liaison between CogSci Apps and the Obsidian community.
- Thanks to thank Josh Nichols for publishing JavaScript on which Hook’s integration is based on which the default integration is based. Josh is known as technicalpickles on Github and on Obsidian’s Forum and @techpickles on Twitter.
- Thanks to Vinzent for developing the “Advanced URI” community plugin.
- Thanks also to many Hook Productivity Forum members who contributed to this discussion .