4.8 KiB
What is Roam protocol?
Org-roam extending org-protocol
with 2 protocols: the roam-file
and roam-ref
protocol.
The roam-file
protocol
This is a simple protocol that opens the path specified by the file
key (e.g. org-protocol://roam-file?file=/tmp/file.org
). This is used
in the generated graph.
The roam-ref
Protocol
This protocol finds or creates a new note with a given ROAM_KEY
(see
Anatomy):
To use this, create a Firefox bookmarklet as follows:
javascript:location.href =
'org-protocol:/roam-ref?template=r&ref='
+ encodeURIComponent(location.href)
+ '&title='
+ encodeURIComponent(document.title)
where template
is the template key for a template in
org-roam-ref-capture-templates
. More documentation on the templating
system can be found here.
These templates should contain a #+ROAM_KEY: ${ref}
in it.
Setting up Org-roam protocol
To enable org-roam's protocol extensions, you have to add the following to your init file:
(require 'org-roam-protocol)
The instructions for setting up org-protocol
can be found
here, but they are reproduced below.
We will also need to create a desktop application for emacsclient
.
The instructions for various platforms are shown below:
Linux
Create a desktop application. I place mine in
~/.local/share/applications/org-protocol.desktop
:
[Desktop Entry]
Name=Org-Protocol
Exec=emacsclient %u
Icon=emacs-icon
Type=Application
Terminal=false
MimeType=x-scheme-handler/org-protocol
Associate org-protocol://
links with the desktop application by
running in your shell:
xdg-mime default org-protocol.desktop x-scheme-handler/org-protocol
To disable the "confirm" prompt in Chrome, you can also make Chrome
show a checkbox to tick, so that the Org-Protocol Client
app will be used
without confirmation. To do this, run in a shell:
sudo mkdir -p /etc/opt/chrome/policies/managed/
sudo tee /etc/opt/chrome/policies/managed/external_protocol_dialog.json >/dev/null <<'EOF'
{
"ExternalProtocolDialogShowAlwaysOpenCheckbox": true
}
EOF
sudo chmod 644 /etc/opt/chrome/policies/managed/external_protocol_dialog.json
and then restart Chrome (for example, by navigating to chrome://restart) to make the new policy take effect.
See here
for more info on the /etc/opt/chrome/policies/managed
directory and
here
for information on the ExternalProtocolDialogShowAlwaysOpenCheckbox
policy.
Mac OS
One solution is to use Platypus. Here are the instructions for setting up with Platypus and Chrome:
- Install and launch Platypus (with Homebrew):
brew cask install platypus
- Create a script
launch_emacs.sh
:
#!/usr/bin/env bash
/usr/local/bin/emacsclient --no-wait $1
- Create a Platypus app with the following settings:
| Setting | Value |
|--------------------------------+---------------------------|
| App Name | "OrgProtocol" |
| Script Type | "env" · "/usr/bin/env" |
| Script Path | "path/to/launch-emacs.sh" |
| Interface | None |
| Accept dropped items | true |
| Remain running after execution | false |
Inside Settings
:
| Setting | Value |
|--------------------------------+----------------|
| Accept dropped files | true |
| Register as URI scheme handler | true |
| Protocol | "org-protocol" |
To disable the "confirm" prompt in Chrome, you can also make Chrome
show a checkbox to tick, so that the OrgProtocol
app will be used
without confirmation. To do this, run in a shell:
defaults write com.google.Chrome ExternalProtocolDialogShowAlwaysOpenCheckbox -bool true
Note for Emacs Mac Port
If you're using Emacs Mac Port, it
registered its Emacs.app
as the default handler for the URL scheme
org-protocol
. We have to make our OrgProtocol.app
the default
handler instead (replace org.yourusername.OrgProtocol
with your app
identifier):
$ defaults write com.apple.LaunchServices/com.apple.launchservices.secure LSHandlers -array-add \
'{"LSHandlerPreferredVersions" = { "LSHandlerRoleAll" = "-"; }; LSHandlerRoleAll = "org.yourusername.OrgProtocol"; LSHandlerURLScheme = "org-protocol";}'
Then restart your computer.