b7a7741bb0
Instead of implementing our own templating system, we abuse org-capture's templating system. We add 2 additional properties: - :head: a starting template that goes at the beginning of the file. - :file-name: a string that expands to the file name The templates are customizable at `org-roam-capture-templates` and `org-roam-ref-capture-templates`.
3.7 KiB
What is Roam protocol?
Org-roam defines two protocols that help boost productivity, by
extending org-protocol: 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.
Org-protocol Setup
The instructions for setting up org-protocol can be found here, but they are reproduced below.
Across all platforms, to enable org-roam-protocol, you have to add
the following to your init file:
(require 'org-roam-protocol)
We 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 to this, recommended in Issue #115, is to use Platypus. Here are the instructions for setting up with Platypus and Chrome:
- Install and launch Platypus (with Homebrew):
brew cask install playtpus
- Platypus settings:
- App Name:
OrgProtocol - Script Type:
envand/usr/bin/env - Script Path:
/path/to/emacsclient $1 - Tick Accept dropped items and click Settings
- Tick Accept dropped files
- Tick Register as URI scheme handler
- Add
org-protocolas a protocol - Create the app
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