mirror of
https://github.com/org-roam/org-roam
synced 2025-09-30 17:00:56 -05:00
Deploying to gh-pages from @ 10e91a88c1 🚀
This commit is contained in:
jethrokuan
@@ -73,8 +73,8 @@ Next: <a href="Spaced-Repetition.html#Spaced-Repetition" accesskey="n" rel="next
|
||||
tight integration between
|
||||
<a href="https://github.com/jkitchin/org-ref">org-ref</a>,
|
||||
<a href="https://github.com/tmalsburg/helm-bibtex">helm-bibtex</a> and
|
||||
‘<samp>org-roam</samp>’. This helps you manage your bibliographic notes under
|
||||
‘<samp>org-roam</samp>’.
|
||||
<code>org-roam</code>. This helps you manage your bibliographic notes under
|
||||
<code>org-roam</code>.
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
@@ -74,7 +74,7 @@ the Org-roam codebase manageable. However, we attempt to accommodate as
|
||||
many usage styles as possible.
|
||||
</p>
|
||||
<p>All of Org-roam’s customization options can be viewed via
|
||||
‘<samp>M-x customize-group org-roam</samp>’.
|
||||
<code>M-x customize-group org-roam</code>.
|
||||
</p>
|
||||
<table class="menu" border="0" cellspacing="0">
|
||||
<tr><td align="left" valign="top">• <a href="Directories-and-Files.html#Directories-and-Files" accesskey="1">Directories and Files</a>:</td><td> </td><td align="left" valign="top">
|
||||
|
||||
@@ -26,7 +26,7 @@ General Public License for more details.
|
||||
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
||||
<link href="index.html#Top" rel="up" title="Top">
|
||||
<link href="Diagnosing-and-Repairing-Files.html#Diagnosing-and-Repairing-Files" rel="next" title="Diagnosing and Repairing Files">
|
||||
<link href="The-roam_002dref-Protocol.html#The-roam_002dref-Protocol" rel="prev" title="The roam-ref Protocol">
|
||||
<link href="The-roam_002dref-protocol.html#The-roam_002dref-protocol" rel="prev" title="The roam-ref protocol">
|
||||
<style type="text/css">
|
||||
<!--
|
||||
a.summary-letter {text-decoration: none}
|
||||
|
||||
@@ -85,7 +85,7 @@ for browsing and filtering org-roam notes.
|
||||
</pre></div>
|
||||
|
||||
<p>If the title of the Org file is not the first line, you might not get
|
||||
nice titles. You may choose to patch this to use ‘<samp>org-roam</samp>’’s
|
||||
nice titles. You may choose to patch this to use <code>org-roam</code>’s
|
||||
functionality. Here I’m using
|
||||
<a href="https://github.com/raxod502/el-patch">el-patch</a>:
|
||||
</p>
|
||||
|
||||
@@ -71,8 +71,8 @@ Next: <a href="Performance-Optimization.html#Performance-Optimization" accesskey
|
||||
|
||||
<p>Org-roam provides a utility for diagnosing and repairing problematic files via
|
||||
<code>org-roam-doctor</code>. By default, <code>org-roam-doctor</code> runs the check on the current
|
||||
Org-roam file. To run the check only for the current file, run ‘<samp>C-u M-x
|
||||
org-roam-doctor</samp>’, but note that this may take some time.
|
||||
Org-roam file. To run the check only for the current file, run <code>C-u M-x
|
||||
org-roam-doctor</code>, but note that this may take some time.
|
||||
</p>
|
||||
<ul>
|
||||
<li> Function: org-roam-doctor &optional this-buffer
|
||||
@@ -81,7 +81,7 @@ org-roam-doctor</samp>’, but note that this may take some time.
|
||||
the check only for the current buffer.
|
||||
</p></li></ul>
|
||||
|
||||
<p>The checks run are defined in ‘<samp>org-roam-doctor--checkers</samp>’. Each checker is an instance of ‘<samp>org-roam-doctor-checker</samp>’. To define a checker, use ‘<samp>make-org-roam-doctor-checker</samp>’. Here is a sample definition:
|
||||
<p>The checks run are defined in <code>org-roam-doctor--checkers</code>. Each checker is an instance of <code>org-roam-doctor-checker</code>. To define a checker, use <code>make-org-roam-doctor-checker</code>. Here is a sample definition:
|
||||
</p>
|
||||
<div class="lisp">
|
||||
<pre class="lisp">(make-org-roam-doctor-checker
|
||||
@@ -92,14 +92,14 @@ the check only for the current buffer.
|
||||
("R" . ("Replace link (keep label)" . org-roam-doctor--replace-link-keep-label))))
|
||||
</pre></div>
|
||||
|
||||
<p>The ‘<samp>:name</samp>’ property is the name of the function run. The function takes in the
|
||||
Org parse tree, and returns a list of ‘<samp>(point error-message)</samp>’. ‘<samp>:description</samp>’ is a
|
||||
short description of what the checker does. ‘<samp>:actions</samp>’ is an alist containing
|
||||
elements of the form ‘<samp>(char . (prompt . function))</samp>’. These actions are defined per
|
||||
<p>The <code>:name</code> property is the name of the function run. The function takes in the
|
||||
Org parse tree, and returns a list of <code>(point error-message)</code>. <code>:description</code> is a
|
||||
short description of what the checker does. <code>:actions</code> is an alist containing
|
||||
elements of the form <code>(char . (prompt . function))</code>. These actions are defined per
|
||||
checker, to perform autofixes for the errors. For each error detected,
|
||||
‘<samp>org-roam-doctor</samp>’ will move the point to the current error, and pop-up a help
|
||||
<code>org-roam-doctor</code> will move the point to the current error, and pop-up a help
|
||||
window displaying the error message, as well as the list of actions that can be
|
||||
taken provided in ‘<samp>:actions</samp>’.
|
||||
taken provided in <code>:actions</code>.
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
@@ -70,8 +70,8 @@ Next: <a href="Graphing.html#Graphing" accesskey="n" rel="next">Graphing</a>, Pr
|
||||
<h2 class="chapter">9 Encryption</h2>
|
||||
|
||||
<p>One may wish to keep private, encrypted files. Org-roam supports encryption (via
|
||||
GPG), which can be enabled for all new files by setting ‘<samp>org-roam-encrypt-files</samp>’
|
||||
to ‘<samp>t</samp>’. When enabled, new files are created with the ‘<samp>.org.gpg</samp>’ extension and
|
||||
GPG), which can be enabled for all new files by setting <code>org-roam-encrypt-files</code>
|
||||
to <code>t</code>. When enabled, new files are created with the <code>.org.gpg</code> extension and
|
||||
decryption are handled automatically by EasyPG.
|
||||
</p>
|
||||
<p>Note that Emacs will prompt for a password for encrypted files during
|
||||
|
||||
@@ -78,7 +78,7 @@ For example, a note for a website may contain a ref:
|
||||
</pre></div>
|
||||
|
||||
<p>These keys come in useful for when taking website notes, using the
|
||||
‘<samp>roam-ref</samp>’ protocol (see <a href="Roam-Protocol.html#Roam-Protocol">Roam Protocol</a>).
|
||||
<code>roam-ref</code> protocol (see <a href="Roam-Protocol.html#Roam-Protocol">Roam Protocol</a>).
|
||||
</p>
|
||||
<p>Alternatively, add a ref for notes for a specific paper, using its
|
||||
<a href="https://github.com/jkitchin/org-ref">org-ref</a> citation key:
|
||||
|
||||
@@ -79,9 +79,11 @@ workflows. Org-roam does not magically make note-taking better – this ofte
|
||||
requires a radical change in your current note-taking workflow. To understand
|
||||
more about the methods and madness, see <a href="Note_002dtaking-Workflows.html#Note_002dtaking-Workflows">Note-taking Workflows</a>.
|
||||
</p>
|
||||
<p>To begin using Org-roam, one should set the ‘<samp>org-roam-directory</samp>’ to the directory
|
||||
containing your notes. For this tutorial, create an empty directory, and set the
|
||||
‘<samp>org-roam-directory</samp>’:
|
||||
<p>To first start using Org-roam, one needs to pick a location to store the
|
||||
Org-roam files. The directory that will contain your notes, and database index
|
||||
is specified by the variable <code>org-roam-directory</code>. This variable needs to be set
|
||||
before any calls to Org-roam functions, including enabling <code>org-roam-mode</code>. For
|
||||
this tutorial, create an empty directory, and set <code>org-roam-directory</code>:
|
||||
</p>
|
||||
<div class="lisp">
|
||||
<pre class="lisp">(make-directory "~/org-roam")
|
||||
@@ -90,34 +92,34 @@ containing your notes. For this tutorial, create an empty directory, and set the
|
||||
|
||||
<p>We encourage using a flat hierarchy for storing notes, but some prefer using
|
||||
folders for storing specific kinds of notes (e.g. websites, papers). This is
|
||||
fine; Org-roam searches recursively within ‘<samp>org-roam-directory</samp>’ for any notes.
|
||||
fine; Org-roam searches recursively within <code>org-roam-directory</code> for any notes.
|
||||
Instead of relying on the file hierarchy for any form of categorization, we
|
||||
solely rely on links between files to establish connections between notes.
|
||||
</p>
|
||||
<p>Next, we need to enable the global minor mode ‘<samp>org-roam-mode</samp>’. This sets up Emacs
|
||||
<p>Next, we need to enable the global minor mode <code>org-roam-mode</code>. This sets up Emacs
|
||||
with several hooks, builds a cache and keeps it consistent. We recommend
|
||||
starting ‘<samp>org-roam-mode</samp>’ on startup:
|
||||
starting <code>org-roam-mode</code> on startup:
|
||||
</p>
|
||||
<div class="lisp">
|
||||
<pre class="lisp">(add-hook 'after-init-hook 'org-roam-mode)
|
||||
</pre></div>
|
||||
|
||||
<p>To build the cache manually, one can run ‘<samp>M-x org-roam-db-build-cache</samp>’. The cache
|
||||
is a sqlite database named ‘<samp>org-roam.db</samp>’, which defaults to residing in the root
|
||||
‘<samp>org-roam-directory</samp>’. Cache builds may take a while the first time, but is often
|
||||
instantaneous in subsequent runs.
|
||||
<p>To build the cache manually, one can run <code>M-x org-roam-db-build-cache</code>. The
|
||||
cache is a sqlite database named <code>org-roam.db</code>, which defaults to residing in
|
||||
the root <code>org-roam-directory</code>. Cache builds may take a while the first time, but
|
||||
is often instantaneous in subsequent runs.
|
||||
</p>
|
||||
<p>Let us now create our first note. Call ‘<samp>M-x org-roam-find-file</samp>’. This shows a list
|
||||
of titles for notes that reside in ‘<samp>org-roam-directory</samp>’. It should show nothing
|
||||
<p>Let us now create our first note. Call <code>M-x org-roam-find-file</code>. This shows a list
|
||||
of titles for notes that reside in <code>org-roam-directory</code>. It should show nothing
|
||||
right now, since there are no notes in the directory. Entering the title of the
|
||||
note you wish to create, and pressing ‘<samp>RET</samp>’ should begin the note creation
|
||||
process. This process uses ‘<samp>org-capture</samp>’’s templating system, and can be freely
|
||||
customized (see <a href="The-Templating-System.html#The-Templating-System">The Templating System</a>). Using the default template, pressing ‘<samp>C-c
|
||||
C-c</samp>’ finishes the note capture. Running ‘<samp>M-x org-roam-find-file</samp>’ again should show
|
||||
note you wish to create, and pressing <code>RET</code> should begin the note creation
|
||||
process. This process uses <code>org-capture</code>’s templating system, and can be freely
|
||||
customized (see <a href="The-Templating-System.html#The-Templating-System">The Templating System</a>). Using the default template, pressing <code>C-c
|
||||
C-c</code> finishes the note capture. Running <code>M-x org-roam-find-file</code> again should show
|
||||
the note you have created, and selecting that entry will bring you to that note.
|
||||
</p>
|
||||
<p>The crux of Org-roam is making it easy to create notes, and link them together.
|
||||
To link notes together, we call ‘<samp>M-x org-roam-insert</samp>’. This brings up a prompt
|
||||
To link notes together, we call <code>M-x org-roam-insert</code>. This brings up a prompt
|
||||
with a list of title for existing notes. Selecting an existing entry will create
|
||||
and insert a link to the current file. Entering a non-existent title will create
|
||||
a new note with that title. Good usage of Org-roam requires liberally linking
|
||||
@@ -126,7 +128,7 @@ notes.
|
||||
</p>
|
||||
<p>Org-roam provides an interface to view backlinks. It shows backlinks for the
|
||||
currently active Org-roam note, along with some surrounding context. To toggle
|
||||
the visibility of this buffer, call ‘<samp>M-x org-roam</samp>’.
|
||||
the visibility of this buffer, call <code>M-x org-roam</code>.
|
||||
</p>
|
||||
<p>For a visual representation of the notes and their connections, Org-roam also
|
||||
provides graphing capabilities, using Graphviz. It generates graphs with notes
|
||||
|
||||
@@ -75,22 +75,22 @@ Next: <a href="Excluding-Nodes-and-Edges.html#Excluding-Nodes-and-Edges" accessk
|
||||
<li> User Option: org-roam-graph-extra-config
|
||||
|
||||
<p>Extra options passed to graphviz for the digraph (The “G” attributes).
|
||||
Example: ‘<samp>'=(("rankdir" . "LR"))</samp>’
|
||||
Example: <code>'~(("rankdir" . "LR"))</code>
|
||||
</p>
|
||||
</li><li> User Option: org-roam-graph-node-extra-config
|
||||
|
||||
<p>Extra options for nodes in the graphviz output (The “N” attributes).
|
||||
Example: ‘<samp>'(("color" . "skyblue"))</samp>’
|
||||
Example: <code>'(("color" . "skyblue"))</code>
|
||||
</p>
|
||||
</li><li> User Option: org-roam-graph-edge-extra-config
|
||||
|
||||
<p>Extra options for edges in the graphviz output (The “E” attributes).
|
||||
Example: ‘<samp>'(("dir" . "back"))</samp>’
|
||||
Example: <code>'(("dir" . "back"))</code>
|
||||
</p>
|
||||
</li><li> User Option: org-roam-graph-edge-cites-extra-config
|
||||
|
||||
<p>Extra options for citation edges in the graphviz output.
|
||||
Example: ‘<samp>'(("color" . "red"))</samp>’
|
||||
Example: <code>'(("color" . "red"))</code>
|
||||
</p></li></ul>
|
||||
|
||||
|
||||
|
||||
@@ -73,7 +73,7 @@ Next: <a href="Org_002droam-Completion-System.html#Org_002droam-Completion-Syste
|
||||
notes. This is done by performing SQL queries and generating images using
|
||||
<a href="https://graphviz.org/">Graphviz</a>. The graph can also be navigated: see <a href="Roam-Protocol.html#Roam-Protocol">Roam Protocol</a>.
|
||||
</p>
|
||||
<p>The entry point to graph creation is ‘<samp>org-roam-graph</samp>’.
|
||||
<p>The entry point to graph creation is <code>org-roam-graph</code>.
|
||||
</p>
|
||||
<ul>
|
||||
<li> Function: org-roam-graph & optional arg file node-query
|
||||
@@ -83,19 +83,19 @@ If FILE is nil, default to current buffer’s file name.
|
||||
ARG may be any of the following values:
|
||||
</p>
|
||||
<ul>
|
||||
<li> ‘<samp>nil</samp>’ show the graph.
|
||||
</li><li> ‘<samp>C-u</samp>’ show the graph for FILE.
|
||||
</li><li> ‘<samp>C-u N</samp>’ show the graph for FILE limiting nodes to N steps.
|
||||
</li><li> ‘<samp>C-u C-u</samp>’ build the graph.
|
||||
</li><li> ‘<samp>C-u -</samp>’ build the graph for FILE.
|
||||
</li><li> ‘<samp>C-u -N</samp>’ build the graph for FILE limiting nodes to N steps.
|
||||
<li> <code>nil</code> show the graph.
|
||||
</li><li> <code>C-u</code> show the graph for FILE.
|
||||
</li><li> <code>C-u N</code> show the graph for FILE limiting nodes to N steps.
|
||||
</li><li> <code>C-u C-u</code> build the graph.
|
||||
</li><li> <code>C-u -</code> build the graph for FILE.
|
||||
</li><li> <code>C-u -N</code> build the graph for FILE limiting nodes to N steps.
|
||||
</li></ul>
|
||||
|
||||
</li><li> User Option: org-roam-graph-executable
|
||||
|
||||
<p>Path to the graphing executable (in this case, Graphviz). Set this if Org-roam is unable to find the Graphviz executable on your system.
|
||||
</p>
|
||||
<p>You may also choose to use ‘<samp>neato</samp>’ in place of ‘<samp>dot</samp>’, which generates a more
|
||||
<p>You may also choose to use <code>neato</code> in place of <code>dot</code>, which generates a more
|
||||
compact graph layout.
|
||||
</p>
|
||||
</li><li> User Option: org-roam-graph-viewer
|
||||
@@ -107,7 +107,7 @@ compact graph layout.
|
||||
</li><li> a function accepting a single argument: the graph file path.
|
||||
</li></ol>
|
||||
|
||||
<p>‘<samp>nil</samp>’ uses ‘<samp>view-file</samp>’ to view the graph.
|
||||
<p><code>nil</code> uses <code>view-file</code> to view the graph.
|
||||
</p>
|
||||
<p>If you are using WSL2 and would like to open the graph in Windows, you can use the second option to set the browser and network file path:
|
||||
</p>
|
||||
|
||||
@@ -70,11 +70,11 @@ Next: <a href="How-do-I-migrate-from-Roam-Research_003f.html#How-do-I-migrate-fr
|
||||
<h3 class="section">17.1 How do I have more than one Org-roam directory?</h3>
|
||||
|
||||
<p>Emacs supports directory-local variables, allowing the value of
|
||||
‘<samp>org-roam-directory</samp>’ to be different in different directories. It does this by
|
||||
checking for a file named ‘<samp>.dir-locals.el</samp>’.
|
||||
<code>org-roam-directory</code> to be different in different directories. It does this by
|
||||
checking for a file named <code>.dir-locals.el</code>.
|
||||
</p>
|
||||
<p>To add support for multiple directories, override the ‘<samp>org-roam-directory</samp>’
|
||||
variable using directory-local variables. This is what ‘<samp>.dir-locals.el</samp>’ may
|
||||
<p>To add support for multiple directories, override the <code>org-roam-directory</code>
|
||||
variable using directory-local variables. This is what <code>.dir-locals.el</code> may
|
||||
contain:
|
||||
</p>
|
||||
<div class="lisp">
|
||||
@@ -82,7 +82,7 @@ contain:
|
||||
</pre></div>
|
||||
|
||||
<p>All files within that directory will be treated as their own separate
|
||||
set of Org-roam files. Remember to run ‘<samp>org-roam-db-build-cache</samp>’ from a
|
||||
set of Org-roam files. Remember to run <code>org-roam-db-build-cache</code> from a
|
||||
file within that directory, at least once.
|
||||
</p>
|
||||
|
||||
|
||||
@@ -73,7 +73,7 @@ Up: <a href="Navigating-Around.html#Navigating-Around" accesskey="u" rel="up">Na
|
||||
to your main files.
|
||||
</p>
|
||||
<p>In Org-roam, you can define the path to your index file by setting
|
||||
‘<samp>org-roam-index-file</samp>’.
|
||||
<code>org-roam-index-file</code>.
|
||||
</p>
|
||||
<ul>
|
||||
<li> Variable: org-roam-index-file
|
||||
@@ -81,14 +81,14 @@ to your main files.
|
||||
<p>Path to the Org-roam index file.
|
||||
</p>
|
||||
<p>The path can be a string or a function. If it is a string, it should be the
|
||||
path (absolute or relative to ‘<samp>org-roam-directory</samp>’) to the index file. If it
|
||||
path (absolute or relative to <code>org-roam-directory</code>) to the index file. If it
|
||||
is is a function, the function should return the path to the index file.
|
||||
Otherwise, the index is assumed to be a note in ‘<samp>org-roam-index</samp>’ whose
|
||||
title is ‘<samp>"Index"</samp>’.
|
||||
Otherwise, the index is assumed to be a note in <code>org-roam-index</code> whose
|
||||
title is <code>"Index"</code>.
|
||||
</p>
|
||||
</li><li> Function: org-roam-find-index
|
||||
|
||||
<p>Opens the Index file in the current ‘<samp>org-roam-directory</samp>’.
|
||||
<p>Opens the Index file in the current <code>org-roam-directory</code>.
|
||||
</p></li></ul>
|
||||
|
||||
|
||||
|
||||
@@ -63,7 +63,7 @@ ul.no-bullet {list-style: none}
|
||||
<a name="Installation-_00281_0029"></a>
|
||||
<div class="header">
|
||||
<p>
|
||||
Next: <a href="The-roam_002dfile-protocol.html#The-roam_002dfile-protocol" accesskey="n" rel="next">The ‘<samp>roam-file</samp>’ protocol</a>, Previous: <a href="_005f.html#g_t_005f" accesskey="p" rel="prev">_</a>, Up: <a href="Roam-Protocol.html#Roam-Protocol" accesskey="u" rel="up">Roam Protocol</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
|
||||
Next: <a href="The-roam_002dfile-protocol.html#The-roam_002dfile-protocol" accesskey="n" rel="next">The roam-file protocol</a>, Previous: <a href="_005f.html#g_t_005f" accesskey="p" rel="prev">_</a>, Up: <a href="Roam-Protocol.html#Roam-Protocol" accesskey="u" rel="up">Roam Protocol</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
|
||||
</div>
|
||||
<hr>
|
||||
<a name="Installation-2"></a>
|
||||
@@ -75,12 +75,12 @@ Next: <a href="The-roam_002dfile-protocol.html#The-roam_002dfile-protocol" acces
|
||||
<pre class="lisp">(require 'org-roam-protocol)
|
||||
</pre></div>
|
||||
|
||||
<p>The instructions for setting up ‘<samp>org-protocol=</samp>’ are reproduced below.
|
||||
<p>The instructions for setting up <code>org-protocol</code> are reproduced below.
|
||||
</p>
|
||||
<p>We will also need to create a desktop application for ‘<samp>emacsclient</samp>’. The
|
||||
<p>We will also need to create a desktop application for <code>emacsclient</code>. The
|
||||
instructions for various platforms are shown below.
|
||||
</p>
|
||||
<p>For Linux users, create a desktop application in ‘<samp>~/.local/share/applications/org-protocol.desktop</samp>’:
|
||||
<p>For Linux users, create a desktop application in <code>~/.local/share/applications/org-protocol.desktop</code>:
|
||||
</p>
|
||||
<div class="example">
|
||||
<pre class="example">[Desktop Entry]
|
||||
@@ -92,7 +92,7 @@ Terminal=false
|
||||
MimeType=x-scheme-handler/org-protocol
|
||||
</pre></div>
|
||||
|
||||
<p>Associate ‘<samp>org-protocol://</samp>’ links with the desktop application by
|
||||
<p>Associate <code>org-protocol://</code> links with the desktop application by
|
||||
running in your shell:
|
||||
</p>
|
||||
<div class="example">
|
||||
@@ -100,7 +100,7 @@ running in your shell:
|
||||
</pre></div>
|
||||
|
||||
<p>To disable the “confirm” prompt in Chrome, you can also make Chrome
|
||||
show a checkbox to tick, so that the ‘<samp>Org-Protocol Client</samp>’ app will be used
|
||||
show a checkbox to tick, so that the <code>Org-Protocol Client</code> app will be used
|
||||
without confirmation. To do this, run in a shell:
|
||||
</p>
|
||||
<div class="example">
|
||||
@@ -116,8 +116,8 @@ sudo chmod 644 /etc/opt/chrome/policies/managed/external_protocol_dialog.json
|
||||
<p>and then restart Chrome (for example, by navigating to <chrome://restart>) to
|
||||
make the new policy take effect.
|
||||
</p>
|
||||
<p>See <a href="https://www.chromium.org/administrators/linux-quick-start">here</a> for more info on the ‘<samp>/etc/opt/chrome/policies/managed</samp>’ directory and
|
||||
<a href="https://cloud.google.com/docs/chrome-enterprise/policies/?policy=ExternalProtocolDialogShowAlwaysOpenCheckbox">here</a> for information on the ‘<samp>ExternalProtocolDialogShowAlwaysOpenCheckbox</samp>’ policy.
|
||||
<p>See <a href="https://www.chromium.org/administrators/linux-quick-start">here</a> for more info on the <code>/etc/opt/chrome/policies/managed</code> directory and
|
||||
<a href="https://cloud.google.com/docs/chrome-enterprise/policies/?policy=ExternalProtocolDialogShowAlwaysOpenCheckbox">here</a> for information on the <code>ExternalProtocolDialogShowAlwaysOpenCheckbox</code> policy.
|
||||
</p>
|
||||
<p>For MacOS, one solution is to use <a href="https://github.com/sveinbjornt/Platypus">Platypus</a>. Here are the instructions for
|
||||
setting up with Platypus and Chrome:
|
||||
@@ -131,7 +131,7 @@ setting up with Platypus and Chrome:
|
||||
</pre></div>
|
||||
|
||||
<ol>
|
||||
<li> Create a script ‘<samp>launch_emacs.sh</samp>’:
|
||||
<li> Create a script <code>launch_emacs.sh</code>:
|
||||
</li></ol>
|
||||
|
||||
<div class="example">
|
||||
@@ -155,7 +155,7 @@ setting up with Platypus and Chrome:
|
||||
</pre></div>
|
||||
|
||||
|
||||
<p>Inside ‘<samp>Settings</samp>’:
|
||||
<p>Inside <code>Settings</code>:
|
||||
</p>
|
||||
<div class="example">
|
||||
<pre class="example">| Setting | Value |
|
||||
@@ -166,7 +166,7 @@ setting up with Platypus and Chrome:
|
||||
</pre></div>
|
||||
|
||||
<p>To disable the “confirm” prompt in Chrome, you can also make Chrome
|
||||
show a checkbox to tick, so that the ‘<samp>OrgProtocol</samp>’ app will be used
|
||||
show a checkbox to tick, so that the <code>OrgProtocol</code> app will be used
|
||||
without confirmation. To do this, run in a shell:
|
||||
</p>
|
||||
<div class="example">
|
||||
@@ -175,7 +175,7 @@ without confirmation. To do this, run in a shell:
|
||||
|
||||
|
||||
<p>If you’re using <a href="https://github.com/railwaycat/homebrew-emacsmacport">Emacs Mac Port</a>, it registered its ‘Emacs.app‘ as the default
|
||||
handler for the URL scheme ‘org-protocol‘. To make ‘<samp>OrgProtocol.app</samp>’
|
||||
handler for the URL scheme ‘org-protocol‘. To make <code>OrgProtocol.app</code>
|
||||
the default handler instead, run:
|
||||
</p>
|
||||
<div class="example">
|
||||
@@ -185,7 +185,7 @@ the default handler instead, run:
|
||||
|
||||
<p>Then restart your computer.
|
||||
</p>
|
||||
<p>For Windows, create a temporary ‘<samp>org-protocol.reg</samp>’ file:
|
||||
<p>For Windows, create a temporary <code>org-protocol.reg</code> file:
|
||||
</p>
|
||||
<div class="example">
|
||||
<pre class="example">REGEDIT4
|
||||
@@ -210,7 +210,7 @@ the default handler instead, run:
|
||||
<hr>
|
||||
<div class="header">
|
||||
<p>
|
||||
Next: <a href="The-roam_002dfile-protocol.html#The-roam_002dfile-protocol" accesskey="n" rel="next">The ‘<samp>roam-file</samp>’ protocol</a>, Previous: <a href="_005f.html#g_t_005f" accesskey="p" rel="prev">_</a>, Up: <a href="Roam-Protocol.html#Roam-Protocol" accesskey="u" rel="up">Roam Protocol</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
|
||||
Next: <a href="The-roam_002dfile-protocol.html#The-roam_002dfile-protocol" accesskey="n" rel="next">The roam-file protocol</a>, Previous: <a href="_005f.html#g_t_005f" accesskey="p" rel="prev">_</a>, Up: <a href="Roam-Protocol.html#Roam-Protocol" accesskey="u" rel="up">Roam Protocol</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
@@ -70,7 +70,7 @@ Next: <a href="Note_002dtaking-Add_002dons.html#Note_002dtaking-Add_002dons" acc
|
||||
<h4 class="subsection">16.2.3 Org-journal</h4>
|
||||
|
||||
<p><a href="https://github.com/bastibe/org-journal">Org-journal</a> is a more
|
||||
powerful alternative to the simple function ‘<samp>org-roam-dailies-today</samp>’. It
|
||||
powerful alternative to the simple function <code>org-roam-dailies-today</code>. It
|
||||
provides better journaling capabilities, and a nice calendar interface
|
||||
to see all dated entries.
|
||||
</p>
|
||||
|
||||
@@ -76,14 +76,14 @@ system is configurable. The default setting,
|
||||
<pre class="lisp">(setq org-roam-completion-system 'default)
|
||||
</pre></div>
|
||||
|
||||
<p>uses Emacs’ standard ‘<samp>completing-read</samp>’. If you prefer
|
||||
<p>uses Emacs’ standard <code>completing-read</code>. If you prefer
|
||||
<a href="https://emacs-helm.github.io/helm/">Helm</a>, use
|
||||
</p>
|
||||
<div class="lisp">
|
||||
<pre class="lisp">(setq org-roam-completion-system 'helm)
|
||||
</pre></div>
|
||||
|
||||
<p>Other options include ‘<samp>'ido</samp>’, and ‘<samp>'ivy</samp>’.
|
||||
<p>Other options include <code>'ido</code>, and <code>'ivy</code>.
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
@@ -69,17 +69,17 @@ Next: <a href="Org_002droam-Files.html#Org_002droam-Files" accesskey="n" rel="ne
|
||||
<a name="Org_002droam-Links-1"></a>
|
||||
<h3 class="section">7.3 Org-roam Links</h3>
|
||||
|
||||
<p>Org-roam links are regular ‘<samp>file:</samp>’ links in Org-mode. By default, links are
|
||||
inserted with the title as the link description with ‘<samp>org-roam-insert</samp>’.
|
||||
<p>Org-roam links are regular <code>file:</code> links in Org-mode. By default, links are
|
||||
inserted with the title as the link description with <code>org-roam-insert</code>.
|
||||
</p>
|
||||
<ul>
|
||||
<li> User Option: org-roam-link-title-format
|
||||
|
||||
<p>To distinguish between org-roam links and regular links, one may choose to use
|
||||
special indicators for Org-roam links. Defaults to ‘<samp>"%s"</samp>’.
|
||||
special indicators for Org-roam links. Defaults to <code>"%s"</code>.
|
||||
</p>
|
||||
<p>If your version of Org is at least ‘<samp>9.2</samp>’, consider styling the link differently,
|
||||
by customizing the ‘<samp>org-roam-link</samp>’, and ‘<samp>org-roam-link-current</samp>’ faces.
|
||||
<p>If your version of Org is at least <code>9.2</code>, consider styling the link differently,
|
||||
by customizing the <code>org-roam-link</code>, and <code>org-roam-link-current</code> faces.
|
||||
</p></li></ul>
|
||||
|
||||
|
||||
|
||||
@@ -73,26 +73,26 @@ Previous: <a href="Template-Walkthrough.html#Template-Walkthrough" accesskey="p"
|
||||
allow prefilling of strings. We have seen a glimpse of this in <a href="Template-Walkthrough.html#Template-Walkthrough">Template
|
||||
Walkthrough</a>.
|
||||
</p>
|
||||
<p>In org-roam templates, the ‘<samp>${var}</samp>’ syntax allows for the expansion of
|
||||
variables, stored in ‘<samp>org-roam-capture--info</samp>’. For example, during
|
||||
‘<samp>org-roam-insert</samp>’, the user is prompted for a title. Upon entering a
|
||||
non-existent title, the ‘<samp>title</samp>’ key in ‘<samp>org-roam-capture--info</samp>’ is set to the
|
||||
provided title. ‘<samp>${title}</samp>’ is then expanded into the provided title during the
|
||||
<p>In org-roam templates, the <code>${var}</code> syntax allows for the expansion of
|
||||
variables, stored in <code>org-roam-capture--info</code>. For example, during
|
||||
<code>org-roam-insert</code>, the user is prompted for a title. Upon entering a
|
||||
non-existent title, the <code>title</code> key in <code>org-roam-capture--info</code> is set to the
|
||||
provided title. <code>${title}</code> is then expanded into the provided title during the
|
||||
org-capture process. Any variables that do not contain strings, are prompted for
|
||||
values using ‘<samp>completing-read</samp>’.
|
||||
values using <code>completing-read</code>.
|
||||
</p>
|
||||
<p>After doing this expansion, the org-capture’s template expansion system
|
||||
is used to fill up the rest of the template. You may read up more on
|
||||
this on <a href="https://orgmode.org/manual/Template-expansion.html#Template-expansion">org-capture’s documentation page</a>.
|
||||
</p>
|
||||
<p>To illustrate this dual expansion process, take for example the template string:
|
||||
‘<samp>"%<%Y%m%d%H%M%S>-${title}"</samp>’, with the title ‘<samp>"Foo"</samp>’. The template is first
|
||||
expanded into ‘<samp>%<%Y%m%d%H%M%S>-Foo</samp>’. Then org-capture expands ‘<samp>%<%Y%m%d%H%M%S></samp>’
|
||||
with timestamp: e.g. ‘<samp>20200213032037-Foo</samp>’.
|
||||
<code>"%<%Y%m%d%H%M%S>-${title}"</code>, with the title <code>"Foo"</code>. The template is first
|
||||
expanded into <code>%<%Y%m%d%H%M%S>-Foo</code>. Then org-capture expands <code>%<%Y%m%d%H%M%S></code>
|
||||
with timestamp: e.g. <code>20200213032037-Foo</code>.
|
||||
</p>
|
||||
<p>All of the flexibility afforded by Emacs and Org-mode are available. For
|
||||
example, if you want to encode a UTC timestamp in the filename, you can take
|
||||
advantage of org-mode’s ‘<samp>%(EXP)</samp>’ template expansion to call ‘<samp>format-time-string</samp>’
|
||||
advantage of org-mode’s <code>%(EXP)</code> template expansion to call <code>format-time-string</code>
|
||||
directly to provide its third argument to specify UTC.
|
||||
</p>
|
||||
<div class="lisp">
|
||||
|
||||
@@ -74,9 +74,9 @@ Next: <a href="Daily-Notes.html#Daily-Notes" accesskey="n" rel="next">Daily Note
|
||||
</td></tr>
|
||||
<tr><td align="left" valign="top">• <a href="Installation-_00281_0029.html#Installation-_00281_0029" accesskey="2">Installation</a>:</td><td> </td><td align="left" valign="top">
|
||||
</td></tr>
|
||||
<tr><td align="left" valign="top">• <a href="The-roam_002dfile-protocol.html#The-roam_002dfile-protocol" accesskey="3">The ‘<samp>roam-file</samp>’ protocol</a>:</td><td> </td><td align="left" valign="top">
|
||||
<tr><td align="left" valign="top">• <a href="The-roam_002dfile-protocol.html#The-roam_002dfile-protocol" accesskey="3">The roam-file protocol</a>:</td><td> </td><td align="left" valign="top">
|
||||
</td></tr>
|
||||
<tr><td align="left" valign="top">• <a href="The-roam_002dref-Protocol.html#The-roam_002dref-Protocol" accesskey="4">The ‘<samp>roam-ref</samp>’ Protocol</a>:</td><td> </td><td align="left" valign="top">
|
||||
<tr><td align="left" valign="top">• <a href="The-roam_002dref-protocol.html#The-roam_002dref-protocol" accesskey="4">The roam-ref protocol</a>:</td><td> </td><td align="left" valign="top">
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
|
||||
@@ -73,34 +73,34 @@ Next: <a href="File-Refs.html#File-Refs" accesskey="n" rel="next">File Refs</a>,
|
||||
where titles are insufficient. For example, tags allow for categorization of
|
||||
notes: differentiating between bibliographical and structure notes during interactive commands.
|
||||
</p>
|
||||
<p>Org-roam calls ‘<samp>org-roam--extract-tags</samp>’ to extract tags from files. It uses the
|
||||
variable ‘<samp>org-roam-tag-sources</samp>’, to control how tags are extracted. The tag
|
||||
<p>Org-roam calls <code>org-roam--extract-tags</code> to extract tags from files. It uses the
|
||||
variable <code>org-roam-tag-sources</code>, to control how tags are extracted. The tag
|
||||
extraction methods supported are:
|
||||
</p>
|
||||
<ol>
|
||||
<li> ‘<samp>'prop</samp>’: This extracts tags from the ‘<samp>#+roam_tags</samp>’ property. Tags are space delimited, and can be multi-word using double quotes.
|
||||
</li><li> ‘<samp>'all-directories</samp>’: All sub-directories relative to ‘<samp>org-roam-directory</samp>’ are
|
||||
<li> <code>'prop</code>: This extracts tags from the <code>#+roam_tags</code> property. Tags are space delimited, and can be multi-word using double quotes.
|
||||
</li><li> <code>'all-directories</code>: All sub-directories relative to <code>org-roam-directory</code> are
|
||||
extracted as tags. That is, if a file is located at relative path
|
||||
‘<samp>foo/bar/file.org</samp>’, the file will have tags ‘<samp>foo</samp>’ and ‘<samp>bar</samp>’.
|
||||
</li><li> ‘<samp>'last-directory</samp>’: Extracts the last directory relative to
|
||||
‘<samp>org-roam-directory</samp>’ as the tag. That is, if a file is located at relative
|
||||
path ‘<samp>foo/bar/file.org</samp>’, the file will have tag ‘<samp>bar</samp>’.
|
||||
</li><li> ‘<samp>'first-directory</samp>’: Extracts the first directory relative to
|
||||
‘<samp>org-roam-directory</samp>’ as the tag. That is, if a file is located at relative
|
||||
path ‘<samp>foo/bar/file.org</samp>’, the file will have tag ‘<samp>foo</samp>’.
|
||||
<code>foo/bar/file.org</code>, the file will have tags <code>foo</code> and <code>bar</code>.
|
||||
</li><li> <code>'last-directory</code>: Extracts the last directory relative to
|
||||
<code>org-roam-directory</code> as the tag. That is, if a file is located at relative
|
||||
path <code>foo/bar/file.org</code>, the file will have tag <code>bar</code>.
|
||||
</li><li> <code>'first-directory</code>: Extracts the first directory relative to
|
||||
<code>org-roam-directory</code> as the tag. That is, if a file is located at relative
|
||||
path <code>foo/bar/file.org</code>, the file will have tag <code>foo</code>.
|
||||
</li></ol>
|
||||
|
||||
<p>By default, only the ‘<samp>'prop</samp>’ extraction method is enabled. To enable the other
|
||||
extraction methods, you may modify ‘<samp>org-roam-tag-sources</samp>’:
|
||||
<p>By default, only the <code>'prop</code> extraction method is enabled. To enable the other
|
||||
extraction methods, you may modify <code>org-roam-tag-sources</code>:
|
||||
</p>
|
||||
<div class="lisp">
|
||||
<pre class="lisp">(setq org-roam-tag-sources '(prop last-directory))
|
||||
</pre></div>
|
||||
|
||||
<p>If you wish to add your own tag extraction method, you may push a symbol ‘<samp>'foo</samp>’
|
||||
into ‘<samp>org-roam-tag-sources</samp>’, and define a ‘<samp>org-roam--extract-tags-foo</samp>’ which
|
||||
<p>If you wish to add your own tag extraction method, you may push a symbol <code>'foo</code>
|
||||
into <code>org-roam-tag-sources</code>, and define a <code>org-roam--extract-tags-foo</code> which
|
||||
accepts the absolute file path as its argument. See
|
||||
‘<samp>org-roam--extract-tags-prop</samp>’ for an example.
|
||||
<code>org-roam--extract-tags-prop</code> for an example.
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
@@ -81,29 +81,29 @@ the default template, reproduced below.
|
||||
</pre></div>
|
||||
|
||||
<ol>
|
||||
<li> The template has short key ‘<samp>"d"</samp>’. If you have only one template,
|
||||
<li> The template has short key <code>"d"</code>. If you have only one template,
|
||||
org-roam automatically chooses this template for you.
|
||||
</li><li> The template is given a description of ‘<samp>"default"</samp>’.
|
||||
</li><li> ‘<samp>plain</samp>’ text is inserted. Other options include Org headings via
|
||||
‘<samp>entry</samp>’.
|
||||
</li><li> ‘<samp>(function org-roam--capture-get-point)</samp>’ should not be changed.
|
||||
</li><li> ‘<samp>"%?"</samp>’ is the template inserted on each call to ‘<samp>org-roam-capture--capture</samp>’.
|
||||
</li><li> The template is given a description of <code>"default"</code>.
|
||||
</li><li> <code>plain</code> text is inserted. Other options include Org headings via
|
||||
<code>entry</code>.
|
||||
</li><li> <code>(function org-roam--capture-get-point)</code> should not be changed.
|
||||
</li><li> <code>"%?"</code> is the template inserted on each call to <code>org-roam-capture--capture</code>.
|
||||
This template means don’t insert any content, but place the cursor
|
||||
here.
|
||||
</li><li> ‘<samp>:file-name</samp>’ is the file-name template for a new note, if it doesn’t yet
|
||||
</li><li> <code>:file-name</code> is the file-name template for a new note, if it doesn’t yet
|
||||
exist. This creates a file at path that looks like
|
||||
‘<samp>/path/to/org-roam-directory/20200213032037-foo.org</samp>’. This template also
|
||||
<code>/path/to/org-roam-directory/20200213032037-foo.org</code>. This template also
|
||||
allows you to specify if you want the note to go into a subdirectory. For
|
||||
example, the template ‘<samp>private/${slug}</samp>’ will create notes in
|
||||
‘<samp>/path/to/org-roam-directory/private</samp>’.
|
||||
</li><li> ‘<samp>:head</samp>’ contains the initial template to be inserted (once only), at
|
||||
example, the template <code>private/${slug}</code> will create notes in
|
||||
<code>/path/to/org-roam-directory/private</code>.
|
||||
</li><li> <code>:head</code> contains the initial template to be inserted (once only), at
|
||||
the beginning of the file. Here, the title global attribute is
|
||||
inserted.
|
||||
</li><li> ‘<samp>:unnarrowed t</samp>’ tells org-capture to show the contents for the whole
|
||||
</li><li> <code>:unnarrowed t</code> tells org-capture to show the contents for the whole
|
||||
file, rather than narrowing to just the entry.
|
||||
</li></ol>
|
||||
|
||||
<p>Other options you may want to learn about include ‘<samp>:immediate-finish</samp>’.
|
||||
<p>Other options you may want to learn about include <code>:immediate-finish</code>.
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
@@ -74,26 +74,26 @@ Next: <a href="Org_002droam-Links.html#Org_002droam-Links" accesskey="n" rel="ne
|
||||
<ul>
|
||||
<li> User Option: org-roam-buffer
|
||||
|
||||
<p>The name of the org-roam buffer. Defaults to ‘<samp>*org-roam*</samp>’.
|
||||
<p>The name of the org-roam buffer. Defaults to <code>*org-roam*</code>.
|
||||
</p>
|
||||
</li><li> User Option: org-roam-buffer-position
|
||||
|
||||
<p>The position of the Org-roam buffer side window. Valid values are ‘<samp>'left</samp>’,
|
||||
‘<samp>'right</samp>’, ‘<samp>'top</samp>’, ‘<samp>'bottom</samp>’.
|
||||
<p>The position of the Org-roam buffer side window. Valid values are <code>'left</code>,
|
||||
<code>'right</code>, <code>'top</code>, <code>'bottom</code>.
|
||||
</p>
|
||||
</li><li> User Option: org-roam-buffer-width
|
||||
|
||||
<p>Width of ‘<samp>org-roam-buffer</samp>’. Has an effect only if ‘<samp>org-roam-buffer-position</samp>’ is
|
||||
‘<samp>'left</samp>’ or ‘<samp>'right</samp>’.
|
||||
<p>Width of <code>org-roam-buffer</code>. Has an effect only if <code>org-roam-buffer-position</code> is
|
||||
<code>'left</code> or <code>'right</code>.
|
||||
</p>
|
||||
</li><li> User Option: org-roam-buffer-height
|
||||
|
||||
<p>Height of ‘<samp>org-roam-buffer</samp>’. Has an effect only if ‘<samp>org-roam-buffer-position</samp>’ is
|
||||
‘<samp>'top</samp>’ or ‘<samp>'bottom</samp>’.
|
||||
<p>Height of <code>org-roam-buffer</code>. Has an effect only if <code>org-roam-buffer-position</code> is
|
||||
<code>'top</code> or <code>'bottom</code>.
|
||||
</p>
|
||||
</li><li> User Option: org-roam-buffer-no-delete-other-windows
|
||||
|
||||
<p>The ‘<samp>no-delete-window</samp>’ parameter for the org-roam buffer. Setting it to ‘<samp>'t</samp>’ prevents the window from being deleted when calling ‘<samp>delete-other-windows</samp>’.
|
||||
<p>The <code>no-delete-window</code> parameter for the org-roam buffer. Setting it to <code>'t</code> prevents the window from being deleted when calling <code>delete-other-windows</code>.
|
||||
</p></li></ul>
|
||||
|
||||
|
||||
|
||||
@@ -25,7 +25,7 @@ General Public License for more details.
|
||||
<link href="index.html#Top" rel="start" title="Top">
|
||||
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
||||
<link href="Roam-Protocol.html#Roam-Protocol" rel="up" title="Roam Protocol">
|
||||
<link href="The-roam_002dref-Protocol.html#The-roam_002dref-Protocol" rel="next" title="The roam-ref Protocol">
|
||||
<link href="The-roam_002dref-protocol.html#The-roam_002dref-protocol" rel="next" title="The roam-ref protocol">
|
||||
<link href="Installation-_00281_0029.html#Installation-_00281_0029" rel="prev" title="Installation (1)">
|
||||
<style type="text/css">
|
||||
<!--
|
||||
@@ -63,14 +63,14 @@ ul.no-bullet {list-style: none}
|
||||
<a name="The-roam_002dfile-protocol"></a>
|
||||
<div class="header">
|
||||
<p>
|
||||
Next: <a href="The-roam_002dref-Protocol.html#The-roam_002dref-Protocol" accesskey="n" rel="next">The ‘<samp>roam-ref</samp>’ Protocol</a>, Previous: <a href="Installation-_00281_0029.html#Installation-_00281_0029" accesskey="p" rel="prev">Installation (1)</a>, Up: <a href="Roam-Protocol.html#Roam-Protocol" accesskey="u" rel="up">Roam Protocol</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
|
||||
Next: <a href="The-roam_002dref-protocol.html#The-roam_002dref-protocol" accesskey="n" rel="next">The roam-ref protocol</a>, Previous: <a href="Installation-_00281_0029.html#Installation-_00281_0029" accesskey="p" rel="prev">Installation (1)</a>, Up: <a href="Roam-Protocol.html#Roam-Protocol" accesskey="u" rel="up">Roam Protocol</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
|
||||
</div>
|
||||
<hr>
|
||||
<a name="The-roam_002dfile-protocol-1"></a>
|
||||
<h3 class="section">12.3 The ‘<samp>roam-file</samp>’ protocol</h3>
|
||||
<h3 class="section">12.3 The roam-file protocol</h3>
|
||||
|
||||
<p>This is a simple protocol that opens the path specified by the ‘<samp>file</samp>’
|
||||
key (e.g. ‘<samp>org-protocol://roam-file?file=/tmp/file.org</samp>’). This is used
|
||||
<p>This is a simple protocol that opens the path specified by the <code>file</code>
|
||||
key (e.g. <code>org-protocol://roam-file?file=/tmp/file.org</code>). This is used
|
||||
in the generated graph.
|
||||
</p>
|
||||
|
||||
|
||||
@@ -15,10 +15,10 @@ General Public License for more details.
|
||||
<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||||
<title>The roam-ref Protocol (Org-roam User Manual)</title>
|
||||
<title>The roam-ref protocol (Org-roam User Manual)</title>
|
||||
|
||||
<meta name="description" content="The roam-ref Protocol (Org-roam User Manual)">
|
||||
<meta name="keywords" content="The roam-ref Protocol (Org-roam User Manual)">
|
||||
<meta name="description" content="The roam-ref protocol (Org-roam User Manual)">
|
||||
<meta name="keywords" content="The roam-ref protocol (Org-roam User Manual)">
|
||||
<meta name="resource-type" content="document">
|
||||
<meta name="distribution" content="global">
|
||||
<meta name="Generator" content="makeinfo">
|
||||
@@ -60,14 +60,14 @@ ul.no-bullet {list-style: none}
|
||||
</head>
|
||||
|
||||
<body lang="en">
|
||||
<a name="The-roam_002dref-Protocol"></a>
|
||||
<a name="The-roam_002dref-protocol"></a>
|
||||
<div class="header">
|
||||
<p>
|
||||
Previous: <a href="The-roam_002dfile-protocol.html#The-roam_002dfile-protocol" accesskey="p" rel="prev">The ‘<samp>roam-file</samp>’ protocol</a>, Up: <a href="Roam-Protocol.html#Roam-Protocol" accesskey="u" rel="up">Roam Protocol</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
|
||||
Previous: <a href="The-roam_002dfile-protocol.html#The-roam_002dfile-protocol" accesskey="p" rel="prev">The roam-file protocol</a>, Up: <a href="Roam-Protocol.html#Roam-Protocol" accesskey="u" rel="up">Roam Protocol</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
|
||||
</div>
|
||||
<hr>
|
||||
<a name="The-roam_002dref-Protocol-1"></a>
|
||||
<h3 class="section">12.4 The ‘<samp>roam-ref</samp>’ Protocol</h3>
|
||||
<a name="The-roam_002dref-protocol-1"></a>
|
||||
<h3 class="section">12.4 The roam-ref protocol</h3>
|
||||
|
||||
<p>This protocol finds or creates a new note with a given <code>roam_key</code> (see <a href="Anatomy-of-an-Org_002droam-File.html#Anatomy-of-an-Org_002droam-File">Anatomy of an Org-roam File</a>):
|
||||
</p>
|
||||
@@ -75,14 +75,14 @@ especially useful for topics or concepts with acronyms. For example, for a note
|
||||
like “World War 2”, it may be desirable to also refer to it using the acronym
|
||||
“WWII”.
|
||||
</p>
|
||||
<p>Org-roam calls ‘<samp>org-roam--extract-titles</samp>’ to extract titles. It uses the
|
||||
variable ‘<samp>org-roam-title-sources</samp>’, to control how the titles are extracted. The
|
||||
<p>Org-roam calls <code>org-roam--extract-titles</code> to extract titles. It uses the
|
||||
variable <code>org-roam-title-sources</code>, to control how the titles are extracted. The
|
||||
title extraction methods supported are:
|
||||
</p>
|
||||
<ol>
|
||||
<li> ‘<samp>'title</samp>’: This extracts the title using the file ‘<samp>#+title</samp>’ property
|
||||
</li><li> ‘<samp>'headline</samp>’: This extracts the title from the first headline in the Org file
|
||||
</li><li> ‘<samp>'alias</samp>’: This extracts a list of titles using the ‘<samp>#+roam_alias</samp>’ property.
|
||||
<li> <code>'title</code>: This extracts the title using the file <code>#+title</code> property
|
||||
</li><li> <code>'headline</code>: This extracts the title from the first headline in the Org file
|
||||
</li><li> <code>'alias</code>: This extracts a list of titles using the <code>#+roam_alias</code> property.
|
||||
The aliases are space-delimited, and can be multi-worded using quotes
|
||||
</li></ol>
|
||||
|
||||
@@ -97,20 +97,20 @@ The aliases are space-delimited, and can be multi-worded using quotes
|
||||
|
||||
<table>
|
||||
<thead><tr><th>Method</th><th>Titles</th></tr></thead>
|
||||
<tr><td>‘<samp>'title</samp>’</td><td>’(“World War 2”)</td></tr>
|
||||
<tr><td>‘<samp>'headline</samp>’</td><td>’(“Headline”)</td></tr>
|
||||
<tr><td>‘<samp>'alias</samp>’</td><td>’(“WWII” “World War II”)</td></tr>
|
||||
<tr><td><code>'title</code></td><td>’(“World War 2”)</td></tr>
|
||||
<tr><td><code>'headline</code></td><td>’(“Headline”)</td></tr>
|
||||
<tr><td><code>'alias</code></td><td>’(“WWII” “World War II”)</td></tr>
|
||||
</table>
|
||||
|
||||
<p>One can freely control which extraction methods to use by customizing
|
||||
‘<samp>org-roam-title-sources</samp>’: see the doc-string for the variable for more
|
||||
<code>org-roam-title-sources</code>: see the doc-string for the variable for more
|
||||
information. If all methods of title extraction return no results, the file-name
|
||||
is used in place of the titles for completions.
|
||||
</p>
|
||||
<p>If you wish to add your own title extraction method, you may push a symbol
|
||||
‘<samp>'foo</samp>’ into ‘<samp>org-roam-title-sources</samp>’, and define a
|
||||
‘<samp>org-roam--extract-titles-foo</samp>’ which accepts no arguments. See
|
||||
‘<samp>org-roam--extract-titles-title</samp>’ for an example.
|
||||
<code>'foo</code> into <code>org-roam-title-sources</code>, and define a
|
||||
<code>org-roam--extract-titles-foo</code> which accepts no arguments. See
|
||||
<code>org-roam--extract-titles-title</code> for an example.
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
@@ -69,8 +69,8 @@ Next: <a href="Installation-_00281_0029.html#Installation-_00281_0029" accesskey
|
||||
<a name="g_t_005f-_003aignore_003a"></a>
|
||||
<h3 class="section">12.1 _ :ignore:</h3>
|
||||
|
||||
<p>Org-roam extending ‘<samp>org-protocol</samp>’ with 2 protocols: the ‘<samp>roam-file</samp>’
|
||||
and ‘<samp>roam-ref</samp>’ protocol.
|
||||
<p>Org-roam extending <code>org-protocol</code> with 2 protocols: the <code>roam-file</code>
|
||||
and <code>roam-ref</code> protocol.
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
@@ -112,8 +112,8 @@ ul.no-bullet {list-style: none}
|
||||
<ul class="no-bullet">
|
||||
<li><a name="toc-_005f-_003aignore_003a" href="_005f.html#g_t_005f">12.1 _ :ignore:</a></li>
|
||||
<li><a name="toc-Installation-2" href="Installation-_00281_0029.html#Installation-_00281_0029">12.2 Installation</a></li>
|
||||
<li><a name="toc-The-roam_002dfile-protocol-1" href="The-roam_002dfile-protocol.html#The-roam_002dfile-protocol">12.3 The ‘<samp>roam-file</samp>’ protocol</a></li>
|
||||
<li><a name="toc-The-roam_002dref-Protocol-1" href="The-roam_002dref-Protocol.html#The-roam_002dref-Protocol">12.4 The ‘<samp>roam-ref</samp>’ Protocol</a></li>
|
||||
<li><a name="toc-The-roam_002dfile-protocol-1" href="The-roam_002dfile-protocol.html#The-roam_002dfile-protocol">12.3 The roam-file protocol</a></li>
|
||||
<li><a name="toc-The-roam_002dref-protocol-1" href="The-roam_002dref-protocol.html#The-roam_002dref-protocol">12.4 The roam-ref protocol</a></li>
|
||||
</ul></li>
|
||||
<li><a name="toc-TODO-Daily-Notes" href="Daily-Notes.html#Daily-Notes">13 <strong>TODO</strong> Daily Notes</a></li>
|
||||
<li><a name="toc-Diagnosing-and-Repairing-Files-1" href="Diagnosing-and-Repairing-Files.html#Diagnosing-and-Repairing-Files">14 Diagnosing and Repairing Files</a></li>
|
||||
@@ -274,9 +274,9 @@ Roam Protocol
|
||||
</td></tr>
|
||||
<tr><td align="left" valign="top">• <a href="Installation-_00281_0029.html#Installation-_00281_0029">Installation</a>:</td><td> </td><td align="left" valign="top">
|
||||
</td></tr>
|
||||
<tr><td align="left" valign="top">• <a href="The-roam_002dfile-protocol.html#The-roam_002dfile-protocol">The ‘<samp>roam-file</samp>’ protocol</a>:</td><td> </td><td align="left" valign="top">
|
||||
<tr><td align="left" valign="top">• <a href="The-roam_002dfile-protocol.html#The-roam_002dfile-protocol">The roam-file protocol</a>:</td><td> </td><td align="left" valign="top">
|
||||
</td></tr>
|
||||
<tr><td align="left" valign="top">• <a href="The-roam_002dref-Protocol.html#The-roam_002dref-Protocol">The ‘<samp>roam-ref</samp>’ Protocol</a>:</td><td> </td><td align="left" valign="top">
|
||||
<tr><td align="left" valign="top">• <a href="The-roam_002dref-protocol.html#The-roam_002dref-protocol">The roam-ref protocol</a>:</td><td> </td><td align="left" valign="top">
|
||||
</td></tr>
|
||||
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
|
||||
|
||||
|
||||
286
org-roam.org
286
org-roam.org
@@ -185,9 +185,11 @@ workflows. Org-roam does not magically make note-taking better -- this often
|
||||
requires a radical change in your current note-taking workflow. To understand
|
||||
more about the methods and madness, see [[*Note-taking Workflows][Note-taking Workflows]].
|
||||
|
||||
To begin using Org-roam, one should set the =org-roam-directory= to the directory
|
||||
containing your notes. For this tutorial, create an empty directory, and set the
|
||||
=org-roam-directory=:
|
||||
To first start using Org-roam, one needs to pick a location to store the
|
||||
Org-roam files. The directory that will contain your notes, and database index
|
||||
is specified by the variable ~org-roam-directory~. This variable needs to be set
|
||||
before any calls to Org-roam functions, including enabling ~org-roam-mode~. For
|
||||
this tutorial, create an empty directory, and set ~org-roam-directory~:
|
||||
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
(make-directory "~/org-roam")
|
||||
@@ -196,34 +198,34 @@ containing your notes. For this tutorial, create an empty directory, and set the
|
||||
|
||||
We encourage using a flat hierarchy for storing notes, but some prefer using
|
||||
folders for storing specific kinds of notes (e.g. websites, papers). This is
|
||||
fine; Org-roam searches recursively within =org-roam-directory= for any notes.
|
||||
fine; Org-roam searches recursively within ~org-roam-directory~ for any notes.
|
||||
Instead of relying on the file hierarchy for any form of categorization, we
|
||||
solely rely on links between files to establish connections between notes.
|
||||
|
||||
Next, we need to enable the global minor mode =org-roam-mode=. This sets up Emacs
|
||||
Next, we need to enable the global minor mode ~org-roam-mode~. This sets up Emacs
|
||||
with several hooks, builds a cache and keeps it consistent. We recommend
|
||||
starting =org-roam-mode= on startup:
|
||||
starting ~org-roam-mode~ on startup:
|
||||
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
(add-hook 'after-init-hook 'org-roam-mode)
|
||||
#+END_SRC
|
||||
|
||||
To build the cache manually, one can run =M-x org-roam-db-build-cache=. The cache
|
||||
is a sqlite database named =org-roam.db=, which defaults to residing in the root
|
||||
=org-roam-directory=. Cache builds may take a while the first time, but is often
|
||||
instantaneous in subsequent runs.
|
||||
To build the cache manually, one can run ~M-x org-roam-db-build-cache~. The
|
||||
cache is a sqlite database named ~org-roam.db~, which defaults to residing in
|
||||
the root ~org-roam-directory~. Cache builds may take a while the first time, but
|
||||
is often instantaneous in subsequent runs.
|
||||
|
||||
Let us now create our first note. Call =M-x org-roam-find-file=. This shows a list
|
||||
of titles for notes that reside in =org-roam-directory=. It should show nothing
|
||||
Let us now create our first note. Call ~M-x org-roam-find-file~. This shows a list
|
||||
of titles for notes that reside in ~org-roam-directory~. It should show nothing
|
||||
right now, since there are no notes in the directory. Entering the title of the
|
||||
note you wish to create, and pressing =RET= should begin the note creation
|
||||
process. This process uses =org-capture='s templating system, and can be freely
|
||||
customized (see [[*The Templating System][The Templating System]]). Using the default template, pressing =C-c
|
||||
C-c= finishes the note capture. Running =M-x org-roam-find-file= again should show
|
||||
note you wish to create, and pressing ~RET~ should begin the note creation
|
||||
process. This process uses ~org-capture~'s templating system, and can be freely
|
||||
customized (see [[*The Templating System][The Templating System]]). Using the default template, pressing ~C-c
|
||||
C-c~ finishes the note capture. Running ~M-x org-roam-find-file~ again should show
|
||||
the note you have created, and selecting that entry will bring you to that note.
|
||||
|
||||
The crux of Org-roam is making it easy to create notes, and link them together.
|
||||
To link notes together, we call =M-x org-roam-insert=. This brings up a prompt
|
||||
To link notes together, we call ~M-x org-roam-insert~. This brings up a prompt
|
||||
with a list of title for existing notes. Selecting an existing entry will create
|
||||
and insert a link to the current file. Entering a non-existent title will create
|
||||
a new note with that title. Good usage of Org-roam requires liberally linking
|
||||
@@ -232,7 +234,7 @@ notes.
|
||||
|
||||
Org-roam provides an interface to view backlinks. It shows backlinks for the
|
||||
currently active Org-roam note, along with some surrounding context. To toggle
|
||||
the visibility of this buffer, call =M-x org-roam=.
|
||||
the visibility of this buffer, call ~M-x org-roam~.
|
||||
|
||||
For a visual representation of the notes and their connections, Org-roam also
|
||||
provides graphing capabilities, using Graphviz. It generates graphs with notes
|
||||
@@ -255,13 +257,13 @@ especially useful for topics or concepts with acronyms. For example, for a note
|
||||
like "World War 2", it may be desirable to also refer to it using the acronym
|
||||
"WWII".
|
||||
|
||||
Org-roam calls =org-roam--extract-titles= to extract titles. It uses the
|
||||
variable =org-roam-title-sources=, to control how the titles are extracted. The
|
||||
Org-roam calls ~org-roam--extract-titles~ to extract titles. It uses the
|
||||
variable ~org-roam-title-sources~, to control how the titles are extracted. The
|
||||
title extraction methods supported are:
|
||||
|
||||
1. ='title=: This extracts the title using the file =#+title= property
|
||||
2. ='headline=: This extracts the title from the first headline in the Org file
|
||||
3. ='alias=: This extracts a list of titles using the =#+roam_alias= property.
|
||||
1. ~'title~: This extracts the title using the file ~#+title~ property
|
||||
2. ~'headline~: This extracts the title from the first headline in the Org file
|
||||
3. ~'alias~: This extracts a list of titles using the ~#+roam_alias~ property.
|
||||
The aliases are space-delimited, and can be multi-worded using quotes
|
||||
|
||||
Take for example the following org file:
|
||||
@@ -275,19 +277,19 @@ Take for example the following org file:
|
||||
|
||||
| Method | Titles |
|
||||
|-------------+--------------------------|
|
||||
| ='title= | '("World War 2") |
|
||||
| ='headline= | '("Headline") |
|
||||
| ='alias= | '("WWII" "World War II") |
|
||||
| ~'title~ | '("World War 2") |
|
||||
| ~'headline~ | '("Headline") |
|
||||
| ~'alias~ | '("WWII" "World War II") |
|
||||
|
||||
One can freely control which extraction methods to use by customizing
|
||||
=org-roam-title-sources=: see the doc-string for the variable for more
|
||||
~org-roam-title-sources~: see the doc-string for the variable for more
|
||||
information. If all methods of title extraction return no results, the file-name
|
||||
is used in place of the titles for completions.
|
||||
|
||||
If you wish to add your own title extraction method, you may push a symbol
|
||||
='foo= into =org-roam-title-sources=, and define a
|
||||
=org-roam--extract-titles-foo= which accepts no arguments. See
|
||||
=org-roam--extract-titles-title= for an example.
|
||||
~'foo~ into ~org-roam-title-sources~, and define a
|
||||
~org-roam--extract-titles-foo~ which accepts no arguments. See
|
||||
~org-roam--extract-titles-title~ for an example.
|
||||
|
||||
** Tags
|
||||
|
||||
@@ -295,32 +297,32 @@ Tags are used as meta-data for files: they facilitate interactions with notes
|
||||
where titles are insufficient. For example, tags allow for categorization of
|
||||
notes: differentiating between bibliographical and structure notes during interactive commands.
|
||||
|
||||
Org-roam calls =org-roam--extract-tags= to extract tags from files. It uses the
|
||||
variable =org-roam-tag-sources=, to control how tags are extracted. The tag
|
||||
Org-roam calls ~org-roam--extract-tags~ to extract tags from files. It uses the
|
||||
variable ~org-roam-tag-sources~, to control how tags are extracted. The tag
|
||||
extraction methods supported are:
|
||||
|
||||
1. ='prop=: This extracts tags from the =#+roam_tags= property. Tags are space delimited, and can be multi-word using double quotes.
|
||||
2. ='all-directories=: All sub-directories relative to =org-roam-directory= are
|
||||
1. ~'prop~: This extracts tags from the ~#+roam_tags~ property. Tags are space delimited, and can be multi-word using double quotes.
|
||||
2. ~'all-directories~: All sub-directories relative to ~org-roam-directory~ are
|
||||
extracted as tags. That is, if a file is located at relative path
|
||||
=foo/bar/file.org=, the file will have tags =foo= and =bar=.
|
||||
3. ='last-directory=: Extracts the last directory relative to
|
||||
=org-roam-directory= as the tag. That is, if a file is located at relative
|
||||
path =foo/bar/file.org=, the file will have tag =bar=.
|
||||
4. ='first-directory=: Extracts the first directory relative to
|
||||
=org-roam-directory= as the tag. That is, if a file is located at relative
|
||||
path =foo/bar/file.org=, the file will have tag =foo=.
|
||||
~foo/bar/file.org~, the file will have tags ~foo~ and ~bar~.
|
||||
3. ~'last-directory~: Extracts the last directory relative to
|
||||
~org-roam-directory~ as the tag. That is, if a file is located at relative
|
||||
path ~foo/bar/file.org~, the file will have tag ~bar~.
|
||||
4. ~'first-directory~: Extracts the first directory relative to
|
||||
~org-roam-directory~ as the tag. That is, if a file is located at relative
|
||||
path ~foo/bar/file.org~, the file will have tag ~foo~.
|
||||
|
||||
By default, only the ='prop= extraction method is enabled. To enable the other
|
||||
extraction methods, you may modify =org-roam-tag-sources=:
|
||||
By default, only the ~'prop~ extraction method is enabled. To enable the other
|
||||
extraction methods, you may modify ~org-roam-tag-sources~:
|
||||
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
(setq org-roam-tag-sources '(prop last-directory))
|
||||
#+END_SRC
|
||||
|
||||
If you wish to add your own tag extraction method, you may push a symbol ='foo=
|
||||
into =org-roam-tag-sources=, and define a =org-roam--extract-tags-foo= which
|
||||
If you wish to add your own tag extraction method, you may push a symbol ~'foo~
|
||||
into ~org-roam-tag-sources~, and define a ~org-roam--extract-tags-foo~ which
|
||||
accepts the absolute file path as its argument. See
|
||||
=org-roam--extract-tags-prop= for an example.
|
||||
~org-roam--extract-tags-prop~ for an example.
|
||||
|
||||
** File Refs
|
||||
|
||||
@@ -333,7 +335,7 @@ For example, a note for a website may contain a ref:
|
||||
#+END_SRC
|
||||
|
||||
These keys come in useful for when taking website notes, using the
|
||||
=roam-ref= protocol (see [[*Roam Protocol][Roam Protocol]]).
|
||||
~roam-ref~ protocol (see [[*Roam Protocol][Roam Protocol]]).
|
||||
|
||||
Alternatively, add a ref for notes for a specific paper, using its
|
||||
[[https://github.com/jkitchin/org-ref][org-ref]] citation key:
|
||||
@@ -384,28 +386,28 @@ the default template, reproduced below.
|
||||
:unnarrowed t)
|
||||
#+END_SRC
|
||||
|
||||
1. The template has short key ="d"=. If you have only one template,
|
||||
1. The template has short key ~"d"~. If you have only one template,
|
||||
org-roam automatically chooses this template for you.
|
||||
2. The template is given a description of ="default"=.
|
||||
3. =plain= text is inserted. Other options include Org headings via
|
||||
=entry=.
|
||||
4. =(function org-roam--capture-get-point)= should not be changed.
|
||||
5. ="%?"= is the template inserted on each call to =org-roam-capture--capture=.
|
||||
2. The template is given a description of ~"default"~.
|
||||
3. ~plain~ text is inserted. Other options include Org headings via
|
||||
~entry~.
|
||||
4. ~(function org-roam--capture-get-point)~ should not be changed.
|
||||
5. ~"%?"~ is the template inserted on each call to ~org-roam-capture--capture~.
|
||||
This template means don't insert any content, but place the cursor
|
||||
here.
|
||||
6. =:file-name= is the file-name template for a new note, if it doesn't yet
|
||||
6. ~:file-name~ is the file-name template for a new note, if it doesn't yet
|
||||
exist. This creates a file at path that looks like
|
||||
=/path/to/org-roam-directory/20200213032037-foo.org=. This template also
|
||||
~/path/to/org-roam-directory/20200213032037-foo.org~. This template also
|
||||
allows you to specify if you want the note to go into a subdirectory. For
|
||||
example, the template =private/${slug}= will create notes in
|
||||
=/path/to/org-roam-directory/private=.
|
||||
7. =:head= contains the initial template to be inserted (once only), at
|
||||
example, the template ~private/${slug}~ will create notes in
|
||||
~/path/to/org-roam-directory/private~.
|
||||
7. ~:head~ contains the initial template to be inserted (once only), at
|
||||
the beginning of the file. Here, the title global attribute is
|
||||
inserted.
|
||||
8. =:unnarrowed t= tells org-capture to show the contents for the whole
|
||||
8. ~:unnarrowed t~ tells org-capture to show the contents for the whole
|
||||
file, rather than narrowing to just the entry.
|
||||
|
||||
Other options you may want to learn about include =:immediate-finish=.
|
||||
Other options you may want to learn about include ~:immediate-finish~.
|
||||
|
||||
** Org-roam Template Expansion
|
||||
|
||||
@@ -413,26 +415,26 @@ Org-roam's template definitions also extend org-capture's template syntax, to
|
||||
allow prefilling of strings. We have seen a glimpse of this in [[*Template Walkthrough][Template
|
||||
Walkthrough]].
|
||||
|
||||
In org-roam templates, the =${var}= syntax allows for the expansion of
|
||||
variables, stored in =org-roam-capture--info=. For example, during
|
||||
=org-roam-insert=, the user is prompted for a title. Upon entering a
|
||||
non-existent title, the =title= key in =org-roam-capture--info= is set to the
|
||||
provided title. =${title}= is then expanded into the provided title during the
|
||||
In org-roam templates, the ~${var}~ syntax allows for the expansion of
|
||||
variables, stored in ~org-roam-capture--info~. For example, during
|
||||
~org-roam-insert~, the user is prompted for a title. Upon entering a
|
||||
non-existent title, the ~title~ key in ~org-roam-capture--info~ is set to the
|
||||
provided title. ~${title}~ is then expanded into the provided title during the
|
||||
org-capture process. Any variables that do not contain strings, are prompted for
|
||||
values using =completing-read=.
|
||||
values using ~completing-read~.
|
||||
|
||||
After doing this expansion, the org-capture's template expansion system
|
||||
is used to fill up the rest of the template. You may read up more on
|
||||
this on [[https://orgmode.org/manual/Template-expansion.html#Template-expansion][org-capture's documentation page]].
|
||||
|
||||
To illustrate this dual expansion process, take for example the template string:
|
||||
="%<%Y%m%d%H%M%S>-${title}"=, with the title ="Foo"=. The template is first
|
||||
expanded into =%<%Y%m%d%H%M%S>-Foo=. Then org-capture expands =%<%Y%m%d%H%M%S>=
|
||||
with timestamp: e.g. =20200213032037-Foo=.
|
||||
~"%<%Y%m%d%H%M%S>-${title}"~, with the title ~"Foo"~. The template is first
|
||||
expanded into ~%<%Y%m%d%H%M%S>-Foo~. Then org-capture expands ~%<%Y%m%d%H%M%S>~
|
||||
with timestamp: e.g. ~20200213032037-Foo~.
|
||||
|
||||
All of the flexibility afforded by Emacs and Org-mode are available. For
|
||||
example, if you want to encode a UTC timestamp in the filename, you can take
|
||||
advantage of org-mode's =%(EXP)= template expansion to call =format-time-string=
|
||||
advantage of org-mode's ~%(EXP)~ template expansion to call ~format-time-string~
|
||||
directly to provide its third argument to specify UTC.
|
||||
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
@@ -449,7 +451,7 @@ the Org-roam codebase manageable. However, we attempt to accommodate as
|
||||
many usage styles as possible.
|
||||
|
||||
All of Org-roam's customization options can be viewed via
|
||||
=M-x customize-group org-roam=.
|
||||
~M-x customize-group org-roam~.
|
||||
|
||||
** Directories and Files
|
||||
|
||||
@@ -474,39 +476,39 @@ The Org-roam buffer displays backlinks for the currently active Org-roam note.
|
||||
|
||||
- User Option: org-roam-buffer
|
||||
|
||||
The name of the org-roam buffer. Defaults to =*org-roam*=.
|
||||
The name of the org-roam buffer. Defaults to ~*org-roam*~.
|
||||
|
||||
- User Option: org-roam-buffer-position
|
||||
|
||||
The position of the Org-roam buffer side window. Valid values are ='left=,
|
||||
='right=, ='top=, ='bottom=.
|
||||
The position of the Org-roam buffer side window. Valid values are ~'left~,
|
||||
~'right~, ~'top~, ~'bottom~.
|
||||
|
||||
- User Option: org-roam-buffer-width
|
||||
|
||||
Width of =org-roam-buffer=. Has an effect only if =org-roam-buffer-position= is
|
||||
='left= or ='right=.
|
||||
Width of ~org-roam-buffer~. Has an effect only if ~org-roam-buffer-position~ is
|
||||
~'left~ or ~'right~.
|
||||
|
||||
- User Option: org-roam-buffer-height
|
||||
|
||||
Height of =org-roam-buffer=. Has an effect only if =org-roam-buffer-position= is
|
||||
='top= or ='bottom=.
|
||||
Height of ~org-roam-buffer~. Has an effect only if ~org-roam-buffer-position~ is
|
||||
~'top~ or ~'bottom~.
|
||||
|
||||
- User Option: org-roam-buffer-no-delete-other-windows
|
||||
|
||||
The =no-delete-window= parameter for the org-roam buffer. Setting it to ='t= prevents the window from being deleted when calling =delete-other-windows=.
|
||||
The ~no-delete-window~ parameter for the org-roam buffer. Setting it to ~'t~ prevents the window from being deleted when calling ~delete-other-windows~.
|
||||
|
||||
** Org-roam Links
|
||||
|
||||
Org-roam links are regular =file:= links in Org-mode. By default, links are
|
||||
inserted with the title as the link description with =org-roam-insert=.
|
||||
Org-roam links are regular ~file:~ links in Org-mode. By default, links are
|
||||
inserted with the title as the link description with ~org-roam-insert~.
|
||||
|
||||
- User Option: org-roam-link-title-format
|
||||
|
||||
To distinguish between org-roam links and regular links, one may choose to use
|
||||
special indicators for Org-roam links. Defaults to ="%s"=.
|
||||
special indicators for Org-roam links. Defaults to ~"%s"~.
|
||||
|
||||
If your version of Org is at least =9.2=, consider styling the link differently,
|
||||
by customizing the =org-roam-link=, and =org-roam-link-current= faces.
|
||||
If your version of Org is at least ~9.2~, consider styling the link differently,
|
||||
by customizing the ~org-roam-link~, and ~org-roam-link-current~ faces.
|
||||
|
||||
** Org-roam Files
|
||||
|
||||
@@ -521,27 +523,27 @@ As your collection grows, you might want to create an index where you keep links
|
||||
to your main files.
|
||||
|
||||
In Org-roam, you can define the path to your index file by setting
|
||||
=org-roam-index-file=.
|
||||
~org-roam-index-file~.
|
||||
|
||||
- Variable: org-roam-index-file
|
||||
|
||||
Path to the Org-roam index file.
|
||||
|
||||
The path can be a string or a function. If it is a string, it should be the
|
||||
path (absolute or relative to =org-roam-directory=) to the index file. If it
|
||||
path (absolute or relative to ~org-roam-directory~) to the index file. If it
|
||||
is is a function, the function should return the path to the index file.
|
||||
Otherwise, the index is assumed to be a note in =org-roam-index= whose
|
||||
title is ="Index"=.
|
||||
Otherwise, the index is assumed to be a note in ~org-roam-index~ whose
|
||||
title is ~"Index"~.
|
||||
|
||||
- Function: org-roam-find-index
|
||||
|
||||
Opens the Index file in the current =org-roam-directory=.
|
||||
Opens the Index file in the current ~org-roam-directory~.
|
||||
|
||||
* Encryption
|
||||
|
||||
One may wish to keep private, encrypted files. Org-roam supports encryption (via
|
||||
GPG), which can be enabled for all new files by setting =org-roam-encrypt-files=
|
||||
to =t=. When enabled, new files are created with the =.org.gpg= extension and
|
||||
GPG), which can be enabled for all new files by setting ~org-roam-encrypt-files~
|
||||
to ~t~. When enabled, new files are created with the ~.org.gpg~ extension and
|
||||
decryption are handled automatically by EasyPG.
|
||||
|
||||
Note that Emacs will prompt for a password for encrypted files during
|
||||
@@ -557,7 +559,7 @@ Org-roam provides graphing capabilities to explore interconnections between
|
||||
notes. This is done by performing SQL queries and generating images using
|
||||
[[https://graphviz.org/][Graphviz]]. The graph can also be navigated: see [[*Roam Protocol][Roam Protocol]].
|
||||
|
||||
The entry point to graph creation is =org-roam-graph=.
|
||||
The entry point to graph creation is ~org-roam-graph~.
|
||||
|
||||
- Function: org-roam-graph & optional arg file node-query
|
||||
|
||||
@@ -565,18 +567,18 @@ The entry point to graph creation is =org-roam-graph=.
|
||||
If FILE is nil, default to current buffer’s file name.
|
||||
ARG may be any of the following values:
|
||||
|
||||
- =nil= show the graph.
|
||||
- =C-u= show the graph for FILE.
|
||||
- =C-u N= show the graph for FILE limiting nodes to N steps.
|
||||
- =C-u C-u= build the graph.
|
||||
- =C-u -= build the graph for FILE.
|
||||
- =C-u -N= build the graph for FILE limiting nodes to N steps.
|
||||
- ~nil~ show the graph.
|
||||
- ~C-u~ show the graph for FILE.
|
||||
- ~C-u N~ show the graph for FILE limiting nodes to N steps.
|
||||
- ~C-u C-u~ build the graph.
|
||||
- ~C-u -~ build the graph for FILE.
|
||||
- ~C-u -N~ build the graph for FILE limiting nodes to N steps.
|
||||
|
||||
- User Option: org-roam-graph-executable
|
||||
|
||||
Path to the graphing executable (in this case, Graphviz). Set this if Org-roam is unable to find the Graphviz executable on your system.
|
||||
|
||||
You may also choose to use =neato= in place of =dot=, which generates a more
|
||||
You may also choose to use ~neato~ in place of ~dot~, which generates a more
|
||||
compact graph layout.
|
||||
|
||||
- User Option: org-roam-graph-viewer
|
||||
@@ -586,7 +588,7 @@ The entry point to graph creation is =org-roam-graph=.
|
||||
1. A string, which is a path to the program used
|
||||
2. a function accepting a single argument: the graph file path.
|
||||
|
||||
=nil= uses =view-file= to view the graph.
|
||||
~nil~ uses ~view-file~ to view the graph.
|
||||
|
||||
If you are using WSL2 and would like to open the graph in Windows, you can use the second option to set the browser and network file path:
|
||||
|
||||
@@ -604,22 +606,22 @@ Graphviz provides many options for customizing the graph output, and Org-roam su
|
||||
- User Option: org-roam-graph-extra-config
|
||||
|
||||
Extra options passed to graphviz for the digraph (The "G" attributes).
|
||||
Example: ='=(("rankdir" . "LR"))=
|
||||
Example: ~'~(("rankdir" . "LR"))~
|
||||
|
||||
- User Option: org-roam-graph-node-extra-config
|
||||
|
||||
Extra options for nodes in the graphviz output (The "N" attributes).
|
||||
Example: ='(("color" . "skyblue"))=
|
||||
Example: ~'(("color" . "skyblue"))~
|
||||
|
||||
- User Option: org-roam-graph-edge-extra-config
|
||||
|
||||
Extra options for edges in the graphviz output (The "E" attributes).
|
||||
Example: ='(("dir" . "back"))=
|
||||
Example: ~'(("dir" . "back"))~
|
||||
|
||||
- User Option: org-roam-graph-edge-cites-extra-config
|
||||
|
||||
Extra options for citation edges in the graphviz output.
|
||||
Example: ='(("color" . "red"))=
|
||||
Example: ~'(("color" . "red"))~
|
||||
|
||||
** Excluding Nodes and Edges
|
||||
|
||||
@@ -650,19 +652,19 @@ system is configurable. The default setting,
|
||||
(setq org-roam-completion-system 'default)
|
||||
#+END_SRC
|
||||
|
||||
uses Emacs' standard =completing-read=. If you prefer
|
||||
uses Emacs' standard ~completing-read~. If you prefer
|
||||
[[https://emacs-helm.github.io/helm/][Helm]], use
|
||||
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
(setq org-roam-completion-system 'helm)
|
||||
#+END_SRC
|
||||
|
||||
Other options include ='ido=, and ='ivy=.
|
||||
Other options include ~'ido~, and ~'ivy~.
|
||||
|
||||
* Roam Protocol
|
||||
** _ :ignore:
|
||||
Org-roam extending =org-protocol= with 2 protocols: the =roam-file=
|
||||
and =roam-ref= protocol.
|
||||
Org-roam extending ~org-protocol~ with 2 protocols: the ~roam-file~
|
||||
and ~roam-ref~ protocol.
|
||||
|
||||
** Installation
|
||||
|
||||
@@ -672,12 +674,12 @@ To enable Org-roam's protocol extensions, you have to add the following to your
|
||||
(require 'org-roam-protocol)
|
||||
#+END_SRC
|
||||
|
||||
The instructions for setting up =org-protocol== are reproduced below.
|
||||
The instructions for setting up ~org-protocol~ are reproduced below.
|
||||
|
||||
We will also need to create a desktop application for =emacsclient=. The
|
||||
We will also need to create a desktop application for ~emacsclient~. The
|
||||
instructions for various platforms are shown below.
|
||||
|
||||
For Linux users, create a desktop application in =~/.local/share/applications/org-protocol.desktop=:
|
||||
For Linux users, create a desktop application in ~~/.local/share/applications/org-protocol.desktop~:
|
||||
|
||||
#+begin_example
|
||||
[Desktop Entry]
|
||||
@@ -689,7 +691,7 @@ Terminal=false
|
||||
MimeType=x-scheme-handler/org-protocol
|
||||
#+end_example
|
||||
|
||||
Associate =org-protocol://= links with the desktop application by
|
||||
Associate ~org-protocol://~ links with the desktop application by
|
||||
running in your shell:
|
||||
|
||||
#+BEGIN_SRC bash
|
||||
@@ -697,7 +699,7 @@ xdg-mime default org-protocol.desktop x-scheme-handler/org-protocol
|
||||
#+END_SRC
|
||||
|
||||
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
|
||||
show a checkbox to tick, so that the ~Org-Protocol Client~ app will be used
|
||||
without confirmation. To do this, run in a shell:
|
||||
|
||||
#+BEGIN_SRC bash
|
||||
@@ -713,8 +715,8 @@ 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 [[https://www.chromium.org/administrators/linux-quick-start][here]] for more info on the =/etc/opt/chrome/policies/managed= directory and
|
||||
[[https://cloud.google.com/docs/chrome-enterprise/policies/?policy=ExternalProtocolDialogShowAlwaysOpenCheckbox][here]] for information on the =ExternalProtocolDialogShowAlwaysOpenCheckbox= policy.
|
||||
See [[https://www.chromium.org/administrators/linux-quick-start][here]] for more info on the ~/etc/opt/chrome/policies/managed~ directory and
|
||||
[[https://cloud.google.com/docs/chrome-enterprise/policies/?policy=ExternalProtocolDialogShowAlwaysOpenCheckbox][here]] for information on the ~ExternalProtocolDialogShowAlwaysOpenCheckbox~ policy.
|
||||
|
||||
For MacOS, one solution is to use [[https://github.com/sveinbjornt/Platypus][Platypus]]. Here are the instructions for
|
||||
setting up with Platypus and Chrome:
|
||||
@@ -725,7 +727,7 @@ setting up with Platypus and Chrome:
|
||||
brew cask install platypus
|
||||
#+END_SRC
|
||||
|
||||
2. Create a script =launch_emacs.sh=:
|
||||
2. Create a script ~launch_emacs.sh~:
|
||||
|
||||
#+BEGIN_SRC bash
|
||||
#!/usr/bin/env bash
|
||||
@@ -746,7 +748,7 @@ brew cask install platypus
|
||||
#+end_example
|
||||
|
||||
|
||||
Inside =Settings=:
|
||||
Inside ~Settings~:
|
||||
|
||||
#+begin_example
|
||||
| Setting | Value |
|
||||
@@ -757,7 +759,7 @@ Inside =Settings=:
|
||||
#+end_example
|
||||
|
||||
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
|
||||
show a checkbox to tick, so that the ~OrgProtocol~ app will be used
|
||||
without confirmation. To do this, run in a shell:
|
||||
|
||||
#+BEGIN_SRC bash
|
||||
@@ -766,7 +768,7 @@ defaults write com.google.Chrome ExternalProtocolDialogShowAlwaysOpenCheckbox -b
|
||||
|
||||
|
||||
If you're using [[https://github.com/railwaycat/homebrew-emacsmacport][Emacs Mac Port]], it registered its `Emacs.app` as the default
|
||||
handler for the URL scheme `org-protocol`. To make =OrgProtocol.app=
|
||||
handler for the URL scheme `org-protocol`. To make ~OrgProtocol.app~
|
||||
the default handler instead, run:
|
||||
|
||||
#+BEGIN_SRC bash
|
||||
@@ -776,7 +778,7 @@ defaults write com.apple.LaunchServices/com.apple.launchservices.secure LSHandle
|
||||
|
||||
Then restart your computer.
|
||||
|
||||
For Windows, create a temporary =org-protocol.reg= file:
|
||||
For Windows, create a temporary ~org-protocol.reg~ file:
|
||||
|
||||
#+BEGIN_SRC text
|
||||
REGEDIT4
|
||||
@@ -798,13 +800,13 @@ The above will forward the protocol to WSL. If you run Emacs natively on Windows
|
||||
|
||||
After executing the .reg file, the protocol is registered and you can delete the file.
|
||||
|
||||
** The =roam-file= 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
|
||||
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
|
||||
** The roam-ref protocol
|
||||
|
||||
This protocol finds or creates a new note with a given ~roam_key~ (see [[*Anatomy of an Org-roam File][Anatomy of an Org-roam File]]):
|
||||
|
||||
@@ -837,15 +839,15 @@ should contain a ~#+roam_key: ${ref}~ in it.
|
||||
|
||||
Org-roam provides a utility for diagnosing and repairing problematic files via
|
||||
~org-roam-doctor~. By default, ~org-roam-doctor~ runs the check on the current
|
||||
Org-roam file. To run the check only for the current file, run =C-u M-x
|
||||
org-roam-doctor=, but note that this may take some time.
|
||||
Org-roam file. To run the check only for the current file, run ~C-u M-x
|
||||
org-roam-doctor~, but note that this may take some time.
|
||||
|
||||
- Function: org-roam-doctor &optional this-buffer
|
||||
|
||||
Perform a check on Org-roam files to ensure cleanliness. If THIS-BUFFER, run
|
||||
the check only for the current buffer.
|
||||
|
||||
The checks run are defined in =org-roam-doctor--checkers=. Each checker is an instance of =org-roam-doctor-checker=. To define a checker, use =make-org-roam-doctor-checker=. Here is a sample definition:
|
||||
The checks run are defined in ~org-roam-doctor--checkers~. Each checker is an instance of ~org-roam-doctor-checker~. To define a checker, use ~make-org-roam-doctor-checker~. Here is a sample definition:
|
||||
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
(make-org-roam-doctor-checker
|
||||
@@ -856,14 +858,14 @@ The checks run are defined in =org-roam-doctor--checkers=. Each checker is an in
|
||||
("R" . ("Replace link (keep label)" . org-roam-doctor--replace-link-keep-label))))
|
||||
#+END_SRC
|
||||
|
||||
The =:name= property is the name of the function run. The function takes in the
|
||||
Org parse tree, and returns a list of =(point error-message)=. =:description= is a
|
||||
short description of what the checker does. =:actions= is an alist containing
|
||||
elements of the form =(char . (prompt . function))=. These actions are defined per
|
||||
The ~:name~ property is the name of the function run. The function takes in the
|
||||
Org parse tree, and returns a list of ~(point error-message)~. ~:description~ is a
|
||||
short description of what the checker does. ~:actions~ is an alist containing
|
||||
elements of the form ~(char . (prompt . function))~. These actions are defined per
|
||||
checker, to perform autofixes for the errors. For each error detected,
|
||||
=org-roam-doctor= will move the point to the current error, and pop-up a help
|
||||
~org-roam-doctor~ will move the point to the current error, and pop-up a help
|
||||
window displaying the error message, as well as the list of actions that can be
|
||||
taken provided in =:actions=.
|
||||
taken provided in ~:actions~.
|
||||
* Performance Optimization
|
||||
** TODO Profiling Key Operations
|
||||
** Garbage Collection
|
||||
@@ -949,7 +951,7 @@ for browsing and filtering org-roam notes.
|
||||
#+END_SRC
|
||||
|
||||
If the title of the Org file is not the first line, you might not get
|
||||
nice titles. You may choose to patch this to use =org-roam='s
|
||||
nice titles. You may choose to patch this to use ~org-roam~'s
|
||||
functionality. Here I'm using
|
||||
[[https://github.com/raxod502/el-patch][el-patch]]:
|
||||
|
||||
@@ -989,7 +991,7 @@ that uses an external search engine and indexer.
|
||||
:END:
|
||||
|
||||
[[https://github.com/bastibe/org-journal][Org-journal]] is a more
|
||||
powerful alternative to the simple function =org-roam-dailies-today=. It
|
||||
powerful alternative to the simple function ~org-roam-dailies-today~. It
|
||||
provides better journaling capabilities, and a nice calendar interface
|
||||
to see all dated entries.
|
||||
|
||||
@@ -1068,8 +1070,8 @@ etc.) within Org-mode.
|
||||
tight integration between
|
||||
[[https://github.com/jkitchin/org-ref][org-ref]],
|
||||
[[https://github.com/tmalsburg/helm-bibtex][helm-bibtex]] and
|
||||
=org-roam=. This helps you manage your bibliographic notes under
|
||||
=org-roam=.
|
||||
~org-roam~. This helps you manage your bibliographic notes under
|
||||
~org-roam~.
|
||||
|
||||
**** Spaced Repetition
|
||||
:PROPERTIES:
|
||||
@@ -1083,11 +1085,11 @@ files. Other alternatives include [[https://orgmode.org/worg/org-contrib/org-dri
|
||||
** How do I have more than one Org-roam directory?
|
||||
|
||||
Emacs supports directory-local variables, allowing the value of
|
||||
=org-roam-directory= to be different in different directories. It does this by
|
||||
checking for a file named =.dir-locals.el=.
|
||||
~org-roam-directory~ to be different in different directories. It does this by
|
||||
checking for a file named ~.dir-locals.el~.
|
||||
|
||||
To add support for multiple directories, override the =org-roam-directory=
|
||||
variable using directory-local variables. This is what =.dir-locals.el= may
|
||||
To add support for multiple directories, override the ~org-roam-directory~
|
||||
variable using directory-local variables. This is what ~.dir-locals.el~ may
|
||||
contain:
|
||||
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
@@ -1095,7 +1097,7 @@ contain:
|
||||
#+END_SRC
|
||||
|
||||
All files within that directory will be treated as their own separate
|
||||
set of Org-roam files. Remember to run =org-roam-db-build-cache= from a
|
||||
set of Org-roam files. Remember to run ~org-roam-db-build-cache~ from a
|
||||
file within that directory, at least once.
|
||||
|
||||
** How do I migrate from Roam Research?
|
||||
|
||||
296
org-roam.texi
296
org-roam.texi
@@ -122,8 +122,8 @@ Roam Protocol
|
||||
|
||||
* _::
|
||||
* Installation: Installation (1).
|
||||
* The @samp{roam-file} protocol::
|
||||
* The @samp{roam-ref} Protocol::
|
||||
* The roam-file protocol::
|
||||
* The roam-ref protocol::
|
||||
|
||||
Performance Optimization
|
||||
|
||||
@@ -331,9 +331,11 @@ workflows. Org-roam does not magically make note-taking better -- this often
|
||||
requires a radical change in your current note-taking workflow. To understand
|
||||
more about the methods and madness, see @ref{Note-taking Workflows}.
|
||||
|
||||
To begin using Org-roam, one should set the @samp{org-roam-directory} to the directory
|
||||
containing your notes. For this tutorial, create an empty directory, and set the
|
||||
@samp{org-roam-directory}:
|
||||
To first start using Org-roam, one needs to pick a location to store the
|
||||
Org-roam files. The directory that will contain your notes, and database index
|
||||
is specified by the variable @code{org-roam-directory}. This variable needs to be set
|
||||
before any calls to Org-roam functions, including enabling @code{org-roam-mode}. For
|
||||
this tutorial, create an empty directory, and set @code{org-roam-directory}:
|
||||
|
||||
@lisp
|
||||
(make-directory "~/org-roam")
|
||||
@@ -342,34 +344,34 @@ containing your notes. For this tutorial, create an empty directory, and set the
|
||||
|
||||
We encourage using a flat hierarchy for storing notes, but some prefer using
|
||||
folders for storing specific kinds of notes (e.g. websites, papers). This is
|
||||
fine; Org-roam searches recursively within @samp{org-roam-directory} for any notes.
|
||||
fine; Org-roam searches recursively within @code{org-roam-directory} for any notes.
|
||||
Instead of relying on the file hierarchy for any form of categorization, we
|
||||
solely rely on links between files to establish connections between notes.
|
||||
|
||||
Next, we need to enable the global minor mode @samp{org-roam-mode}. This sets up Emacs
|
||||
Next, we need to enable the global minor mode @code{org-roam-mode}. This sets up Emacs
|
||||
with several hooks, builds a cache and keeps it consistent. We recommend
|
||||
starting @samp{org-roam-mode} on startup:
|
||||
starting @code{org-roam-mode} on startup:
|
||||
|
||||
@lisp
|
||||
(add-hook 'after-init-hook 'org-roam-mode)
|
||||
@end lisp
|
||||
|
||||
To build the cache manually, one can run @samp{M-x org-roam-db-build-cache}. The cache
|
||||
is a sqlite database named @samp{org-roam.db}, which defaults to residing in the root
|
||||
@samp{org-roam-directory}. Cache builds may take a while the first time, but is often
|
||||
instantaneous in subsequent runs.
|
||||
To build the cache manually, one can run @code{M-x org-roam-db-build-cache}. The
|
||||
cache is a sqlite database named @code{org-roam.db}, which defaults to residing in
|
||||
the root @code{org-roam-directory}. Cache builds may take a while the first time, but
|
||||
is often instantaneous in subsequent runs.
|
||||
|
||||
Let us now create our first note. Call @samp{M-x org-roam-find-file}. This shows a list
|
||||
of titles for notes that reside in @samp{org-roam-directory}. It should show nothing
|
||||
Let us now create our first note. Call @code{M-x org-roam-find-file}. This shows a list
|
||||
of titles for notes that reside in @code{org-roam-directory}. It should show nothing
|
||||
right now, since there are no notes in the directory. Entering the title of the
|
||||
note you wish to create, and pressing @samp{RET} should begin the note creation
|
||||
process. This process uses @samp{org-capture}'s templating system, and can be freely
|
||||
customized (see @ref{The Templating System}). Using the default template, pressing @samp{C-c
|
||||
C-c} finishes the note capture. Running @samp{M-x org-roam-find-file} again should show
|
||||
note you wish to create, and pressing @code{RET} should begin the note creation
|
||||
process. This process uses @code{org-capture}'s templating system, and can be freely
|
||||
customized (see @ref{The Templating System}). Using the default template, pressing @code{C-c
|
||||
C-c} finishes the note capture. Running @code{M-x org-roam-find-file} again should show
|
||||
the note you have created, and selecting that entry will bring you to that note.
|
||||
|
||||
The crux of Org-roam is making it easy to create notes, and link them together.
|
||||
To link notes together, we call @samp{M-x org-roam-insert}. This brings up a prompt
|
||||
To link notes together, we call @code{M-x org-roam-insert}. This brings up a prompt
|
||||
with a list of title for existing notes. Selecting an existing entry will create
|
||||
and insert a link to the current file. Entering a non-existent title will create
|
||||
a new note with that title. Good usage of Org-roam requires liberally linking
|
||||
@@ -378,7 +380,7 @@ notes.
|
||||
|
||||
Org-roam provides an interface to view backlinks. It shows backlinks for the
|
||||
currently active Org-roam note, along with some surrounding context. To toggle
|
||||
the visibility of this buffer, call @samp{M-x org-roam}.
|
||||
the visibility of this buffer, call @code{M-x org-roam}.
|
||||
|
||||
For a visual representation of the notes and their connections, Org-roam also
|
||||
provides graphing capabilities, using Graphviz. It generates graphs with notes
|
||||
@@ -409,17 +411,17 @@ especially useful for topics or concepts with acronyms. For example, for a note
|
||||
like ``World War 2'', it may be desirable to also refer to it using the acronym
|
||||
``WWII''.
|
||||
|
||||
Org-roam calls @samp{org-roam--extract-titles} to extract titles. It uses the
|
||||
variable @samp{org-roam-title-sources}, to control how the titles are extracted. The
|
||||
Org-roam calls @code{org-roam--extract-titles} to extract titles. It uses the
|
||||
variable @code{org-roam-title-sources}, to control how the titles are extracted. The
|
||||
title extraction methods supported are:
|
||||
|
||||
@enumerate
|
||||
@item
|
||||
@samp{'title}: This extracts the title using the file @samp{#+title} property
|
||||
@code{'title}: This extracts the title using the file @code{#+title} property
|
||||
@item
|
||||
@samp{'headline}: This extracts the title from the first headline in the Org file
|
||||
@code{'headline}: This extracts the title from the first headline in the Org file
|
||||
@item
|
||||
@samp{'alias}: This extracts a list of titles using the @samp{#+roam_alias} property.
|
||||
@code{'alias}: This extracts a list of titles using the @code{#+roam_alias} property.
|
||||
The aliases are space-delimited, and can be multi-worded using quotes
|
||||
@end enumerate
|
||||
|
||||
@@ -435,23 +437,23 @@ Take for example the following org file:
|
||||
@multitable {aaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaa}
|
||||
@headitem Method
|
||||
@tab Titles
|
||||
@item @samp{'title}
|
||||
@item @code{'title}
|
||||
@tab '(``World War 2'')
|
||||
@item @samp{'headline}
|
||||
@item @code{'headline}
|
||||
@tab '(``Headline'')
|
||||
@item @samp{'alias}
|
||||
@item @code{'alias}
|
||||
@tab '(``WWII'' ``World War II'')
|
||||
@end multitable
|
||||
|
||||
One can freely control which extraction methods to use by customizing
|
||||
@samp{org-roam-title-sources}: see the doc-string for the variable for more
|
||||
@code{org-roam-title-sources}: see the doc-string for the variable for more
|
||||
information. If all methods of title extraction return no results, the file-name
|
||||
is used in place of the titles for completions.
|
||||
|
||||
If you wish to add your own title extraction method, you may push a symbol
|
||||
@samp{'foo} into @samp{org-roam-title-sources}, and define a
|
||||
@samp{org-roam--extract-titles-foo} which accepts no arguments. See
|
||||
@samp{org-roam--extract-titles-title} for an example.
|
||||
@code{'foo} into @code{org-roam-title-sources}, and define a
|
||||
@code{org-roam--extract-titles-foo} which accepts no arguments. See
|
||||
@code{org-roam--extract-titles-title} for an example.
|
||||
|
||||
@node Tags
|
||||
@section Tags
|
||||
@@ -460,38 +462,38 @@ Tags are used as meta-data for files: they facilitate interactions with notes
|
||||
where titles are insufficient. For example, tags allow for categorization of
|
||||
notes: differentiating between bibliographical and structure notes during interactive commands.
|
||||
|
||||
Org-roam calls @samp{org-roam--extract-tags} to extract tags from files. It uses the
|
||||
variable @samp{org-roam-tag-sources}, to control how tags are extracted. The tag
|
||||
Org-roam calls @code{org-roam--extract-tags} to extract tags from files. It uses the
|
||||
variable @code{org-roam-tag-sources}, to control how tags are extracted. The tag
|
||||
extraction methods supported are:
|
||||
|
||||
@enumerate
|
||||
@item
|
||||
@samp{'prop}: This extracts tags from the @samp{#+roam_tags} property. Tags are space delimited, and can be multi-word using double quotes.
|
||||
@code{'prop}: This extracts tags from the @code{#+roam_tags} property. Tags are space delimited, and can be multi-word using double quotes.
|
||||
@item
|
||||
@samp{'all-directories}: All sub-directories relative to @samp{org-roam-directory} are
|
||||
@code{'all-directories}: All sub-directories relative to @code{org-roam-directory} are
|
||||
extracted as tags. That is, if a file is located at relative path
|
||||
@samp{foo/bar/file.org}, the file will have tags @samp{foo} and @samp{bar}.
|
||||
@code{foo/bar/file.org}, the file will have tags @code{foo} and @code{bar}.
|
||||
@item
|
||||
@samp{'last-directory}: Extracts the last directory relative to
|
||||
@samp{org-roam-directory} as the tag. That is, if a file is located at relative
|
||||
path @samp{foo/bar/file.org}, the file will have tag @samp{bar}.
|
||||
@code{'last-directory}: Extracts the last directory relative to
|
||||
@code{org-roam-directory} as the tag. That is, if a file is located at relative
|
||||
path @code{foo/bar/file.org}, the file will have tag @code{bar}.
|
||||
@item
|
||||
@samp{'first-directory}: Extracts the first directory relative to
|
||||
@samp{org-roam-directory} as the tag. That is, if a file is located at relative
|
||||
path @samp{foo/bar/file.org}, the file will have tag @samp{foo}.
|
||||
@code{'first-directory}: Extracts the first directory relative to
|
||||
@code{org-roam-directory} as the tag. That is, if a file is located at relative
|
||||
path @code{foo/bar/file.org}, the file will have tag @code{foo}.
|
||||
@end enumerate
|
||||
|
||||
By default, only the @samp{'prop} extraction method is enabled. To enable the other
|
||||
extraction methods, you may modify @samp{org-roam-tag-sources}:
|
||||
By default, only the @code{'prop} extraction method is enabled. To enable the other
|
||||
extraction methods, you may modify @code{org-roam-tag-sources}:
|
||||
|
||||
@lisp
|
||||
(setq org-roam-tag-sources '(prop last-directory))
|
||||
@end lisp
|
||||
|
||||
If you wish to add your own tag extraction method, you may push a symbol @samp{'foo}
|
||||
into @samp{org-roam-tag-sources}, and define a @samp{org-roam--extract-tags-foo} which
|
||||
If you wish to add your own tag extraction method, you may push a symbol @code{'foo}
|
||||
into @code{org-roam-tag-sources}, and define a @code{org-roam--extract-tags-foo} which
|
||||
accepts the absolute file path as its argument. See
|
||||
@samp{org-roam--extract-tags-prop} for an example.
|
||||
@code{org-roam--extract-tags-prop} for an example.
|
||||
|
||||
@node File Refs
|
||||
@section File Refs
|
||||
@@ -505,7 +507,7 @@ For example, a note for a website may contain a ref:
|
||||
@end example
|
||||
|
||||
These keys come in useful for when taking website notes, using the
|
||||
@samp{roam-ref} protocol (see @ref{Roam Protocol}).
|
||||
@code{roam-ref} protocol (see @ref{Roam Protocol}).
|
||||
|
||||
Alternatively, add a ref for notes for a specific paper, using its
|
||||
@uref{https://github.com/jkitchin/org-ref, org-ref} citation key:
|
||||
@@ -574,36 +576,36 @@ the default template, reproduced below.
|
||||
|
||||
@enumerate
|
||||
@item
|
||||
The template has short key @samp{"d"}. If you have only one template,
|
||||
The template has short key @code{"d"}. If you have only one template,
|
||||
org-roam automatically chooses this template for you.
|
||||
@item
|
||||
The template is given a description of @samp{"default"}.
|
||||
The template is given a description of @code{"default"}.
|
||||
@item
|
||||
@samp{plain} text is inserted. Other options include Org headings via
|
||||
@samp{entry}.
|
||||
@code{plain} text is inserted. Other options include Org headings via
|
||||
@code{entry}.
|
||||
@item
|
||||
@samp{(function org-roam--capture-get-point)} should not be changed.
|
||||
@code{(function org-roam--capture-get-point)} should not be changed.
|
||||
@item
|
||||
@samp{"%?"} is the template inserted on each call to @samp{org-roam-capture--capture}.
|
||||
@code{"%?"} is the template inserted on each call to @code{org-roam-capture--capture}.
|
||||
This template means don't insert any content, but place the cursor
|
||||
here.
|
||||
@item
|
||||
@samp{:file-name} is the file-name template for a new note, if it doesn't yet
|
||||
@code{:file-name} is the file-name template for a new note, if it doesn't yet
|
||||
exist. This creates a file at path that looks like
|
||||
@samp{/path/to/org-roam-directory/20200213032037-foo.org}. This template also
|
||||
@code{/path/to/org-roam-directory/20200213032037-foo.org}. This template also
|
||||
allows you to specify if you want the note to go into a subdirectory. For
|
||||
example, the template @samp{private/$@{slug@}} will create notes in
|
||||
@samp{/path/to/org-roam-directory/private}.
|
||||
example, the template @code{private/$@{slug@}} will create notes in
|
||||
@code{/path/to/org-roam-directory/private}.
|
||||
@item
|
||||
@samp{:head} contains the initial template to be inserted (once only), at
|
||||
@code{:head} contains the initial template to be inserted (once only), at
|
||||
the beginning of the file. Here, the title global attribute is
|
||||
inserted.
|
||||
@item
|
||||
@samp{:unnarrowed t} tells org-capture to show the contents for the whole
|
||||
@code{:unnarrowed t} tells org-capture to show the contents for the whole
|
||||
file, rather than narrowing to just the entry.
|
||||
@end enumerate
|
||||
|
||||
Other options you may want to learn about include @samp{:immediate-finish}.
|
||||
Other options you may want to learn about include @code{:immediate-finish}.
|
||||
|
||||
@node Org-roam Template Expansion
|
||||
@section Org-roam Template Expansion
|
||||
@@ -612,26 +614,26 @@ Org-roam's template definitions also extend org-capture's template syntax, to
|
||||
allow prefilling of strings. We have seen a glimpse of this in @ref{Template Walkthrough, , Template
|
||||
Walkthrough}.
|
||||
|
||||
In org-roam templates, the @samp{$@{var@}} syntax allows for the expansion of
|
||||
variables, stored in @samp{org-roam-capture--info}. For example, during
|
||||
@samp{org-roam-insert}, the user is prompted for a title. Upon entering a
|
||||
non-existent title, the @samp{title} key in @samp{org-roam-capture--info} is set to the
|
||||
provided title. @samp{$@{title@}} is then expanded into the provided title during the
|
||||
In org-roam templates, the @code{$@{var@}} syntax allows for the expansion of
|
||||
variables, stored in @code{org-roam-capture--info}. For example, during
|
||||
@code{org-roam-insert}, the user is prompted for a title. Upon entering a
|
||||
non-existent title, the @code{title} key in @code{org-roam-capture--info} is set to the
|
||||
provided title. @code{$@{title@}} is then expanded into the provided title during the
|
||||
org-capture process. Any variables that do not contain strings, are prompted for
|
||||
values using @samp{completing-read}.
|
||||
values using @code{completing-read}.
|
||||
|
||||
After doing this expansion, the org-capture's template expansion system
|
||||
is used to fill up the rest of the template. You may read up more on
|
||||
this on @uref{https://orgmode.org/manual/Template-expansion.html#Template-expansion, org-capture's documentation page}.
|
||||
|
||||
To illustrate this dual expansion process, take for example the template string:
|
||||
@samp{"%<%Y%m%d%H%M%S>-$@{title@}"}, with the title @samp{"Foo"}. The template is first
|
||||
expanded into @samp{%<%Y%m%d%H%M%S>-Foo}. Then org-capture expands @samp{%<%Y%m%d%H%M%S>}
|
||||
with timestamp: e.g. @samp{20200213032037-Foo}.
|
||||
@code{"%<%Y%m%d%H%M%S>-$@{title@}"}, with the title @code{"Foo"}. The template is first
|
||||
expanded into @code{%<%Y%m%d%H%M%S>-Foo}. Then org-capture expands @code{%<%Y%m%d%H%M%S>}
|
||||
with timestamp: e.g. @code{20200213032037-Foo}.
|
||||
|
||||
All of the flexibility afforded by Emacs and Org-mode are available. For
|
||||
example, if you want to encode a UTC timestamp in the filename, you can take
|
||||
advantage of org-mode's @samp{%(EXP)} template expansion to call @samp{format-time-string}
|
||||
advantage of org-mode's @code{%(EXP)} template expansion to call @code{format-time-string}
|
||||
directly to provide its third argument to specify UTC@.
|
||||
|
||||
@lisp
|
||||
@@ -650,7 +652,7 @@ the Org-roam codebase manageable. However, we attempt to accommodate as
|
||||
many usage styles as possible.
|
||||
|
||||
All of Org-roam's customization options can be viewed via
|
||||
@samp{M-x customize-group org-roam}.
|
||||
@code{M-x customize-group org-roam}.
|
||||
|
||||
@menu
|
||||
* Directories and Files::
|
||||
@@ -690,47 +692,47 @@ The Org-roam buffer displays backlinks for the currently active Org-roam note.
|
||||
@item
|
||||
User Option: org-roam-buffer
|
||||
|
||||
The name of the org-roam buffer. Defaults to @samp{*org-roam*}.
|
||||
The name of the org-roam buffer. Defaults to @code{*org-roam*}.
|
||||
|
||||
@item
|
||||
User Option: org-roam-buffer-position
|
||||
|
||||
The position of the Org-roam buffer side window. Valid values are @samp{'left},
|
||||
@samp{'right}, @samp{'top}, @samp{'bottom}.
|
||||
The position of the Org-roam buffer side window. Valid values are @code{'left},
|
||||
@code{'right}, @code{'top}, @code{'bottom}.
|
||||
|
||||
@item
|
||||
User Option: org-roam-buffer-width
|
||||
|
||||
Width of @samp{org-roam-buffer}. Has an effect only if @samp{org-roam-buffer-position} is
|
||||
@samp{'left} or @samp{'right}.
|
||||
Width of @code{org-roam-buffer}. Has an effect only if @code{org-roam-buffer-position} is
|
||||
@code{'left} or @code{'right}.
|
||||
|
||||
@item
|
||||
User Option: org-roam-buffer-height
|
||||
|
||||
Height of @samp{org-roam-buffer}. Has an effect only if @samp{org-roam-buffer-position} is
|
||||
@samp{'top} or @samp{'bottom}.
|
||||
Height of @code{org-roam-buffer}. Has an effect only if @code{org-roam-buffer-position} is
|
||||
@code{'top} or @code{'bottom}.
|
||||
|
||||
@item
|
||||
User Option: org-roam-buffer-no-delete-other-windows
|
||||
|
||||
The @samp{no-delete-window} parameter for the org-roam buffer. Setting it to @samp{'t} prevents the window from being deleted when calling @samp{delete-other-windows}.
|
||||
The @code{no-delete-window} parameter for the org-roam buffer. Setting it to @code{'t} prevents the window from being deleted when calling @code{delete-other-windows}.
|
||||
@end itemize
|
||||
|
||||
@node Org-roam Links
|
||||
@section Org-roam Links
|
||||
|
||||
Org-roam links are regular @samp{file:} links in Org-mode. By default, links are
|
||||
inserted with the title as the link description with @samp{org-roam-insert}.
|
||||
Org-roam links are regular @code{file:} links in Org-mode. By default, links are
|
||||
inserted with the title as the link description with @code{org-roam-insert}.
|
||||
|
||||
@itemize
|
||||
@item
|
||||
User Option: org-roam-link-title-format
|
||||
|
||||
To distinguish between org-roam links and regular links, one may choose to use
|
||||
special indicators for Org-roam links. Defaults to @samp{"%s"}.
|
||||
special indicators for Org-roam links. Defaults to @code{"%s"}.
|
||||
|
||||
If your version of Org is at least @samp{9.2}, consider styling the link differently,
|
||||
by customizing the @samp{org-roam-link}, and @samp{org-roam-link-current} faces.
|
||||
If your version of Org is at least @code{9.2}, consider styling the link differently,
|
||||
by customizing the @code{org-roam-link}, and @code{org-roam-link-current} faces.
|
||||
@end itemize
|
||||
|
||||
@node Org-roam Files
|
||||
@@ -753,7 +755,7 @@ As your collection grows, you might want to create an index where you keep links
|
||||
to your main files.
|
||||
|
||||
In Org-roam, you can define the path to your index file by setting
|
||||
@samp{org-roam-index-file}.
|
||||
@code{org-roam-index-file}.
|
||||
|
||||
@itemize
|
||||
@item
|
||||
@@ -762,23 +764,23 @@ Variable: org-roam-index-file
|
||||
Path to the Org-roam index file.
|
||||
|
||||
The path can be a string or a function. If it is a string, it should be the
|
||||
path (absolute or relative to @samp{org-roam-directory}) to the index file. If it
|
||||
path (absolute or relative to @code{org-roam-directory}) to the index file. If it
|
||||
is is a function, the function should return the path to the index file.
|
||||
Otherwise, the index is assumed to be a note in @samp{org-roam-index} whose
|
||||
title is @samp{"Index"}.
|
||||
Otherwise, the index is assumed to be a note in @code{org-roam-index} whose
|
||||
title is @code{"Index"}.
|
||||
|
||||
@item
|
||||
Function: org-roam-find-index
|
||||
|
||||
Opens the Index file in the current @samp{org-roam-directory}.
|
||||
Opens the Index file in the current @code{org-roam-directory}.
|
||||
@end itemize
|
||||
|
||||
@node Encryption
|
||||
@chapter Encryption
|
||||
|
||||
One may wish to keep private, encrypted files. Org-roam supports encryption (via
|
||||
GPG), which can be enabled for all new files by setting @samp{org-roam-encrypt-files}
|
||||
to @samp{t}. When enabled, new files are created with the @samp{.org.gpg} extension and
|
||||
GPG), which can be enabled for all new files by setting @code{org-roam-encrypt-files}
|
||||
to @code{t}. When enabled, new files are created with the @code{.org.gpg} extension and
|
||||
decryption are handled automatically by EasyPG@.
|
||||
|
||||
Note that Emacs will prompt for a password for encrypted files during
|
||||
@@ -799,7 +801,7 @@ Org-roam provides graphing capabilities to explore interconnections between
|
||||
notes. This is done by performing SQL queries and generating images using
|
||||
@uref{https://graphviz.org/, Graphviz}. The graph can also be navigated: see @ref{Roam Protocol}.
|
||||
|
||||
The entry point to graph creation is @samp{org-roam-graph}.
|
||||
The entry point to graph creation is @code{org-roam-graph}.
|
||||
|
||||
@itemize
|
||||
@item
|
||||
@@ -811,17 +813,17 @@ ARG may be any of the following values:
|
||||
|
||||
@itemize
|
||||
@item
|
||||
@samp{nil} show the graph.
|
||||
@code{nil} show the graph.
|
||||
@item
|
||||
@samp{C-u} show the graph for FILE@.
|
||||
@code{C-u} show the graph for FILE@.
|
||||
@item
|
||||
@samp{C-u N} show the graph for FILE limiting nodes to N steps.
|
||||
@code{C-u N} show the graph for FILE limiting nodes to N steps.
|
||||
@item
|
||||
@samp{C-u C-u} build the graph.
|
||||
@code{C-u C-u} build the graph.
|
||||
@item
|
||||
@samp{C-u -} build the graph for FILE@.
|
||||
@code{C-u -} build the graph for FILE@.
|
||||
@item
|
||||
@samp{C-u -N} build the graph for FILE limiting nodes to N steps.
|
||||
@code{C-u -N} build the graph for FILE limiting nodes to N steps.
|
||||
@end itemize
|
||||
|
||||
@item
|
||||
@@ -829,7 +831,7 @@ User Option: org-roam-graph-executable
|
||||
|
||||
Path to the graphing executable (in this case, Graphviz). Set this if Org-roam is unable to find the Graphviz executable on your system.
|
||||
|
||||
You may also choose to use @samp{neato} in place of @samp{dot}, which generates a more
|
||||
You may also choose to use @code{neato} in place of @code{dot}, which generates a more
|
||||
compact graph layout.
|
||||
|
||||
@item
|
||||
@@ -844,7 +846,7 @@ A string, which is a path to the program used
|
||||
a function accepting a single argument: the graph file path.
|
||||
@end enumerate
|
||||
|
||||
@samp{nil} uses @samp{view-file} to view the graph.
|
||||
@code{nil} uses @code{view-file} to view the graph.
|
||||
|
||||
If you are using WSL2 and would like to open the graph in Windows, you can use the second option to set the browser and network file path:
|
||||
|
||||
@@ -871,25 +873,25 @@ Graphviz provides many options for customizing the graph output, and Org-roam su
|
||||
User Option: org-roam-graph-extra-config
|
||||
|
||||
Extra options passed to graphviz for the digraph (The ``G'' attributes).
|
||||
Example: @samp{'=(("rankdir" . "LR"))}
|
||||
Example: @code{'~(("rankdir" . "LR"))}
|
||||
|
||||
@item
|
||||
User Option: org-roam-graph-node-extra-config
|
||||
|
||||
Extra options for nodes in the graphviz output (The ``N'' attributes).
|
||||
Example: @samp{'(("color" . "skyblue"))}
|
||||
Example: @code{'(("color" . "skyblue"))}
|
||||
|
||||
@item
|
||||
User Option: org-roam-graph-edge-extra-config
|
||||
|
||||
Extra options for edges in the graphviz output (The ``E'' attributes).
|
||||
Example: @samp{'(("dir" . "back"))}
|
||||
Example: @code{'(("dir" . "back"))}
|
||||
|
||||
@item
|
||||
User Option: org-roam-graph-edge-cites-extra-config
|
||||
|
||||
Extra options for citation edges in the graphviz output.
|
||||
Example: @samp{'(("color" . "red"))}
|
||||
Example: @code{'(("color" . "red"))}
|
||||
@end itemize
|
||||
|
||||
@node Excluding Nodes and Edges
|
||||
@@ -926,14 +928,14 @@ system is configurable. The default setting,
|
||||
(setq org-roam-completion-system 'default)
|
||||
@end lisp
|
||||
|
||||
uses Emacs' standard @samp{completing-read}. If you prefer
|
||||
uses Emacs' standard @code{completing-read}. If you prefer
|
||||
@uref{https://emacs-helm.github.io/helm/, Helm}, use
|
||||
|
||||
@lisp
|
||||
(setq org-roam-completion-system 'helm)
|
||||
@end lisp
|
||||
|
||||
Other options include @samp{'ido}, and @samp{'ivy}.
|
||||
Other options include @code{'ido}, and @code{'ivy}.
|
||||
|
||||
@node Roam Protocol
|
||||
@chapter Roam Protocol
|
||||
@@ -941,15 +943,15 @@ Other options include @samp{'ido}, and @samp{'ivy}.
|
||||
@menu
|
||||
* _::
|
||||
* Installation: Installation (1).
|
||||
* The @samp{roam-file} protocol::
|
||||
* The @samp{roam-ref} Protocol::
|
||||
* The roam-file protocol::
|
||||
* The roam-ref protocol::
|
||||
@end menu
|
||||
|
||||
@node _
|
||||
@section _ :ignore:
|
||||
|
||||
Org-roam extending @samp{org-protocol} with 2 protocols: the @samp{roam-file}
|
||||
and @samp{roam-ref} protocol.
|
||||
Org-roam extending @code{org-protocol} with 2 protocols: the @code{roam-file}
|
||||
and @code{roam-ref} protocol.
|
||||
|
||||
@node Installation (1)
|
||||
@section Installation
|
||||
@@ -960,12 +962,12 @@ To enable Org-roam's protocol extensions, you have to add the following to your
|
||||
(require 'org-roam-protocol)
|
||||
@end lisp
|
||||
|
||||
The instructions for setting up @samp{org-protocol=} are reproduced below.
|
||||
The instructions for setting up @code{org-protocol} are reproduced below.
|
||||
|
||||
We will also need to create a desktop application for @samp{emacsclient}. The
|
||||
We will also need to create a desktop application for @code{emacsclient}. The
|
||||
instructions for various platforms are shown below.
|
||||
|
||||
For Linux users, create a desktop application in @samp{~/.local/share/applications/org-protocol.desktop}:
|
||||
For Linux users, create a desktop application in @code{~/.local/share/applications/org-protocol.desktop}:
|
||||
|
||||
@example
|
||||
[Desktop Entry]
|
||||
@@ -977,7 +979,7 @@ Terminal=false
|
||||
MimeType=x-scheme-handler/org-protocol
|
||||
@end example
|
||||
|
||||
Associate @samp{org-protocol://} links with the desktop application by
|
||||
Associate @code{org-protocol://} links with the desktop application by
|
||||
running in your shell:
|
||||
|
||||
@example
|
||||
@@ -985,7 +987,7 @@ xdg-mime default org-protocol.desktop x-scheme-handler/org-protocol
|
||||
@end example
|
||||
|
||||
To disable the ``confirm'' prompt in Chrome, you can also make Chrome
|
||||
show a checkbox to tick, so that the @samp{Org-Protocol Client} app will be used
|
||||
show a checkbox to tick, so that the @code{Org-Protocol Client} app will be used
|
||||
without confirmation. To do this, run in a shell:
|
||||
|
||||
@example
|
||||
@@ -1001,8 +1003,8 @@ 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 @uref{https://www.chromium.org/administrators/linux-quick-start, here} for more info on the @samp{/etc/opt/chrome/policies/managed} directory and
|
||||
@uref{https://cloud.google.com/docs/chrome-enterprise/policies/?policy=ExternalProtocolDialogShowAlwaysOpenCheckbox, here} for information on the @samp{ExternalProtocolDialogShowAlwaysOpenCheckbox} policy.
|
||||
See @uref{https://www.chromium.org/administrators/linux-quick-start, here} for more info on the @code{/etc/opt/chrome/policies/managed} directory and
|
||||
@uref{https://cloud.google.com/docs/chrome-enterprise/policies/?policy=ExternalProtocolDialogShowAlwaysOpenCheckbox, here} for information on the @code{ExternalProtocolDialogShowAlwaysOpenCheckbox} policy.
|
||||
|
||||
For MacOS, one solution is to use @uref{https://github.com/sveinbjornt/Platypus, Platypus}. Here are the instructions for
|
||||
setting up with Platypus and Chrome:
|
||||
@@ -1018,7 +1020,7 @@ brew cask install platypus
|
||||
|
||||
@enumerate
|
||||
@item
|
||||
Create a script @samp{launch_emacs.sh}:
|
||||
Create a script @code{launch_emacs.sh}:
|
||||
@end enumerate
|
||||
|
||||
@example
|
||||
@@ -1043,7 +1045,7 @@ Create a Platypus app with the following settings:
|
||||
@end example
|
||||
|
||||
|
||||
Inside @samp{Settings}:
|
||||
Inside @code{Settings}:
|
||||
|
||||
@example
|
||||
| Setting | Value |
|
||||
@@ -1054,7 +1056,7 @@ Inside @samp{Settings}:
|
||||
@end example
|
||||
|
||||
To disable the ``confirm'' prompt in Chrome, you can also make Chrome
|
||||
show a checkbox to tick, so that the @samp{OrgProtocol} app will be used
|
||||
show a checkbox to tick, so that the @code{OrgProtocol} app will be used
|
||||
without confirmation. To do this, run in a shell:
|
||||
|
||||
@example
|
||||
@@ -1063,7 +1065,7 @@ defaults write com.google.Chrome ExternalProtocolDialogShowAlwaysOpenCheckbox -b
|
||||
|
||||
|
||||
If you're using @uref{https://github.com/railwaycat/homebrew-emacsmacport, Emacs Mac Port}, it registered its `Emacs.app` as the default
|
||||
handler for the URL scheme `org-protocol`. To make @samp{OrgProtocol.app}
|
||||
handler for the URL scheme `org-protocol`. To make @code{OrgProtocol.app}
|
||||
the default handler instead, run:
|
||||
|
||||
@example
|
||||
@@ -1073,7 +1075,7 @@ defaults write com.apple.LaunchServices/com.apple.launchservices.secure LSHandle
|
||||
|
||||
Then restart your computer.
|
||||
|
||||
For Windows, create a temporary @samp{org-protocol.reg} file:
|
||||
For Windows, create a temporary @code{org-protocol.reg} file:
|
||||
|
||||
@example
|
||||
REGEDIT4
|
||||
@@ -1095,15 +1097,15 @@ The above will forward the protocol to WSL@. If you run Emacs natively on Window
|
||||
|
||||
After executing the .reg file, the protocol is registered and you can delete the file.
|
||||
|
||||
@node The @samp{roam-file} protocol
|
||||
@section The @samp{roam-file} protocol
|
||||
@node The roam-file protocol
|
||||
@section The roam-file protocol
|
||||
|
||||
This is a simple protocol that opens the path specified by the @samp{file}
|
||||
key (e.g. @samp{org-protocol://roam-file?file=/tmp/file.org}). This is used
|
||||
This is a simple protocol that opens the path specified by the @code{file}
|
||||
key (e.g. @code{org-protocol://roam-file?file=/tmp/file.org}). This is used
|
||||
in the generated graph.
|
||||
|
||||
@node The @samp{roam-ref} Protocol
|
||||
@section The @samp{roam-ref} Protocol
|
||||
@node The roam-ref protocol
|
||||
@section The roam-ref protocol
|
||||
|
||||
This protocol finds or creates a new note with a given @code{roam_key} (see @ref{Anatomy of an Org-roam File}):
|
||||
|
||||
@@ -1138,7 +1140,7 @@ should contain a @code{#+roam_key: $@{ref@}} in it.
|
||||
|
||||
Org-roam provides a utility for diagnosing and repairing problematic files via
|
||||
@code{org-roam-doctor}. By default, @code{org-roam-doctor} runs the check on the current
|
||||
Org-roam file. To run the check only for the current file, run @samp{C-u M-x
|
||||
Org-roam file. To run the check only for the current file, run @code{C-u M-x
|
||||
org-roam-doctor}, but note that this may take some time.
|
||||
|
||||
@itemize
|
||||
@@ -1149,7 +1151,7 @@ Perform a check on Org-roam files to ensure cleanliness. If THIS-BUFFER, run
|
||||
the check only for the current buffer.
|
||||
@end itemize
|
||||
|
||||
The checks run are defined in @samp{org-roam-doctor--checkers}. Each checker is an instance of @samp{org-roam-doctor-checker}. To define a checker, use @samp{make-org-roam-doctor-checker}. Here is a sample definition:
|
||||
The checks run are defined in @code{org-roam-doctor--checkers}. Each checker is an instance of @code{org-roam-doctor-checker}. To define a checker, use @code{make-org-roam-doctor-checker}. Here is a sample definition:
|
||||
|
||||
@lisp
|
||||
(make-org-roam-doctor-checker
|
||||
@@ -1160,14 +1162,14 @@ The checks run are defined in @samp{org-roam-doctor--checkers}. Each checker is
|
||||
("R" . ("Replace link (keep label)" . org-roam-doctor--replace-link-keep-label))))
|
||||
@end lisp
|
||||
|
||||
The @samp{:name} property is the name of the function run. The function takes in the
|
||||
Org parse tree, and returns a list of @samp{(point error-message)}. @samp{:description} is a
|
||||
short description of what the checker does. @samp{:actions} is an alist containing
|
||||
elements of the form @samp{(char . (prompt . function))}. These actions are defined per
|
||||
The @code{:name} property is the name of the function run. The function takes in the
|
||||
Org parse tree, and returns a list of @code{(point error-message)}. @code{:description} is a
|
||||
short description of what the checker does. @code{:actions} is an alist containing
|
||||
elements of the form @code{(char . (prompt . function))}. These actions are defined per
|
||||
checker, to perform autofixes for the errors. For each error detected,
|
||||
@samp{org-roam-doctor} will move the point to the current error, and pop-up a help
|
||||
@code{org-roam-doctor} will move the point to the current error, and pop-up a help
|
||||
window displaying the error message, as well as the list of actions that can be
|
||||
taken provided in @samp{:actions}.
|
||||
taken provided in @code{:actions}.
|
||||
|
||||
@node Performance Optimization
|
||||
@chapter Performance Optimization
|
||||
@@ -1282,7 +1284,7 @@ for browsing and filtering org-roam notes.
|
||||
@end lisp
|
||||
|
||||
If the title of the Org file is not the first line, you might not get
|
||||
nice titles. You may choose to patch this to use @samp{org-roam}'s
|
||||
nice titles. You may choose to patch this to use @code{org-roam}'s
|
||||
functionality. Here I'm using
|
||||
@uref{https://github.com/raxod502/el-patch, el-patch}:
|
||||
|
||||
@@ -1320,7 +1322,7 @@ that uses an external search engine and indexer.
|
||||
@subsection Org-journal
|
||||
|
||||
@uref{https://github.com/bastibe/org-journal, Org-journal} is a more
|
||||
powerful alternative to the simple function @samp{org-roam-dailies-today}. It
|
||||
powerful alternative to the simple function @code{org-roam-dailies-today}. It
|
||||
provides better journaling capabilities, and a nice calendar interface
|
||||
to see all dated entries.
|
||||
|
||||
@@ -1401,8 +1403,8 @@ etc.) within Org-mode.
|
||||
tight integration between
|
||||
@uref{https://github.com/jkitchin/org-ref, org-ref},
|
||||
@uref{https://github.com/tmalsburg/helm-bibtex, helm-bibtex} and
|
||||
@samp{org-roam}. This helps you manage your bibliographic notes under
|
||||
@samp{org-roam}.
|
||||
@code{org-roam}. This helps you manage your bibliographic notes under
|
||||
@code{org-roam}.
|
||||
|
||||
@node Spaced Repetition
|
||||
@unnumberedsubsubsec Spaced Repetition
|
||||
@@ -1422,11 +1424,11 @@ files. Other alternatives include @uref{https://orgmode.org/worg/org-contrib/org
|
||||
@section How do I have more than one Org-roam directory?
|
||||
|
||||
Emacs supports directory-local variables, allowing the value of
|
||||
@samp{org-roam-directory} to be different in different directories. It does this by
|
||||
checking for a file named @samp{.dir-locals.el}.
|
||||
@code{org-roam-directory} to be different in different directories. It does this by
|
||||
checking for a file named @code{.dir-locals.el}.
|
||||
|
||||
To add support for multiple directories, override the @samp{org-roam-directory}
|
||||
variable using directory-local variables. This is what @samp{.dir-locals.el} may
|
||||
To add support for multiple directories, override the @code{org-roam-directory}
|
||||
variable using directory-local variables. This is what @code{.dir-locals.el} may
|
||||
contain:
|
||||
|
||||
@lisp
|
||||
@@ -1434,7 +1436,7 @@ contain:
|
||||
@end lisp
|
||||
|
||||
All files within that directory will be treated as their own separate
|
||||
set of Org-roam files. Remember to run @samp{org-roam-db-build-cache} from a
|
||||
set of Org-roam files. Remember to run @code{org-roam-db-build-cache} from a
|
||||
file within that directory, at least once.
|
||||
|
||||
@node How do I migrate from Roam Research?
|
||||
|
||||
Reference in New Issue
Block a user