mirror of
https://github.com/org-roam/org-roam
synced 2025-08-17 13:33:31 -05:00
2665 lines
140 KiB
HTML
2665 lines
140 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
<html>
|
||
<!-- Copyright (C) 2020-2020 Jethro Kuan <jethrokuan95@gmail.com>
|
||
|
||
You can redistribute this document and/or modify it under the terms
|
||
of the GNU General Public License as published by the Free Software
|
||
Foundation, either version 3 of the License, or (at your option) any
|
||
later version.
|
||
|
||
This document is distributed in the hope that it will be useful,
|
||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||
General Public License for more details.
|
||
-->
|
||
<!-- Created by GNU Texinfo 6.7, http://www.gnu.org/software/texinfo/ -->
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
<title>Org-roam User Manual</title>
|
||
|
||
<meta name="description" content="Org-roam User Manual">
|
||
<meta name="keywords" content="Org-roam User Manual">
|
||
<meta name="resource-type" content="document">
|
||
<meta name="distribution" content="global">
|
||
<meta name="Generator" content="makeinfo">
|
||
<link href="#Top" rel="start" title="Top">
|
||
<link href="#Keystroke-Index" rel="index" title="Keystroke Index">
|
||
<style type="text/css">
|
||
<!--
|
||
a.summary-letter {text-decoration: none}
|
||
blockquote.indentedblock {margin-right: 0em}
|
||
div.display {margin-left: 3.2em}
|
||
div.example {margin-left: 3.2em}
|
||
div.lisp {margin-left: 3.2em}
|
||
kbd {font-style: oblique}
|
||
pre.display {font-family: inherit}
|
||
pre.format {font-family: inherit}
|
||
pre.menu-comment {font-family: serif}
|
||
pre.menu-preformatted {font-family: serif}
|
||
span.nolinebreak {white-space: nowrap}
|
||
span.roman {font-family: initial; font-weight: normal}
|
||
span.sansserif {font-family: sans-serif; font-weight: normal}
|
||
ul.no-bullet {list-style: none}
|
||
-->
|
||
</style>
|
||
<link rel="stylesheet" type="text/css" href="assets/page.css">
|
||
|
||
|
||
</head>
|
||
|
||
<body lang="en">
|
||
<h1 class="settitle" align="center">Org-roam User Manual</h1>
|
||
|
||
|
||
|
||
|
||
<span id="Top"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Introduction" accesskey="n" rel="next">Introduction</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Org_002droam-User-Manual"></span><h1 class="top">Org-roam User Manual</h1>
|
||
|
||
|
||
<p>This manual is for Org-roam version 1.2.3.
|
||
</p>
|
||
<blockquote>
|
||
<p>Copyright (C) 2020-2020 Jethro Kuan <jethrokuan95@gmail.com>
|
||
</p>
|
||
<p>You can redistribute this document and/or modify it under the terms of the GNU
|
||
General Public License as published by the Free Software Foundation, either
|
||
version 3 of the License, or (at your option) any later version.
|
||
</p>
|
||
<p>This document is distributed in the hope that it will be useful,
|
||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||
General Public License for more details.
|
||
</p>
|
||
</blockquote>
|
||
|
||
<table class="menu" border="0" cellspacing="0">
|
||
<tr><td align="left" valign="top">• <a href="#Introduction" accesskey="1">Introduction</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Target-Audience" accesskey="2">Target Audience</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#A-Brief-Introduction-to-the-Zettelkasten-Method" accesskey="3">A Brief Introduction to the Zettelkasten Method</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Installation" accesskey="4">Installation</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Getting-Started" accesskey="5">Getting Started</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Files" accesskey="6">Files</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#The-Templating-System" accesskey="7">The Templating System</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Concepts-and-Configuration" accesskey="8">Concepts and Configuration</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Inserting-Links" accesskey="9">Inserting Links</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Completions">Completions</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Navigating-Around">Navigating Around</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Encryption">Encryption</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Graphing">Graphing</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Minibuffer-Completion">Minibuffer Completion</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Roam-Protocol">Roam Protocol</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Daily_002dnotes">Daily-notes</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Diagnosing-and-Repairing-Files">Diagnosing and Repairing Files</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Finding-Unlinked-References">Finding Unlinked References</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Performance-Optimization">Performance Optimization</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Appendix">Appendix</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#FAQ">FAQ</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Keystroke-Index" rel="index">Keystroke Index</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Command-Index" rel="index">Command Index</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Function-Index" rel="index">Function Index</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Variable-Index" rel="index">Variable Index</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
|
||
|
||
</pre></th></tr><tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">— The Detailed Node Listing —
|
||
|
||
A Brief Introduction to the Zettelkasten Method
|
||
|
||
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Fleeting-notes">Fleeting notes</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Permanent-notes">Permanent notes</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
|
||
|
||
Installation
|
||
|
||
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Installing-from-MELPA">Installing from MELPA</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Installing-from-Apt">Installing from Apt</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Installing-from-the-Git-Repository">Installing from the Git Repository</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Post_002dInstallation-Tasks">Post-Installation Tasks</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
|
||
|
||
Files
|
||
|
||
</pre></th></tr><tr><td align="left" valign="top">• <a href="#File-Titles">File Titles</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#File-Tags">File Tags</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#File-Refs">File Refs</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
|
||
|
||
File Titles
|
||
|
||
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Customizing-Title-Extraction">Customizing Title Extraction</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
|
||
|
||
File Tags
|
||
|
||
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Customizing-Tag-Extraction">Customizing Tag Extraction</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
|
||
|
||
The Templating System
|
||
|
||
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Template-Walkthrough">Template Walkthrough</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Org_002droam-Template-Expansion">Org-roam Template Expansion</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
|
||
|
||
Concepts and Configuration
|
||
|
||
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Directories-and-Files">Directories and Files</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#The-Org_002droam-Buffer">The Org-roam Buffer</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Org_002droam-Files">Org-roam Files</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Org_002droam-Faces">Org-roam Faces</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#The-Database">The Database</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
|
||
|
||
Completions
|
||
|
||
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Link-Completion">Link Completion</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Tag-Completion">Tag Completion</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
|
||
|
||
Link Completion
|
||
|
||
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Link-Completions-Everywhere">Link Completions Everywhere</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
|
||
|
||
Navigating Around
|
||
|
||
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Index-File">Index File</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
|
||
|
||
Graphing
|
||
|
||
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Graph-Options">Graph Options</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Excluding-Nodes-and-Edges">Excluding Nodes and Edges</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
|
||
|
||
Roam Protocol
|
||
|
||
</pre></th></tr><tr><td align="left" valign="top">• <a href="#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">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">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">
|
||
|
||
Daily-notes
|
||
|
||
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Configuration">Configuration</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Capturing-and-finding-daily_002dnotes">Capturing and finding daily-notes</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Navigation">Navigation</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
|
||
|
||
Performance Optimization
|
||
|
||
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Profiling-Key-Operations">Profiling Key Operations</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Garbage-Collection">Garbage Collection</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
|
||
|
||
Appendix
|
||
|
||
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Note_002dtaking-Workflows">Note-taking Workflows</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Ecosystem">Ecosystem</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
|
||
|
||
Ecosystem
|
||
|
||
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Browsing-History-with-winner_002dmode">Browsing History with winner-mode</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Versioning-Notes">Versioning Notes</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Full_002dtext-search-interface-with-Deft">Full-text search interface with Deft</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Org_002djournal">Org-journal</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Note_002dtaking-Add_002dons">Note-taking Add-ons</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
|
||
|
||
Note-taking Add-ons
|
||
|
||
</pre></th></tr><tr><td align="left" valign="top">• <a href="#Org_002ddownload">Org-download</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#mathpixel">mathpix.el</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Org_002dnoter-_002f-Interleave">Org-noter / Interleave</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Bibliography">Bibliography</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Spaced-Repetition">Spaced Repetition</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
|
||
|
||
FAQ
|
||
|
||
</pre></th></tr><tr><td align="left" valign="top">• <a href="#How-do-I-have-more-than-one-Org_002droam-directory_003f">How do I have more than one Org-roam directory?</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#How-do-I-migrate-from-Roam-Research_003f">How do I migrate from Roam Research?</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#How-do-I-create-a-note-whose-title-already-matches-one-of-the-candidates_003f">How do I create a note whose title already matches one of the candidates?</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
|
||
|
||
</pre></th></tr></table>
|
||
|
||
<hr>
|
||
<span id="Introduction"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Target-Audience" accesskey="n" rel="next">Target Audience</a>, Previous: <a href="#Top" accesskey="p" rel="prev">Top</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Introduction-1"></span><h2 class="chapter">1 Introduction</h2>
|
||
|
||
<p>Org-roam is a tool for network thought. It reproduces some of <a href="https://roamresearch.com/">Roam
|
||
Research’s</a> <a id="DOCF1" href="#FOOT1"><sup>1</sup></a> features within the all-powerful <a href="https://orgmode.org/">Org-mode</a>.
|
||
</p>
|
||
<p>Org-roam is a solution for effortless non-hierarchical note-taking with
|
||
Org-mode. With Org-roam, notes flow naturally, making note-taking fun and easy.
|
||
Org-roam keeps closely to Org syntax, and will work for anyone already using
|
||
Org-mode for their personal wiki.
|
||
</p>
|
||
<p>Org-roam gains its superpowers by leveraging the mature ecosystem around
|
||
Org-mode. For example, it has first-class support for <a href="https://github.com/jkitchin/org-ref">org-ref</a> for citation
|
||
management.
|
||
</p>
|
||
<p>Org-roam aims to implement the core features of Roam, leveraging the
|
||
mature ecosystem around Org-mode where possible. Eventually, we hope
|
||
to further introduce features enabled by the Emacs ecosystem.
|
||
</p>
|
||
<p>Org-roam provides several benefits over other tooling:
|
||
</p>
|
||
<ul>
|
||
<li> <strong>Privacy and Security:</strong> Keep your personal wiki entirely offline and in your
|
||
control. Encrypt your notes with GPG.
|
||
|
||
</li><li> <strong>Longevity of Plain Text:</strong> Unlike web solutions like Roam Research, the notes
|
||
are first and foremost plain Org-mode files – Org-roam simply builds an
|
||
auxiliary database to give the personal wiki superpowers. Having your notes
|
||
in plain-text is crucial for the longevity of your wiki. Never have to worry
|
||
about proprietary web solutions being taken down. The notes are still
|
||
functional even if Org-roam ceases to exist.
|
||
|
||
</li><li> <strong>Free and Open Source:</strong> Org-roam is free and open-source, which means that if
|
||
you feel unhappy with any part of Org-roam, you may choose to extend Org-roam,
|
||
or open a pull request.
|
||
|
||
</li><li> <strong>Leverage the Org-mode ecosystem:</strong> Over the years, Emacs and Org-mode has
|
||
developed into a mature system for plain-text organization. Building upon
|
||
Org-mode already puts Org-roam light-years ahead of many other solutions.
|
||
|
||
</li><li> <strong>Built on Emacs:</strong> Emacs is also a fantastic interface for editing text, and we
|
||
can inherit many of the powerful text-navigation and editing packages
|
||
available to Emacs.
|
||
</li></ul>
|
||
|
||
<hr>
|
||
<span id="Target-Audience"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#A-Brief-Introduction-to-the-Zettelkasten-Method" accesskey="n" rel="next">A Brief Introduction to the Zettelkasten Method</a>, Previous: <a href="#Introduction" accesskey="p" rel="prev">Introduction</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Target-Audience-1"></span><h2 class="chapter">2 Target Audience</h2>
|
||
|
||
<p>Org-roam is a tool that will appear unfriendly to anyone unfamiliar with Emacs
|
||
and Org-mode, but is also extremely powerful to those willing to put effort in
|
||
mastering the intricacies of the tools. Org-roam stands on the shoulders on
|
||
giants. Emacs was first created in 1976, and remains a top tier tool for editing
|
||
text and designing textual interfaces. The malleability of Emacs allowed the
|
||
creation of Org-mode, an all-purpose plain-text system for maintaining TODO
|
||
lists, planning projects, and authoring documents. Both of these tools are
|
||
incredibly vast and require significant time investment to master.
|
||
</p>
|
||
<p>Org-roam assumes basic familiarity with these tools. It is not difficult to get
|
||
up and running with basic text-editing functionality, but one will only fully
|
||
appreciate the power of building Roam functionality into Emacs and Org-mode when
|
||
the usage of these tools become more advanced.
|
||
</p>
|
||
<p>One key advantage to Org-roam is that building on top of Emacs gives it
|
||
malleability. This is especially important for note-taking workflows. It is our
|
||
belief that note-taking workflows are extremely personal, and there is no one
|
||
tool that’s perfect for you. Org-mode and Org-roam allows you to discover what
|
||
works for you, and build that perfect tool for yourself.
|
||
</p>
|
||
<p>If you are new to the software, and choose to take this leap of faith, I hope
|
||
you find yourself equally entranced as Neal Stephenson was.
|
||
</p>
|
||
<blockquote>
|
||
<p>Emacs outshines all other editing software in approximately the same way that
|
||
the noonday sun does the stars. It is not just bigger and brighter; it simply
|
||
makes everything else vanish. – Neal Stephenson, In the Beginning was the
|
||
Command Line (1998)
|
||
</p>
|
||
</blockquote>
|
||
|
||
<hr>
|
||
<span id="A-Brief-Introduction-to-the-Zettelkasten-Method"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Installation" accesskey="n" rel="next">Installation</a>, Previous: <a href="#Target-Audience" accesskey="p" rel="prev">Target Audience</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="A-Brief-Introduction-to-the-Zettelkasten-Method-1"></span><h2 class="chapter">3 A Brief Introduction to the Zettelkasten Method</h2>
|
||
|
||
<p>Org-roam provides utilities for maintaining a digital slip-box. This section
|
||
aims to provide a brief introduction to the “slip-box”, or “Zettelkasten”
|
||
method. By providing some background on the method, we hope that the design
|
||
decisions of Org-roam will become clear, and that will aid in using Org-roam
|
||
appropriately. In this section we will introduce terms commonly used within the
|
||
Zettelkasten community and the Org-roam forums.
|
||
</p>
|
||
<p>The Zettelkasten is a personal tool for thinking and writing. It places heavy
|
||
emphasis on connecting ideas, building up a web of thought. Hence, it is well
|
||
suited for knowledge workers and intellectual tasks, such as conducting
|
||
research. The Zettelkasten can act as a research partner, where conversations
|
||
with it may produce new and surprising lines of thought.
|
||
</p>
|
||
<p>This method is attributed to German sociologist Niklas Luhmann, who using the
|
||
method had produced volumes of written works. Luhmann’s slip-box was simply a
|
||
box of cards. These cards are small – often only large enough to fit a single
|
||
concept. The size limitation encourages ideas to be broken down into individual
|
||
concepts. These ideas are explicitly linked together. The breakdown of ideas
|
||
encourages tangential exploration of ideas, increasing the surface for thought.
|
||
Making linking explicit between notes also encourages one to think about the
|
||
connections between concepts.
|
||
</p>
|
||
<p>At the corner of each note, Luhmann ascribed each note with an ordered ID,
|
||
allowing him to link and jump between notes. In Org-roam, we simply use
|
||
hyperlinks.
|
||
</p>
|
||
<p>Org-roam is the slip-box, digitalized in Org-mode. Every zettel (card) is a
|
||
plain-text, Org-mode file. In the same way one would maintain a paper slip-box,
|
||
Org-roam makes it easy to create new zettels, pre-filling boilerplate content
|
||
using a powerful templating system.
|
||
</p>
|
||
<table class="menu" border="0" cellspacing="0">
|
||
<tr><td align="left" valign="top">• <a href="#Fleeting-notes" accesskey="1">Fleeting notes</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Permanent-notes" accesskey="2">Permanent notes</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
</table>
|
||
|
||
<hr>
|
||
<span id="Fleeting-notes"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Permanent-notes" accesskey="n" rel="next">Permanent notes</a>, Up: <a href="#A-Brief-Introduction-to-the-Zettelkasten-Method" accesskey="u" rel="up">A Brief Introduction to the Zettelkasten Method</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Fleeting-notes-1"></span><h3 class="section">3.1 Fleeting notes</h3>
|
||
|
||
<p>A slip-box requires a method for quickly capturing ideas. These are called
|
||
<strong>fleeting notes</strong>: they are simple reminders of information or ideas that will
|
||
need to be processed later on, or trashed. This is typically accomplished using
|
||
<code>org-capture</code> (see <a href="https://www.gnu.org/software/emacs/manual/html_mono/org.html#Capture">(org)Capture</a>), or using Org-roam’s daily notes
|
||
functionality (see <a href="#Daily_002dnotes">Daily-notes</a>). This provides a central inbox for collecting
|
||
thoughts, to be processed later into permanent notes.
|
||
</p>
|
||
<hr>
|
||
<span id="Permanent-notes"></span><div class="header">
|
||
<p>
|
||
Previous: <a href="#Fleeting-notes" accesskey="p" rel="prev">Fleeting notes</a>, Up: <a href="#A-Brief-Introduction-to-the-Zettelkasten-Method" accesskey="u" rel="up">A Brief Introduction to the Zettelkasten Method</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Permanent-notes-1"></span><h3 class="section">3.2 Permanent notes</h3>
|
||
|
||
<p>Permanent notes are further split into two categories: <strong>literature notes</strong> and
|
||
<strong>concept notes</strong>. Literature notes can be brief annotations on a particular
|
||
source (e.g. book, website or paper), that you’d like to access later on.
|
||
Concept notes require much more care in authoring: they need to be
|
||
self-explanatory and detailed. Org-roam’s templating system supports the
|
||
addition of different templates to facilitate the creation of these notes.
|
||
</p>
|
||
<hr>
|
||
<span id="Installation"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Getting-Started" accesskey="n" rel="next">Getting Started</a>, Previous: <a href="#A-Brief-Introduction-to-the-Zettelkasten-Method" accesskey="p" rel="prev">A Brief Introduction to the Zettelkasten Method</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Installation-1"></span><h2 class="chapter">4 Installation</h2>
|
||
|
||
<p>Org-roam can be installed using Emacs’ package manager or manually from its
|
||
development repository.
|
||
</p>
|
||
<table class="menu" border="0" cellspacing="0">
|
||
<tr><td align="left" valign="top">• <a href="#Installing-from-MELPA" accesskey="1">Installing from MELPA</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Installing-from-Apt" accesskey="2">Installing from Apt</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Installing-from-the-Git-Repository" accesskey="3">Installing from the Git Repository</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Post_002dInstallation-Tasks" accesskey="4">Post-Installation Tasks</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
</table>
|
||
|
||
<hr>
|
||
<span id="Installing-from-MELPA"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Installing-from-Apt" accesskey="n" rel="next">Installing from Apt</a>, Up: <a href="#Installation" accesskey="u" rel="up">Installation</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Installing-from-MELPA-1"></span><h3 class="section">4.1 Installing from MELPA</h3>
|
||
|
||
<p>Org-roam is available from Melpa and Melpa-Stable. If you haven’t used Emacs’
|
||
package manager before, you may familiarize yourself with it by reading the
|
||
documentation in the Emacs manual, see <a href="https://www.gnu.org/software/emacs/manual/html_mono/emacs.html#Packages">(emacs)Packages</a>. Then, add one of the
|
||
archives to ‘<samp>package-archives</samp>’:
|
||
</p>
|
||
<ul>
|
||
<li> To use Melpa:
|
||
</li></ul>
|
||
|
||
<div class="lisp">
|
||
<pre class="lisp">(require 'package)
|
||
(add-to-list 'package-archives
|
||
'("melpa" . "http://melpa.org/packages/") t)
|
||
</pre></div>
|
||
|
||
<ul>
|
||
<li> To use Melpa-Stable:
|
||
</li></ul>
|
||
|
||
<div class="lisp">
|
||
<pre class="lisp">(require 'package)
|
||
(add-to-list 'package-archives
|
||
'("melpa-stable" . "http://stable.melpa.org/packages/") t)
|
||
</pre></div>
|
||
|
||
<p>Org-roam also depends on a recent version of Org, which can be obtained in Org’s
|
||
package repository (see <a href="https://www.gnu.org/software/emacs/manual/html_mono/org.html#Installation">(org)Installation</a>). To use Org’s ELPA archive:
|
||
</p>
|
||
<div class="lisp">
|
||
<pre class="lisp">(add-to-list 'package-archives '("org" . "https://orgmode.org/elpa/") t)
|
||
</pre></div>
|
||
|
||
<p>Once you have added your preferred archive, you need to update the
|
||
local package list using:
|
||
</p>
|
||
<div class="example">
|
||
<pre class="example">M-x package-refresh-contents RET
|
||
</pre></div>
|
||
|
||
<p>Once you have done that, you can install Org-roam and its dependencies
|
||
using:
|
||
</p>
|
||
<div class="example">
|
||
<pre class="example">M-x package-install RET org-roam RET
|
||
</pre></div>
|
||
|
||
<p>Now see <a href="#Post_002dInstallation-Tasks">Post-Installation Tasks</a>.
|
||
</p>
|
||
<hr>
|
||
<span id="Installing-from-Apt"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Installing-from-the-Git-Repository" accesskey="n" rel="next">Installing from the Git Repository</a>, Previous: <a href="#Installing-from-MELPA" accesskey="p" rel="prev">Installing from MELPA</a>, Up: <a href="#Installation" accesskey="u" rel="up">Installation</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Installing-from-Apt-1"></span><h3 class="section">4.2 Installing from Apt</h3>
|
||
|
||
<p>Users of Debian 11 or later or Ubuntu 20.10 or later can simply install Org-roam
|
||
using Apt:
|
||
</p>
|
||
<div class="example">
|
||
<pre class="example">apt-get install elpa-org-roam
|
||
</pre></div>
|
||
|
||
<p>Org-roam will then be autoloaded into Emacs.
|
||
</p>
|
||
<hr>
|
||
<span id="Installing-from-the-Git-Repository"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Post_002dInstallation-Tasks" accesskey="n" rel="next">Post-Installation Tasks</a>, Previous: <a href="#Installing-from-Apt" accesskey="p" rel="prev">Installing from Apt</a>, Up: <a href="#Installation" accesskey="u" rel="up">Installation</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Installing-from-the-Git-Repository-1"></span><h3 class="section">4.3 Installing from the Git Repository</h3>
|
||
|
||
<p>You may install Org-roam directly from the repository on <a href="https://github.com/org-roam/org-roam">GitHub</a> if you like.
|
||
This will give you access to the latest version hours or days before it appears
|
||
on MELPA, and months (or more) before it is added to the Debian or Ubuntu
|
||
repositories. This will also give you access to various developmental branches
|
||
that may be available.
|
||
</p>
|
||
<p>Note, however, that development version, and especially any feature branches,
|
||
may not always be in working order. You’ll need to be prepared to do some
|
||
debugging, or to manually roll-back to working versions, if you install from
|
||
GitHub.
|
||
</p>
|
||
<p>Installing from GitHub requires that you clone the repository:
|
||
</p>
|
||
<div class="example">
|
||
<pre class="example">git clone https://github.com/org-roam/org-roam.git /path/to/org/roam
|
||
</pre></div>
|
||
|
||
<p>where <code>./path/to/org/roam</code> is the location you will store your copy of the code.
|
||
</p>
|
||
<p>Next, you need to add this location to your load path, and <code>require</code> the
|
||
Org-roam library. Add the following code to your <code>.emacs</code>:
|
||
</p>
|
||
<div class="lisp">
|
||
<pre class="lisp">(add-to-list 'load-path "/path/to/org/roam")
|
||
(require 'org-roam)
|
||
</pre></div>
|
||
|
||
<p>You now have Org-roam installed. However, you don’t necessarily have the
|
||
dependencies that it requires. These include:
|
||
</p>
|
||
<ul>
|
||
<li> dash
|
||
|
||
</li><li> f
|
||
|
||
</li><li> s
|
||
|
||
</li><li> org
|
||
|
||
</li><li> emacsql
|
||
|
||
</li><li> emacsql-sqlite3
|
||
</li></ul>
|
||
|
||
<p>You can install this manually as well, or get the latest version from MELPA. You
|
||
may wish to use <a href="https://github.com/jwiegley/use-package">use-package</a>, <a href="https://github.com/raxod502/straight.el">straight.el</a> to help manage this.
|
||
</p>
|
||
<p>If you would like to install the manual for access from Emacs’ built-in Info
|
||
system, you’ll need to compile the .texi source file, and install it in an
|
||
appropriate location.
|
||
</p>
|
||
<p>To compile the .texi source file, from a terminal navigate to the <code>/doc</code>
|
||
subdirectory of the Org-roam repository, and run the following:
|
||
</p>
|
||
<div class="example">
|
||
<pre class="example">make infodir=/path/to/my/info/files install-info
|
||
</pre></div>
|
||
|
||
<p>Where <code>/path/to/my/info/files</code> is the location where you keep info files. This
|
||
target directory needs to be stored in the variable
|
||
‘Info-default-directory-list‘. If you aren’t using one of the default info
|
||
locations, you can configure this with the following in your <code>.emacs</code> file:
|
||
</p>
|
||
<div class="lisp">
|
||
<pre class="lisp">(require 'info)
|
||
(add-to-list 'Info-default-directory-list
|
||
"/path/to/my/info/files")
|
||
</pre></div>
|
||
|
||
<p>You can also use one of the default locations, such as:
|
||
</p>
|
||
<ul>
|
||
<li> <em>usr/local/share/info</em>
|
||
|
||
</li><li> <em>usr/share/info</em>
|
||
|
||
</li><li> <em>usr/local/share/info</em>
|
||
</li></ul>
|
||
|
||
<p>If you do this, you’ll need to make sure you have write-access to that location,
|
||
or run the above <code>make</code> command as root.
|
||
</p>
|
||
<p>Now that the info file is ready, you need to add it to the corresponding <code>dir</code>
|
||
file:
|
||
</p>
|
||
<div class="example">
|
||
<pre class="example">install-info /path/to/my/info/files/org-roam.info /path/to/my/info/files/dir
|
||
</pre></div>
|
||
|
||
<hr>
|
||
<span id="Post_002dInstallation-Tasks"></span><div class="header">
|
||
<p>
|
||
Previous: <a href="#Installing-from-the-Git-Repository" accesskey="p" rel="prev">Installing from the Git Repository</a>, Up: <a href="#Installation" accesskey="u" rel="up">Installation</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Post_002dInstallation-Tasks-1"></span><h3 class="section">4.4 Post-Installation Tasks</h3>
|
||
|
||
<p>Org-roam uses <code>emacsql-sqlite3</code>, which requires <code>sqlite3</code> to be located on
|
||
<code>exec-path</code>. Please ensure that <code>sqlite3</code> is installed appropriately on your
|
||
operating system. You can verify that this is the case by executing:
|
||
</p>
|
||
<div class="lisp">
|
||
<pre class="lisp">(executable-find "sqlite3")
|
||
</pre></div>
|
||
|
||
<p>If you have <code>sqlite3</code> installed, and <code>executable-find</code> still reports <code>nil</code>, then
|
||
it is likely that the path to the executable is not a member of the Emacs
|
||
variable <code>exec-path</code>. You may rectify this by manually adding the path within
|
||
your Emacs configuration:
|
||
</p>
|
||
<div class="lisp">
|
||
<pre class="lisp">(add-to-list 'exec-path "path/to/sqlite3")
|
||
</pre></div>
|
||
|
||
<hr>
|
||
<span id="Getting-Started"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Files" accesskey="n" rel="next">Files</a>, Previous: <a href="#Installation" accesskey="p" rel="prev">Installation</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Getting-Started-1"></span><h2 class="chapter">5 Getting Started</h2>
|
||
|
||
<p>This short tutorial describes the essential commands used in Org-roam, to help
|
||
you get started.
|
||
</p>
|
||
<p>First, it is important to understand how Org-roam was designed. Org-roam was
|
||
built to support a workflow that was not possible with vanilla Org-mode. This
|
||
flow is modelled after the <a href="https://zettelkasten.de/">Zettelkasten Method</a>, and many of <a href="https://roamresearch.com">Roam Research’s</a>
|
||
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 <a href="#Note_002dtaking-Workflows">Note-taking Workflows</a>.
|
||
</p>
|
||
<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 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")
|
||
(setq org-roam-directory "~/org-roam")
|
||
</pre></div>
|
||
|
||
<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 <code>org-roam-directory</code> for notes.
|
||
Instead of relying on the file hierarchy for any form of categorization, one
|
||
should use links between files to establish connections between notes.
|
||
</p>
|
||
<p>Next, we need to enable the global minor mode <code>org-roam-mode</code>. This sets up
|
||
Emacs with several hooks, building a cache that is kept consistent as your
|
||
slip-box grows. We recommend 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 <code>M-x org-roam-db-build-cache</code>. Cache
|
||
builds may take a while the first time, but is often instantaneous in subsequent
|
||
runs because it only reprocesses modified files.
|
||
</p>
|
||
<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 <code>RET</code> should begin the note
|
||
creation process. This process uses <code>org-capture</code>’s templating system, and can
|
||
be customized (see <a href="#The-Templating-System">The Templating System</a>). Using the default template, pressing
|
||
<code>C-c C-c</code> finishes the note capture.
|
||
</p>
|
||
<p>By default, Org-roam updates the cache asynchronously in the background to
|
||
avoid getting in the way of writing. Org-roam queues updates to the files,
|
||
waits for you to be idle for 2 seconds, and then automatically triggers
|
||
updating the cache. After the cache has been updated, 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 <a id="DOCF2" href="#FOOT2"><sup>2</sup></a>. One can customize the waiting
|
||
time by setting <code>org-roam-db-update-idle-seconds</code>; or change the cache update
|
||
to be triggered immediately after buffer save by setting
|
||
<code>org-roam-db-update-method</code> to <code>'immediate</code>.
|
||
</p>
|
||
<p>For experienced <code>org-capture</code> users, the behavior of <code>M-x org-roam-find-file</code>
|
||
may seem unfamiliar: after finishing a capture with <code>C-c C-c</code>, you are returned
|
||
not to the original buffer from which you called <code>M-x org-roam-find-file</code>, but
|
||
to a buffer pointing to the note you just created. For the usual <code>org-capture</code>
|
||
behavior you can call <code>M-x org-roam-capture</code> instead of <code>M-x org-roam-find-file</code>.
|
||
</p>
|
||
<p>Org-roam makes it easy to create notes, and link them together. 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 files: this
|
||
facilitates building up a dense graph of inter-connected 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 <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
|
||
as nodes, and links between them as edges. The generated graph can be used to
|
||
navigate to the files, but this requires some additional setup (see <a href="#Roam-Protocol">Roam Protocol</a>).
|
||
</p>
|
||
<hr>
|
||
<span id="Files"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#The-Templating-System" accesskey="n" rel="next">The Templating System</a>, Previous: <a href="#Getting-Started" accesskey="p" rel="prev">Getting Started</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Files-1"></span><h2 class="chapter">6 Files</h2>
|
||
|
||
<p>In Org-roam, notes typically consist of multiple files, where each file is a
|
||
zettel.
|
||
</p>
|
||
<p>While the bulk of Org-roam’s functionality is built on top of vanilla Org-mode,
|
||
Org-roam adds several Org-roam-specific keywords to support additional
|
||
functionality.
|
||
</p>
|
||
<p>This section explains the important components of a file, and the extensions to
|
||
Org-mode.
|
||
</p>
|
||
<table class="menu" border="0" cellspacing="0">
|
||
<tr><td align="left" valign="top">• <a href="#File-Titles" accesskey="1">File Titles</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#File-Tags" accesskey="2">File Tags</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#File-Refs" accesskey="3">File Refs</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
</table>
|
||
|
||
<hr>
|
||
<span id="File-Titles"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#File-Tags" accesskey="n" rel="next">File Tags</a>, Up: <a href="#Files" accesskey="u" rel="up">Files</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="File-Titles-1"></span><h3 class="section">6.1 File Titles</h3>
|
||
|
||
<p>To easily find a note, a title needs to be prescribed to a note.
|
||
</p>
|
||
<p>A note can have many titles: this allows a note to be referred to by different
|
||
names, which is 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 <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>
|
||
<ul>
|
||
<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></ul>
|
||
|
||
<p>Take for example the following org file:
|
||
</p>
|
||
<div class="example">
|
||
<pre class="example">#+title: World War 2
|
||
#+roam_alias: "WWII" "World War II"
|
||
|
||
* Headline
|
||
</pre></div>
|
||
|
||
<table>
|
||
<thead><tr><th>Method</th><th>Titles</th></tr></thead>
|
||
<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>If no title is provided, Org-roam defaults to using the file-path.
|
||
</p>
|
||
<table class="menu" border="0" cellspacing="0">
|
||
<tr><td align="left" valign="top">• <a href="#Customizing-Title-Extraction" accesskey="1">Customizing Title Extraction</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
</table>
|
||
|
||
<hr>
|
||
<span id="Customizing-Title-Extraction"></span><div class="header">
|
||
<p>
|
||
Up: <a href="#File-Titles" accesskey="u" rel="up">File Titles</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Customizing-Title-Extraction-1"></span><h4 class="subsection">6.1.1 Customizing Title Extraction</h4>
|
||
|
||
<p>To control how Org-roam extracts titles, customize <code>org-roam-title-sources</code>. If
|
||
all methods of title extraction return no results, the file-name is used as the
|
||
note’s title.
|
||
</p>
|
||
<dl>
|
||
<dt id="index-org_002droam_002dtitle_002dsources">User Option: <strong>org-roam-title-sources</strong></dt>
|
||
<dd>
|
||
<p>The list of sources from which to retrieve a note title.
|
||
Each element in the list is either:
|
||
</p></dd></dl>
|
||
|
||
<ul>
|
||
<li> a symbol – this symbol corresponds to a title retrieval function, which
|
||
returns the list of titles for the current buffer
|
||
<ul>
|
||
<li> a list of symbols – symbols in the list are treated as with (1). The
|
||
return value of this list is the first symbol in the list returning a
|
||
non-nil value.
|
||
</li></ul>
|
||
|
||
<p>The return results of the root list are concatenated.
|
||
</p>
|
||
<p>For example the setting: ’((title headline) alias) means the following:
|
||
</p>
|
||
<ul>
|
||
<li> Return the ’title + ’alias, if the title of current buffer is non-empty;
|
||
|
||
</li><li> Or return ’headline + ’alias otherwise.
|
||
</li></ul>
|
||
|
||
<p>The currently supported symbols are:
|
||
</p>
|
||
<p><code>'title</code>
|
||
The <code>#+title</code> property of org file.
|
||
</p>
|
||
<p><code>'alias</code>
|
||
The <code>#+roam_alias</code> property of the org file, using
|
||
space-delimited strings.
|
||
</p>
|
||
<p><code>'headline</code>
|
||
The first headline in the org file.
|
||
</p></li></ul>
|
||
|
||
<p>Adding your own title extraction method requires two steps. First, define a
|
||
method <code>(defun org-roam--extract-titles-foo () ...)</code>, where <code>foo</code> a
|
||
self-prescribed name for the title extraction method. This method takes no
|
||
arguments, and returns a list of strings (titles). Finally, push the symbol
|
||
<code>foo</code> into <code>org-roam-title-sources</code>. You may need to rebuild the cache from
|
||
scratch to re-process all files to pick up the new titles.
|
||
</p>
|
||
<hr>
|
||
<span id="File-Tags"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#File-Refs" accesskey="n" rel="next">File Refs</a>, Previous: <a href="#File-Titles" accesskey="p" rel="prev">File Titles</a>, Up: <a href="#Files" accesskey="u" rel="up">Files</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="File-Tags-1"></span><h3 class="section">6.2 File Tags</h3>
|
||
|
||
<p>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.
|
||
</p>
|
||
<p>By default, tags are extracted from the <code>#+roam_tags</code> property. To add
|
||
additional extraction methods, see <a href="#Customizing-Tag-Extraction">Customizing Tag Extraction</a>.
|
||
</p>
|
||
<table class="menu" border="0" cellspacing="0">
|
||
<tr><td align="left" valign="top">• <a href="#Customizing-Tag-Extraction" accesskey="1">Customizing Tag Extraction</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
</table>
|
||
|
||
<hr>
|
||
<span id="Customizing-Tag-Extraction"></span><div class="header">
|
||
<p>
|
||
Up: <a href="#File-Tags" accesskey="u" rel="up">File Tags</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Customizing-Tag-Extraction-1"></span><h4 class="subsection">6.2.1 Customizing Tag Extraction</h4>
|
||
|
||
<p>Org-roam calls <code>org-roam--extract-tags</code> to extract tags from files. The variable
|
||
<code>org-roam-tag-sources</code>, to control how tags are extracted.
|
||
</p>
|
||
<dl>
|
||
<dt id="index-org_002droam_002dtag_002dsources">User Option: <strong>org-roam-tag-sources</strong></dt>
|
||
</dl>
|
||
|
||
<p>Sources to obtain tags from.
|
||
</p>
|
||
<p>It should be a list of symbols representing any of the following extraction
|
||
methods:
|
||
</p>
|
||
<p><code>'prop</code>
|
||
Extract tags from the <code>#+roam_tags</code> property.
|
||
Tags are space delimited.
|
||
Tags may contain spaces if they are double-quoted.
|
||
e.g. <code>#+roam_tags: TAG "tag with spaces"</code>
|
||
</p>
|
||
<p><code>'vanilla</code>
|
||
Extract vanilla org-mode tags, including <code>#+FILETAGS</code> and
|
||
inherited tags.
|
||
</p>
|
||
<p><code>'all-directories</code>
|
||
Extract sub-directories relative to <code>org-roam-directory</code>.
|
||
That is, if a file is located at relative path foo/bar/file.org,
|
||
the file will have tags “foo” and “bar”.
|
||
</p>
|
||
<p><code>'last-directory</code>
|
||
Extract the last directory relative to ‘org-roam-directory’.
|
||
That is, if a file is located at relative path foo/bar/file.org,
|
||
the file will have tag \“bar\”.
|
||
</p>
|
||
<p><code>'first-directory</code>
|
||
Extract the first directory relative to <code>org-roam-directory</code>.
|
||
That is, if a file is located at relative path foo/bar/file.org,
|
||
the file will have tag “foo”
|
||
</p>
|
||
<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>, for example:
|
||
</p>
|
||
<div class="lisp">
|
||
<pre class="lisp">(setq org-roam-tag-sources '(prop last-directory))
|
||
</pre></div>
|
||
|
||
<p>Adding your own tag extraction method requires two steps. First, define a method
|
||
<code>(defun org-roam--extract-tags-foo (file) ...)</code>, where <code>foo</code> a self-prescribed
|
||
name for the tag extraction method. This method takes the file path as an
|
||
argument, and returns a list of strings (titles). Finally, push the symbol <code>foo</code>
|
||
into <code>org-roam-tag-sources</code>. You may need to rebuild the cache from scratch to
|
||
re-process all files to pick up the new tags.
|
||
</p>
|
||
<hr>
|
||
<span id="File-Refs"></span><div class="header">
|
||
<p>
|
||
Previous: <a href="#File-Tags" accesskey="p" rel="prev">File Tags</a>, Up: <a href="#Files" accesskey="u" rel="up">Files</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="File-Refs-1"></span><h3 class="section">6.3 File Refs</h3>
|
||
|
||
<p>Refs are unique identifiers for files. For example, a note for a website may
|
||
contain a ref:
|
||
</p>
|
||
<div class="example">
|
||
<pre class="example">#+title: Google
|
||
#+roam_key: https://www.google.com/
|
||
</pre></div>
|
||
|
||
<p>These keys allow references to the key to show up in the backlinks buffer. For
|
||
instance, with the example above, if another file then links to
|
||
<a href="https://www.google.com">https://www.google.com</a>, that will show up as a “Ref Backlink”.
|
||
</p>
|
||
<p>These keys also come in useful for when taking website notes, using the
|
||
<code>roam-ref</code> protocol (see <a href="#Roam-Protocol">Roam Protocol</a>).
|
||
</p>
|
||
<p><a href="https://github.com/jkitchin/org-ref">org-ref</a> citation keys can also be used as refs:
|
||
</p>
|
||
<div class="example">
|
||
<pre class="example">#+title: Neural Ordinary Differential Equations
|
||
#+roam_key: cite:chen18_neural_ordin_differ_equat
|
||
</pre></div>
|
||
|
||
<div class="float">
|
||
<img src="images/org-ref-citelink.png" alt="images/org-ref-citelink">
|
||
|
||
<div class="float-caption"><p><strong>Figure: </strong>org-ref-citelink</p></div></div>
|
||
<p>You may assign multiple refs to a single file, for example when you want
|
||
multiple papers in a series to share the same note, or an article has a citation
|
||
key and a URL at the same time.
|
||
</p>
|
||
<hr>
|
||
<span id="The-Templating-System"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Concepts-and-Configuration" accesskey="n" rel="next">Concepts and Configuration</a>, Previous: <a href="#Files" accesskey="p" rel="prev">Files</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="The-Templating-System-1"></span><h2 class="chapter">7 The Templating System</h2>
|
||
|
||
<p>Rather than creating blank files on <code>org-roam-insert</code> and <code>org-roam-find-file</code>,
|
||
it may be desirable to prefill the file with templated content. This may
|
||
include:
|
||
</p>
|
||
<ul>
|
||
<li> Time of creation
|
||
|
||
</li><li> File it was created from
|
||
|
||
</li><li> Clipboard content
|
||
|
||
</li><li> Any other data you may want to input manually
|
||
</li></ul>
|
||
|
||
<p>This requires a complex template insertion system. Fortunately, Org ships with a
|
||
powerful one: <code>org-capture</code> (see <a href="https://www.gnu.org/software/emacs/manual/html_mono/org.html#capture">(org)capture</a>). However, org-capture was not
|
||
designed for such use. Org-roam abuses <code>org-capture</code>, extending its syntax and
|
||
capabilities. To first understand how org-roam’s templating system works, it may
|
||
be useful to look into basic usage of <code>org-capture</code>.
|
||
</p>
|
||
<p>For these reasons, Org-roam capture templates are not compatible with regular
|
||
<code>org-capture</code>. Hence, Org-roam’s templates can be customized by instead
|
||
modifying the variable <code>org-roam-capture-templates</code>. Just like
|
||
<code>org-capture-templates</code>, <code>org-roam-capture-templates</code> can contain multiple
|
||
templates. If <code>org-roam-capture-templates</code> only contains one template, there
|
||
will be no prompt for template selection.
|
||
</p>
|
||
<table class="menu" border="0" cellspacing="0">
|
||
<tr><td align="left" valign="top">• <a href="#Template-Walkthrough" accesskey="1">Template Walkthrough</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Org_002droam-Template-Expansion" accesskey="2">Org-roam Template Expansion</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
</table>
|
||
|
||
<hr>
|
||
<span id="Template-Walkthrough"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Org_002droam-Template-Expansion" accesskey="n" rel="next">Org-roam Template Expansion</a>, Up: <a href="#The-Templating-System" accesskey="u" rel="up">The Templating System</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Template-Walkthrough-1"></span><h3 class="section">7.1 Template Walkthrough</h3>
|
||
|
||
<p>To demonstrate the additions made to org-capture templates. Here, we walkthrough
|
||
the default template, reproduced below.
|
||
</p>
|
||
<div class="lisp">
|
||
<pre class="lisp">("d" "default" plain (function org-roam--capture-get-point)
|
||
"%?"
|
||
:file-name "%<%Y%m%d%H%M%S>-${slug}"
|
||
:head "#+title: ${title}\n"
|
||
:unnarrowed t)
|
||
</pre></div>
|
||
|
||
<ul>
|
||
<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 <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> <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
|
||
<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 <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> <code>:unnarrowed t</code> tells org-capture to show the contents for the whole
|
||
file, rather than narrowing to just the entry.
|
||
</li></ul>
|
||
|
||
<p>Other options you may want to learn about include <code>:immediate-finish</code>.
|
||
</p>
|
||
<hr>
|
||
<span id="Org_002droam-Template-Expansion"></span><div class="header">
|
||
<p>
|
||
Previous: <a href="#Template-Walkthrough" accesskey="p" rel="prev">Template Walkthrough</a>, Up: <a href="#The-Templating-System" accesskey="u" rel="up">The Templating System</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Org_002droam-Template-Expansion-1"></span><h3 class="section">7.2 Org-roam Template Expansion</h3>
|
||
|
||
<p>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 <a href="#Template-Walkthrough">Template
|
||
Walkthrough</a>.
|
||
</p>
|
||
<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 <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:
|
||
<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 <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">
|
||
<pre class="lisp">("d" "default" plain (function org-roam--capture-get-point)
|
||
"%?"
|
||
:file-name "%(format-time-string \"%Y-%m-%d--%H-%M-%SZ--${slug}\" (current-time) t)"
|
||
:head "#+title: ${title}\n"
|
||
:unnarrowed t)
|
||
</pre></div>
|
||
|
||
<hr>
|
||
<span id="Concepts-and-Configuration"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Inserting-Links" accesskey="n" rel="next">Inserting Links</a>, Previous: <a href="#The-Templating-System" accesskey="p" rel="prev">The Templating System</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Concepts-and-Configuration-1"></span><h2 class="chapter">8 Concepts and Configuration</h2>
|
||
|
||
<p>The number of configuration options is deliberately kept small, to keep 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 <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" accesskey="1">Directories and Files</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#The-Org_002droam-Buffer" accesskey="2">The Org-roam Buffer</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Org_002droam-Files" accesskey="3">Org-roam Files</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Org_002droam-Faces" accesskey="4">Org-roam Faces</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#The-Database" accesskey="5">The Database</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
</table>
|
||
|
||
<hr>
|
||
<span id="Directories-and-Files"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#The-Org_002droam-Buffer" accesskey="n" rel="next">The Org-roam Buffer</a>, Up: <a href="#Concepts-and-Configuration" accesskey="u" rel="up">Concepts and Configuration</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Directories-and-Files-1"></span><h3 class="section">8.1 Directories and Files</h3>
|
||
|
||
<p>This section concerns the placement and creation of files.
|
||
</p>
|
||
<dl>
|
||
<dt id="index-org_002droam_002ddirectory">Variable: <strong>org-roam-directory</strong></dt>
|
||
<dd>
|
||
<p>This is the default path to Org-roam files. All Org files, at any level of
|
||
nesting, are considered part of the Org-roam.
|
||
</p></dd></dl>
|
||
|
||
<dl>
|
||
<dt id="index-org_002droam_002ddb_002dlocation">Variable: <strong>org-roam-db-location</strong></dt>
|
||
<dd>
|
||
<p>Location of the Org-roam database. If this is non-nil, the Org-roam sqlite
|
||
database is saved here.
|
||
</p>
|
||
<p>It is the user’s responsibility to set this correctly, especially when used
|
||
with multiple Org-roam instances.
|
||
</p></dd></dl>
|
||
|
||
<dl>
|
||
<dt id="index-org_002droam_002dfile_002dexclude_002dregexp">Variable: <strong>org-roam-file-exclude-regexp</strong></dt>
|
||
<dd>
|
||
<p>Files matching this regular expression are excluded from the Org-roam.
|
||
</p></dd></dl>
|
||
|
||
<hr>
|
||
<span id="The-Org_002droam-Buffer"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Org_002droam-Files" accesskey="n" rel="next">Org-roam Files</a>, Previous: <a href="#Directories-and-Files" accesskey="p" rel="prev">Directories and Files</a>, Up: <a href="#Concepts-and-Configuration" accesskey="u" rel="up">Concepts and Configuration</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="The-Org_002droam-Buffer-1"></span><h3 class="section">8.2 The Org-roam Buffer</h3>
|
||
|
||
<p>The Org-roam buffer displays backlinks for the currently active Org-roam note.
|
||
</p>
|
||
<dl>
|
||
<dt id="index-org_002droam_002dbuffer">User Option: <strong>org-roam-buffer</strong></dt>
|
||
<dd>
|
||
<p>The name of the org-roam buffer. Defaults to <code>*org-roam*</code>.
|
||
</p></dd></dl>
|
||
|
||
<dl>
|
||
<dt id="index-org_002droam_002dbuffer_002dposition">User Option: <strong>org-roam-buffer-position</strong></dt>
|
||
<dd>
|
||
<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></dd></dl>
|
||
|
||
<dl>
|
||
<dt id="index-org_002droam_002dbuffer_002dwidth">User Option: <strong>org-roam-buffer-width</strong></dt>
|
||
<dd>
|
||
<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></dd></dl>
|
||
|
||
<dl>
|
||
<dt id="index-org_002droam_002dbuffer_002dheight">User Option: <strong>org-roam-buffer-height</strong></dt>
|
||
<dd>
|
||
<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></dd></dl>
|
||
|
||
<dl>
|
||
<dt id="index-org_002droam_002dbuffer_002dwindow_002dparameters">User Option: <strong>org-roam-buffer-window-parameters</strong></dt>
|
||
<dd>
|
||
<p>Additional window parameters for the org-roam-buffer side window.
|
||
</p>
|
||
<p>For example one can prevent the window from being deleted when calling
|
||
<code>delete-other-windows</code>, by setting it with the following:
|
||
</p>
|
||
<p><code>(setq org-roam-buffer-window-parameters '((no-delete-other-windows . t)))</code>
|
||
</p></dd></dl>
|
||
|
||
<hr>
|
||
<span id="Org_002droam-Files"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Org_002droam-Faces" accesskey="n" rel="next">Org-roam Faces</a>, Previous: <a href="#The-Org_002droam-Buffer" accesskey="p" rel="prev">The Org-roam Buffer</a>, Up: <a href="#Concepts-and-Configuration" accesskey="u" rel="up">Concepts and Configuration</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Org_002droam-Files-1"></span><h3 class="section">8.3 Org-roam Files</h3>
|
||
|
||
<p>Org-roam files are created and prefilled using Org-roam’s templating
|
||
system. The templating system is customizable (see <a href="#The-Templating-System">The Templating System</a>).
|
||
</p>
|
||
<hr>
|
||
<span id="Org_002droam-Faces"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#The-Database" accesskey="n" rel="next">The Database</a>, Previous: <a href="#Org_002droam-Files" accesskey="p" rel="prev">Org-roam Files</a>, Up: <a href="#Concepts-and-Configuration" accesskey="u" rel="up">Concepts and Configuration</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Org_002droam-Faces-1"></span><h3 class="section">8.4 Org-roam Faces</h3>
|
||
|
||
<p>Org-roam introduces several faces to distinguish links within the same buffer.
|
||
These faces are enabled by default in Org-roam notes.
|
||
</p>
|
||
<dl>
|
||
<dt id="index-org_002droam_002dlink_002duse_002dcustom_002dfaces">User Option: <strong>org-roam-link-use-custom-faces</strong></dt>
|
||
<dd>
|
||
<p>When <code>t</code>, use custom faces only inside Org-roam notes.
|
||
When <code>everywhere</code>, the custom face is applied additionally to non Org-roam notes.
|
||
When <code>nil</code>, do not use Org-roam’s custom faces.
|
||
</p></dd></dl>
|
||
|
||
<p>The <code>org-roam-link</code> face is the face applied to links to other Org-roam files.
|
||
This distinguishes internal links from external links (e.g. external web links).
|
||
</p>
|
||
<p>The <code>org-roam-link-current</code> face corresponds to links to the same file it is in.
|
||
</p>
|
||
<p>The <code>org-roam-link-invalid</code> face is applied to links that are broken. These are
|
||
links to files or IDs that cannot be found.
|
||
</p>
|
||
<hr>
|
||
<span id="The-Database"></span><div class="header">
|
||
<p>
|
||
Previous: <a href="#Org_002droam-Faces" accesskey="p" rel="prev">Org-roam Faces</a>, Up: <a href="#Concepts-and-Configuration" accesskey="u" rel="up">Concepts and Configuration</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="TODO-The-Database"></span><h3 class="section">8.5 <strong>TODO</strong> The Database</h3>
|
||
|
||
<p>Org-roam is backed by a Sqlite database.
|
||
</p>
|
||
<dl>
|
||
<dt id="index-org_002droam_002ddb_002dupdate_002dmethod">User Option: <strong>org-roam-db-update-method</strong></dt>
|
||
<dd>
|
||
<p>Method to update the Org-roam database.
|
||
</p>
|
||
<p><code>'immediate</code>: Update the database immediately upon file changes.
|
||
</p>
|
||
<p><code>'idle-timer</code>: Updates the database if dirty, if Emacs idles for
|
||
<code>org-roam-db-update-idle-seconds</code>.
|
||
</p></dd></dl>
|
||
|
||
<dl>
|
||
<dt id="index-org_002droam_002ddb_002dupdate_002didle_002dseconds">User Option: <strong>org-roam-db-update-idle-seconds</strong></dt>
|
||
<dd>
|
||
<p>Number of idle seconds before triggering an Org-roam database update. This is
|
||
only valid if <code>org-roam-db-update-method</code> is <code>'idle-timer</code>.
|
||
</p></dd></dl>
|
||
|
||
<hr>
|
||
<span id="Inserting-Links"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Completions" accesskey="n" rel="next">Completions</a>, Previous: <a href="#Concepts-and-Configuration" accesskey="p" rel="prev">Concepts and Configuration</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Inserting-Links-1"></span><h2 class="chapter">9 Inserting Links</h2>
|
||
|
||
<p>The preferred mode of linking is via <code>file</code> links to files, and <code>id</code> links for
|
||
headlines. This maintains the strongest compatibility with Org-mode, ensuring
|
||
that the links still function without Org-roam, and work well exporting to other
|
||
backends.
|
||
</p>
|
||
<p><code>file</code> links can be inserted via <code>org-roam-insert</code>. Links to headlines can be
|
||
inserted by navigating to the desired headline and calling <code>org-store-link</code>.
|
||
This will create an ID for the headline if it does not already exist, and
|
||
populate the Org-roam database. The link can then be inserted via
|
||
<code>org-insert-link</code>.
|
||
</p>
|
||
<p>An alternative mode of insertion is using Org-roam’s <code>roam</code> links. Org-roam
|
||
registers this link type, and interprets the path as follows:
|
||
</p>
|
||
<ul>
|
||
<li> <code>[[roam:title]]</code>links to an Org-roam file with title or alias “title”
|
||
|
||
</li><li> <code>[[roam:*headline]]</code>links to the headline “headline” in the current
|
||
Org-roam file
|
||
|
||
</li><li> <code>[[roam:title*headline]]</code>links to the headline “headline” in the Org-roam
|
||
file with title or alias “title”
|
||
|
||
</li></ul>
|
||
|
||
<dl>
|
||
<dt id="index-org_002droam_002dlink_002dtitle_002dformat">User Option: <strong>org-roam-link-title-format</strong></dt>
|
||
<dd>
|
||
<p>To distinguish between org-roam links and regular links, one may choose to use
|
||
special indicators for Org-roam links. Defaults to <code>"%s"</code>.
|
||
</p>
|
||
<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></dd></dl>
|
||
|
||
<dl>
|
||
<dt id="index-org_002droam_002dlink_002dauto_002dreplace">User Option: <strong>org-roam-link-auto-replace</strong></dt>
|
||
<dd>
|
||
<p>When non-nil, <code>roam</code> links will be replaced with <code>file</code> or <code>id</code> links when
|
||
they are navigated to, and on file save, when a match is found. This is
|
||
desirable to maintain compatibility with vanilla Org, but resolved links are
|
||
harder to edit. Defaults to <code>t</code>.
|
||
</p></dd></dl>
|
||
|
||
<hr>
|
||
<span id="Completions"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Navigating-Around" accesskey="n" rel="next">Navigating Around</a>, Previous: <a href="#Inserting-Links" accesskey="p" rel="prev">Inserting Links</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Completions-1"></span><h2 class="chapter">10 Completions</h2>
|
||
|
||
<p>Completions for Org-roam are provided via <code>completion-at-point</code>. Completion
|
||
suggestions are implemented as separate functions. Org-roam installs all
|
||
functions in <code>org-roam-completion-functions</code> to <code>completion-at-point-functions</code>.
|
||
</p>
|
||
<dl>
|
||
<dt id="index-org_002droam_002dcompletion_002dfunctions">Variable: <strong>org-roam-completion-functions</strong></dt>
|
||
<dd>
|
||
<p>The list of functions to be used with <code>completion-at-point</code>.
|
||
</p></dd></dl>
|
||
|
||
<dl>
|
||
<dt id="index-org_002droam_002dcompletion_002dignore_002dcase">User Option: <strong>org-roam-completion-ignore-case</strong></dt>
|
||
<dd>
|
||
<p>When non-nil, the <code>roam</code> link completions are ignore case. For example,
|
||
calling <code>completion-at-point</code> within <code>[[roam:fo]]</code> will present a completion
|
||
for a file with title “Foo”. Defaults to <code>t</code>.
|
||
</p></dd></dl>
|
||
|
||
<p>To use the completions from Org-roam with <code>company-mode</code>, prepend <code>company-capf</code>
|
||
to variable <code>company-backends</code>.
|
||
</p>
|
||
<table class="menu" border="0" cellspacing="0">
|
||
<tr><td align="left" valign="top">• <a href="#Link-Completion" accesskey="1">Link Completion</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Tag-Completion" accesskey="2">Tag Completion</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
</table>
|
||
|
||
<hr>
|
||
<span id="Link-Completion"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Tag-Completion" accesskey="n" rel="next">Tag Completion</a>, Up: <a href="#Completions" accesskey="u" rel="up">Completions</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Link-Completion-1"></span><h3 class="section">10.1 Link Completion</h3>
|
||
|
||
<p><code>roam</code> links support auto-completion via <code>completion-at-point</code>: simply call
|
||
<code>M-x completion-at-point</code> within a roam link. That is, where the <code>|</code> character
|
||
represents the cursor:
|
||
</p>
|
||
<ul>
|
||
<li> <code>[[|]]</code>: completes for a file title
|
||
|
||
</li><li> <code>[[roam:]]</code>: completes for a file title
|
||
|
||
</li><li> <code>[[*|]]</code>: completes for a headline within this file
|
||
|
||
</li><li> <code>[[foo*|]]</code>: completes a headline within the file with title “foo”
|
||
|
||
</li><li> <code>[[roam:foo*|]]</code> completes a headline within the file with title “foo”
|
||
</li></ul>
|
||
|
||
<p>Completions account for the current input. For example, for <code>[[f|]]</code>, the
|
||
completions (by default) only show for files with titles that start with “f”.
|
||
</p>
|
||
<dl>
|
||
<dt id="index-org_002droam_002dlink_002dcomplete_002dat_002dpoint">Function: <strong>org-roam-link-complete-at-point</strong></dt>
|
||
<dd>
|
||
<p>Do appropriate completion for the link at point.
|
||
</p></dd></dl>
|
||
|
||
<table class="menu" border="0" cellspacing="0">
|
||
<tr><td align="left" valign="top">• <a href="#Link-Completions-Everywhere" accesskey="1">Link Completions Everywhere</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
</table>
|
||
|
||
<hr>
|
||
<span id="Link-Completions-Everywhere"></span><div class="header">
|
||
<p>
|
||
Up: <a href="#Link-Completion" accesskey="u" rel="up">Link Completion</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Link-Completions-Everywhere-1"></span><h4 class="subsection">10.1.1 Link Completions Everywhere</h4>
|
||
|
||
<p>Org-roam is able to provide completions from the current word at point, enabling
|
||
as-you-type link completions. However, this is disabled by default: the author
|
||
believes that linking should be a deliberate action and linking should be
|
||
performed with great care.
|
||
</p>
|
||
<p>Setting <code>org-roam-completion-everywhere</code> to <code>t</code> will enable word-at-point
|
||
completions.
|
||
</p>
|
||
<dl>
|
||
<dt id="index-org_002droam_002dcompletion_002deverywhere">User Option: <strong>org-roam-completion-everywhere</strong></dt>
|
||
<dd>
|
||
<p>If non-nil, provide completions from the current word at point. That is, in
|
||
the scenario <code>this is a sent|</code>, calling <code>completion-at-point</code> will show
|
||
completions for titles that begin with “sent”.
|
||
</p></dd></dl>
|
||
|
||
<hr>
|
||
<span id="Tag-Completion"></span><div class="header">
|
||
<p>
|
||
Previous: <a href="#Link-Completion" accesskey="p" rel="prev">Link Completion</a>, Up: <a href="#Completions" accesskey="u" rel="up">Completions</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Tag-Completion-1"></span><h3 class="section">10.2 Tag Completion</h3>
|
||
|
||
<p>Org-roam facilitates the insertion of existing tags via <code>completion-at-point</code>.
|
||
</p>
|
||
<p>That is, suppose you have notes with tags “foo”, and “bar”. Now, in a note, if
|
||
you’re on a line beginning with <code>#+roam_tags:</code>, completions for these will
|
||
appear as-you-type if they match.
|
||
</p>
|
||
<p>This functionality is implemented in <code>org-roam-complete-tags-at-point</code>.
|
||
</p>
|
||
<hr>
|
||
<span id="Navigating-Around"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Encryption" accesskey="n" rel="next">Encryption</a>, Previous: <a href="#Completions" accesskey="p" rel="prev">Completions</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Navigating-Around-1"></span><h2 class="chapter">11 Navigating Around</h2>
|
||
|
||
<table class="menu" border="0" cellspacing="0">
|
||
<tr><td align="left" valign="top">• <a href="#Index-File" accesskey="1">Index File</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
</table>
|
||
|
||
<hr>
|
||
<span id="Index-File"></span><div class="header">
|
||
<p>
|
||
Up: <a href="#Navigating-Around" accesskey="u" rel="up">Navigating Around</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Index-File-1"></span><h3 class="section">11.1 Index File</h3>
|
||
|
||
<p>As your collection grows, you might want to create an index where you keep links
|
||
to your main files.
|
||
</p>
|
||
<p>In Org-roam, you can define the path to your index file by setting
|
||
<code>org-roam-index-file</code>.
|
||
</p>
|
||
<dl>
|
||
<dt id="index-org_002droam_002dindex_002dfile">Variable: <strong>org-roam-index-file</strong></dt>
|
||
<dd>
|
||
<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 <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 <code>org-roam-index</code> whose
|
||
title is <code>"Index"</code>.
|
||
</p></dd></dl>
|
||
|
||
<dl>
|
||
<dt id="index-org_002droam_002dfind_002dindex">Function: <strong>org-roam-find-index</strong></dt>
|
||
<dd>
|
||
<p>Opens the Index file in the current <code>org-roam-directory</code>.
|
||
</p></dd></dl>
|
||
|
||
<hr>
|
||
<span id="Encryption"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Graphing" accesskey="n" rel="next">Graphing</a>, Previous: <a href="#Navigating-Around" accesskey="p" rel="prev">Navigating Around</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Encryption-1"></span><h2 class="chapter">12 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 <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 cache
|
||
updates if it requires reading the encrypted file. To reduce the number of
|
||
password prompts, you may wish to cache the password.
|
||
</p>
|
||
<dl>
|
||
<dt id="index-org_002droam_002dencrypt_002dfiles">User Option: <strong>org-roam-encrypt-files</strong></dt>
|
||
<dd>
|
||
<p>Whether to encrypt new files. If true, create files with .org.gpg extension.
|
||
</p></dd></dl>
|
||
|
||
<hr>
|
||
<span id="Graphing"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Minibuffer-Completion" accesskey="n" rel="next">Minibuffer Completion</a>, Previous: <a href="#Encryption" accesskey="p" rel="prev">Encryption</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Graphing-1"></span><h2 class="chapter">13 Graphing</h2>
|
||
|
||
<p>Org-roam provides graphing capabilities to explore interconnections between
|
||
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">Roam Protocol</a>.
|
||
</p>
|
||
<p>The entry point to graph creation is <code>org-roam-graph</code>.
|
||
</p>
|
||
<dl>
|
||
<dt id="index-org_002droam_002dgraph">Function: <strong>org-roam-graph</strong> <em>& optional arg file node-query</em></dt>
|
||
<dd>
|
||
<p>Build and possibly display a graph for FILE from NODE-QUERY.
|
||
If FILE is nil, default to current buffer’s file name.
|
||
ARG may be any of the following values:
|
||
</p>
|
||
<ul>
|
||
<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>
|
||
</dd></dl>
|
||
|
||
<dl>
|
||
<dt id="index-org_002droam_002dgraph_002dexecutable">User Option: <strong>org-roam-graph-executable</strong></dt>
|
||
<dd>
|
||
<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 <code>neato</code> in place of <code>dot</code>, which generates a more
|
||
compact graph layout.
|
||
</p></dd></dl>
|
||
|
||
<dl>
|
||
<dt id="index-org_002droam_002dgraph_002dviewer">User Option: <strong>org-roam-graph-viewer</strong></dt>
|
||
<dd>
|
||
<p>Org-roam defaults to using Firefox (located on PATH) to view the SVG, but you
|
||
may choose to set it to:
|
||
</p>
|
||
<ul>
|
||
<li> A string, which is a path to the program used
|
||
|
||
</li><li> a function accepting a single argument: the graph file path.
|
||
</li></ul>
|
||
|
||
<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>
|
||
<div class="lisp">
|
||
<pre class="lisp">(setq org-roam-graph-viewer
|
||
(lambda (file)
|
||
(let ((org-roam-graph-viewer "/mnt/c/Program Files/Mozilla Firefox/firefox.exe"))
|
||
(org-roam-graph--open (concat "file://///wsl$/Ubuntu" file)))))
|
||
</pre></div>
|
||
</dd></dl>
|
||
|
||
<table class="menu" border="0" cellspacing="0">
|
||
<tr><td align="left" valign="top">• <a href="#Graph-Options" accesskey="1">Graph Options</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Excluding-Nodes-and-Edges" accesskey="2">Excluding Nodes and Edges</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
</table>
|
||
|
||
<hr>
|
||
<span id="Graph-Options"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Excluding-Nodes-and-Edges" accesskey="n" rel="next">Excluding Nodes and Edges</a>, Up: <a href="#Graphing" accesskey="u" rel="up">Graphing</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Graph-Options-1"></span><h3 class="section">13.1 Graph Options</h3>
|
||
|
||
<p>Graphviz provides many options for customizing the graph output, and Org-roam
|
||
supports some of them. See <a href="https://graphviz.gitlab.io/_pages/doc/info/attrs.html">https://graphviz.gitlab.io/_pages/doc/info/attrs.html</a>
|
||
for customizable options.
|
||
</p>
|
||
<dl>
|
||
<dt id="index-org_002droam_002dgraph_002dextra_002dconfig">User Option: <strong>org-roam-graph-extra-config</strong></dt>
|
||
<dd>
|
||
<p>Extra options passed to graphviz for the digraph (The “G” attributes).
|
||
Example: <code>'~(("rankdir" . "LR"))</code>
|
||
</p></dd></dl>
|
||
|
||
<dl>
|
||
<dt id="index-org_002droam_002dgraph_002dnode_002dextra_002dconfig">User Option: <strong>org-roam-graph-node-extra-config</strong></dt>
|
||
<dd>
|
||
<p>Extra options for nodes in the graphviz output (The “N” attributes).
|
||
Example: <code>'(("color" . "skyblue"))</code>
|
||
</p></dd></dl>
|
||
|
||
<dl>
|
||
<dt id="index-org_002droam_002dgraph_002dedge_002dextra_002dconfig">User Option: <strong>org-roam-graph-edge-extra-config</strong></dt>
|
||
<dd>
|
||
<p>Extra options for edges in the graphviz output (The “E” attributes).
|
||
Example: <code>'(("dir" . "back"))</code>
|
||
</p></dd></dl>
|
||
|
||
<dl>
|
||
<dt id="index-org_002droam_002dgraph_002dedge_002dcites_002dextra_002dconfig">User Option: <strong>org-roam-graph-edge-cites-extra-config</strong></dt>
|
||
<dd>
|
||
<p>Extra options for citation edges in the graphviz output.
|
||
Example: <code>'(("color" . "red"))</code>
|
||
</p></dd></dl>
|
||
|
||
<hr>
|
||
<span id="Excluding-Nodes-and-Edges"></span><div class="header">
|
||
<p>
|
||
Previous: <a href="#Graph-Options" accesskey="p" rel="prev">Graph Options</a>, Up: <a href="#Graphing" accesskey="u" rel="up">Graphing</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Excluding-Nodes-and-Edges-1"></span><h3 class="section">13.2 Excluding Nodes and Edges</h3>
|
||
|
||
<p>One may want to exclude certain files to declutter the graph.
|
||
</p>
|
||
<dl>
|
||
<dt id="index-org_002droam_002dgraph_002dexclude_002dmatcher">User Option: <strong>org-roam-graph-exclude-matcher</strong></dt>
|
||
<dd>
|
||
<p>Matcher for excluding nodes from the generated graph. Any nodes and links for
|
||
file paths matching this string is excluded from the graph.
|
||
</p>
|
||
<p>If value is a string, the string is the only matcher.
|
||
</p>
|
||
<p>If value is a list, all file paths matching any of the strings
|
||
are excluded.
|
||
</p></dd></dl>
|
||
|
||
<div class="example">
|
||
<pre class="example">(setq org-roam-graph-exclude-matcher '("private" "dailies"))
|
||
</pre></div>
|
||
|
||
<p>This setting excludes all files whose path contain “private” or “dailies”.
|
||
</p>
|
||
<hr>
|
||
<span id="Minibuffer-Completion"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Roam-Protocol" accesskey="n" rel="next">Roam Protocol</a>, Previous: <a href="#Graphing" accesskey="p" rel="prev">Graphing</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Minibuffer-Completion-1"></span><h2 class="chapter">14 Minibuffer Completion</h2>
|
||
|
||
<p>Org-roam allows customization of which minibuffer completion system to use for
|
||
its interactive commands. The default setting uses Emacs’ standard
|
||
<code>completing-read</code> mechanism.
|
||
</p>
|
||
<div class="lisp">
|
||
<pre class="lisp">(setq org-roam-completion-system 'default)
|
||
</pre></div>
|
||
|
||
<p>If you have installed Helm or Ivy, and have their modes enabled, under the
|
||
<code>'default</code> setting they will be used.
|
||
</p>
|
||
<p>In the rare scenario where you use Ivy globally, but prefer <a href="https://emacs-helm.github.io/helm/">Helm</a> for org-roam
|
||
commands, set:
|
||
</p>
|
||
<div class="lisp">
|
||
<pre class="lisp">(setq org-roam-completion-system 'helm)
|
||
</pre></div>
|
||
|
||
<p>Other options include <code>'ido</code>, and <code>'ivy</code>.
|
||
</p>
|
||
<hr>
|
||
<span id="Roam-Protocol"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Daily_002dnotes" accesskey="n" rel="next">Daily-notes</a>, Previous: <a href="#Minibuffer-Completion" accesskey="p" rel="prev">Minibuffer Completion</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Roam-Protocol-1"></span><h2 class="chapter">15 Roam Protocol</h2>
|
||
|
||
<p>Org-roam extends <code>org-protocol</code> with 2 protocols: the <code>roam-file</code> and <code>roam-ref</code>
|
||
protocols.
|
||
</p>
|
||
<table class="menu" border="0" cellspacing="0">
|
||
<tr><td align="left" valign="top">• <a href="#Installation-_00281_0029" accesskey="1">Installation</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#The-roam_002dfile-protocol" accesskey="2">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" accesskey="3">The roam-ref protocol</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
</table>
|
||
|
||
<hr>
|
||
<span id="Installation-_00281_0029"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#The-roam_002dfile-protocol" accesskey="n" rel="next">The roam-file protocol</a>, Up: <a href="#Roam-Protocol" accesskey="u" rel="up">Roam Protocol</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Installation-2"></span><h3 class="section">15.1 Installation</h3>
|
||
|
||
<p>To enable Org-roam’s protocol extensions, you have to add the following to your
|
||
init file:
|
||
</p>
|
||
<div class="lisp">
|
||
<pre class="lisp">(require 'org-roam-protocol)
|
||
</pre></div>
|
||
|
||
<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 <code>emacsclient</code>. The
|
||
instructions for various platforms are shown below.
|
||
</p>
|
||
<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]
|
||
Name=Org-Protocol
|
||
Exec=emacsclient %u
|
||
Icon=emacs-icon
|
||
Type=Application
|
||
Terminal=false
|
||
MimeType=x-scheme-handler/org-protocol
|
||
</pre></div>
|
||
|
||
<p>Associate <code>org-protocol://</code> links with the desktop application by
|
||
running in your shell:
|
||
</p>
|
||
<div class="example">
|
||
<pre class="example">xdg-mime default org-protocol.desktop x-scheme-handler/org-protocol
|
||
</pre></div>
|
||
|
||
<p>To disable the “confirm” prompt in Chrome, you can also make Chrome 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">
|
||
<pre class="example">sudo mkdir -p /etc/opt/chrome/policies/managed/
|
||
sudo tee /etc/opt/chrome/policies/managed/external_protocol_dialog.json >/dev/null <<'EOF'
|
||
{
|
||
"ExternalProtocolDialogShowAlwaysOpenCheckbox": true
|
||
}
|
||
EOF
|
||
sudo chmod 644 /etc/opt/chrome/policies/managed/external_protocol_dialog.json
|
||
</pre></div>
|
||
|
||
<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 <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, we need to create our own application.
|
||
</p>
|
||
<ul>
|
||
<li> Launch Script Editor
|
||
|
||
</li><li> Use the following script, paying attention to the path to <code>emacsclient</code>:
|
||
</li></ul>
|
||
|
||
<div class="lisp">
|
||
<pre class="lisp">on open location this_URL
|
||
set EC to "/usr/local/bin/emacsclient --no-wait "
|
||
set filePath to quoted form of this_URL
|
||
do shell script EC & filePath
|
||
tell application "Emacs" to activate
|
||
end open location
|
||
</pre></div>
|
||
|
||
<ul>
|
||
<li> Save the script in <code>/Applications/OrgProtocolClient.app</code>, changing the script type to
|
||
“Application”, rather than “Script”.
|
||
|
||
</li><li> Edit <code>/Applications/OrgProtocolClient.app/Contents/Info.plist</code>, adding the
|
||
following before the last <code></dict></code> tag:
|
||
</li></ul>
|
||
|
||
<div class="example">
|
||
<pre class="example"><key>CFBundleURLTypes</key>
|
||
<array>
|
||
<dict>
|
||
<key>CFBundleURLName</key>
|
||
<string>org-protocol handler</string>
|
||
<key>CFBundleURLSchemes</key>
|
||
<array>
|
||
<string>org-protocol</string>
|
||
</array>
|
||
</dict>
|
||
</array>
|
||
</pre></div>
|
||
|
||
<ul>
|
||
<li> Save the file, and run the <code>OrgProtocolClient.app</code> to register the protocol.
|
||
</li></ul>
|
||
|
||
<p>To disable the “confirm” prompt in Chrome, you can also make Chrome
|
||
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">
|
||
<pre class="example">defaults write com.google.Chrome ExternalProtocolDialogShowAlwaysOpenCheckbox -bool true
|
||
</pre></div>
|
||
|
||
|
||
<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 <code>OrgProtocol.app</code>
|
||
the default handler instead, run:
|
||
</p>
|
||
<div class="example">
|
||
<pre class="example">defaults write com.apple.LaunchServices/com.apple.launchservices.secure LSHandlers -array-add \
|
||
'{"LSHandlerPreferredVersions" = { "LSHandlerRoleAll" = "-"; }; LSHandlerRoleAll = "org.yourusername.OrgProtocol"; LSHandlerURLScheme = "org-protocol";}'
|
||
</pre></div>
|
||
|
||
<p>Then restart your computer.
|
||
</p>
|
||
<p>For Windows, create a temporary <code>org-protocol.reg</code> file:
|
||
</p>
|
||
<div class="example">
|
||
<pre class="example">REGEDIT4
|
||
|
||
[HKEY_CLASSES_ROOT\org-protocol]
|
||
@="URL:Org Protocol"
|
||
"URL Protocol"=""
|
||
[HKEY_CLASSES_ROOT\org-protocol\shell]
|
||
[HKEY_CLASSES_ROOT\org-protocol\shell\open]
|
||
[HKEY_CLASSES_ROOT\org-protocol\shell\open\command]
|
||
@="\"C:\\Windows\\System32\\wsl.exe\" emacsclient \"%1\""
|
||
</pre></div>
|
||
|
||
<p>The above will forward the protocol to WSL. If you run Emacs natively on
|
||
Windows, replace the last line with:
|
||
</p>
|
||
<div class="example">
|
||
<pre class="example">@="\"c:\\path\\to\\emacs\\bin\\emacsclientw.exe\" \"%1\""
|
||
</pre></div>
|
||
|
||
<p>After executing the .reg file, the protocol is registered and you can delete the
|
||
file.
|
||
</p>
|
||
<hr>
|
||
<span id="The-roam_002dfile-protocol"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#The-roam_002dref-protocol" accesskey="n" rel="next">The roam-ref protocol</a>, Previous: <a href="#Installation-_00281_0029" accesskey="p" rel="prev">Installation (1)</a>, Up: <a href="#Roam-Protocol" accesskey="u" rel="up">Roam Protocol</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="The-roam_002dfile-protocol-1"></span><h3 class="section">15.2 The roam-file protocol</h3>
|
||
|
||
<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>
|
||
<hr>
|
||
<span id="The-roam_002dref-protocol"></span><div class="header">
|
||
<p>
|
||
Previous: <a href="#The-roam_002dfile-protocol" accesskey="p" rel="prev">The roam-file protocol</a>, Up: <a href="#Roam-Protocol" accesskey="u" rel="up">Roam Protocol</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="The-roam_002dref-protocol-1"></span><h3 class="section">15.3 The roam-ref protocol</h3>
|
||
|
||
<p>This protocol finds or creates a new note with a given <code>roam_key</code> (see <a href="#Files">Files</a>):
|
||
</p>
|
||
<img src="images/roam-ref.gif" alt="images/roam-ref">
|
||
|
||
<p>To use this, create the following <a href="https://en.wikipedia.org/wiki/Bookmarklet">bookmarklet</a> in your browser:
|
||
</p>
|
||
<div class="example">
|
||
<pre class="example">javascript:location.href =
|
||
'org-protocol://roam-ref?template=r&ref='
|
||
+ encodeURIComponent(location.href)
|
||
+ '&title='
|
||
+ encodeURIComponent(document.title)
|
||
+ '&body='
|
||
+ encodeURIComponent(window.getSelection())
|
||
</pre></div>
|
||
|
||
<p>or as a keybinding in <code>qutebrowser</code> in , using the <code>config.py</code> file (see
|
||
<a href="https://github.com/qutebrowser/qutebrowser/blob/master/doc/help/configuring.asciidoc">Configuring qutebrowser</a>):
|
||
</p>
|
||
<div class="example">
|
||
<pre class="example">config.bind("<Ctrl-r>", "open javascript:location.href='org-protocol://roam-ref?template=r&ref='+encodeURIComponent(location.href)+'&title='+encodeURIComponent(document.title)")
|
||
</pre></div>
|
||
|
||
<p>where <code>template</code> is the template key for a template in
|
||
<code>org-roam-capture-ref-templates</code> (see <a href="#The-Templating-System">The Templating System</a>). These templates
|
||
should contain a <code>#+roam_key: ${ref}</code> in it.
|
||
</p>
|
||
<hr>
|
||
<span id="Daily_002dnotes"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Diagnosing-and-Repairing-Files" accesskey="n" rel="next">Diagnosing and Repairing Files</a>, Previous: <a href="#Roam-Protocol" accesskey="p" rel="prev">Roam Protocol</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Daily_002dnotes-1"></span><h2 class="chapter">16 Daily-notes</h2>
|
||
|
||
<p>Org-roam provides journaling capabilities akin to
|
||
<a href="#Org_002djournal">Org-journal</a> with <code>org-roam-dailies</code>.
|
||
</p>
|
||
<table class="menu" border="0" cellspacing="0">
|
||
<tr><td align="left" valign="top">• <a href="#Configuration" accesskey="1">Configuration</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Capturing-and-finding-daily_002dnotes" accesskey="2">Capturing and finding daily-notes</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Navigation" accesskey="3">Navigation</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
</table>
|
||
|
||
<hr>
|
||
<span id="Configuration"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Capturing-and-finding-daily_002dnotes" accesskey="n" rel="next">Capturing and finding daily-notes</a>, Up: <a href="#Daily_002dnotes" accesskey="u" rel="up">Daily-notes</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Configuration-1"></span><h3 class="section">16.1 Configuration</h3>
|
||
|
||
<p>For <code>org-roam-dailies</code> to work, you need to define two variables:
|
||
</p>
|
||
<dl>
|
||
<dt id="index-org_002droam_002ddailies_002ddirectory">Variable: <strong><code>org-roam-dailies-directory</code></strong></dt>
|
||
<dd>
|
||
<p>Path to daily-notes.
|
||
</p></dd></dl>
|
||
|
||
<dl>
|
||
<dt id="index-org_002droam_002ddailies_002dcapture_002dtemplates">Variable: <strong><code>org-roam-dailies-capture-templates</code></strong></dt>
|
||
<dd>
|
||
<p>Capture templates for daily-notes in Org-roam.
|
||
</p></dd></dl>
|
||
|
||
<p>Here is a sane default configuration:
|
||
</p>
|
||
<div class="lisp">
|
||
<pre class="lisp">(setq org-roam-dailies-directory "daily/")
|
||
|
||
(setq org-roam-dailies-capture-templates
|
||
'(("d" "default" entry
|
||
#'org-roam-capture--get-point
|
||
"* %?"
|
||
:file-name "daily/%<%Y-%m-%d>"
|
||
:head "#+title: %<%Y-%m-%d>\n\n")))
|
||
</pre></div>
|
||
|
||
<p>Make sure that <code>org-roam-dailies-directory</code> appears in <code>:file-name</code> for your
|
||
notes to be recognized as daily-notes. You can have different templates placing
|
||
their notes in different directories, but the one in
|
||
<code>org-roam-dailies-directory</code> will be considered as the main one in commands.
|
||
</p>
|
||
<p>See <a href="#The-Templating-System">The Templating System</a> for creating new
|
||
templates. <code>org-roam-dailies</code> provides an extra <code>:olp</code> option which allows
|
||
specifying the outline-path to a heading:
|
||
</p>
|
||
<div class="lisp">
|
||
<pre class="lisp">(setq org-roam-dailies-capture-templates
|
||
'(("l" "lab" entry
|
||
#'org-roam-capture--get-point
|
||
"* %?"
|
||
:file-name "daily/%<%Y-%m-%d>"
|
||
:head "#+title: %<%Y-%m-%d>\n"
|
||
:olp ("Lab notes"))
|
||
|
||
("j" "journal" entry
|
||
#'org-roam-capture--get-point
|
||
"* %?"
|
||
:file-name "daily/%<%Y-%m-%d>"
|
||
:head "#+title: %<%Y-%m-%d>\n"
|
||
:olp ("Journal"))))
|
||
</pre></div>
|
||
|
||
<p>The template <code>l</code> will put its notes under the heading ‘Lab notes’, and the
|
||
template <code>j</code> will put its notes under the heading ‘Journal’.
|
||
</p>
|
||
<hr>
|
||
<span id="Capturing-and-finding-daily_002dnotes"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Navigation" accesskey="n" rel="next">Navigation</a>, Previous: <a href="#Configuration" accesskey="p" rel="prev">Configuration</a>, Up: <a href="#Daily_002dnotes" accesskey="u" rel="up">Daily-notes</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Capturing-and-finding-daily_002dnotes-1"></span><h3 class="section">16.2 Capturing and finding daily-notes</h3>
|
||
|
||
<dl>
|
||
<dt id="index-org_002droam_002ddailies_002dcapture_002dtoday">Function: <strong><code>org-roam-dailies-capture-today</code></strong> <em>&optional goto</em></dt>
|
||
<dd>
|
||
<p>Create an entry in the daily note for today.
|
||
</p>
|
||
<p>When <code>goto</code> is non-nil, go the note without creating an entry.
|
||
</p></dd></dl>
|
||
|
||
<dl>
|
||
<dt id="index-org_002droam_002ddailies_002dfind_002dtoday">Function: <strong><code>org-roam-dailies-find-today</code></strong></dt>
|
||
<dd>
|
||
<p>Find the daily note for today, creating it if necessary.
|
||
</p></dd></dl>
|
||
|
||
<p>There are variants of those commands for <code>-yesterday</code> and <code>-tomorrow</code>:
|
||
</p>
|
||
<dl>
|
||
<dt id="index-org_002droam_002ddailies_002dcapture_002dyesterday">Function: <strong><code>org-roam-dailies-capture-yesterday</code></strong> <em>n &optional goto</em></dt>
|
||
<dd>
|
||
<p>Create an entry in the daily note for yesteday.
|
||
</p>
|
||
<p>With numeric argument <code>n</code>, use the daily note <code>n</code> days in the past.
|
||
</p></dd></dl>
|
||
|
||
<dl>
|
||
<dt id="index-org_002droam_002ddailies_002dfind_002dyesterday">Function: <strong><code>org-roam-dailies-find-yesterday</code></strong></dt>
|
||
<dd>
|
||
<p>With numeric argument N, use the daily-note N days in the future.
|
||
</p></dd></dl>
|
||
|
||
<p>There are also commands which allow you to use Emacs’s <code>calendar</code> to find the date
|
||
</p>
|
||
<dl>
|
||
<dt id="index-org_002droam_002ddailies_002dcapture_002ddate">Function: <strong><code>org-roam-dailies-capture-date</code></strong></dt>
|
||
<dd>
|
||
<p>Create an entry in the daily note for a date using the calendar.
|
||
</p>
|
||
<p>Prefer past dates, unless <code>prefer-future</code> is non-nil.
|
||
</p>
|
||
<p>With a ’C-u’ prefix or when <code>goto</code> is non-nil, go the note without
|
||
creating an entry.
|
||
</p></dd></dl>
|
||
|
||
<dl>
|
||
<dt id="index-org_002droam_002ddailies_002dfind_002ddate">Function: <strong><code>org-roam-dailies-find-date</code></strong></dt>
|
||
<dd>
|
||
<p>Find the daily note for a date using the calendar, creating it if necessary.
|
||
</p>
|
||
<p>Prefer past dates, unless <code>prefer-future</code> is non-nil.
|
||
</p></dd></dl>
|
||
|
||
<hr>
|
||
<span id="Navigation"></span><div class="header">
|
||
<p>
|
||
Previous: <a href="#Capturing-and-finding-daily_002dnotes" accesskey="p" rel="prev">Capturing and finding daily-notes</a>, Up: <a href="#Daily_002dnotes" accesskey="u" rel="up">Daily-notes</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Navigation-1"></span><h3 class="section">16.3 Navigation</h3>
|
||
|
||
<p>You can navigate between daily-notes:
|
||
</p>
|
||
<dl>
|
||
<dt id="index-org_002droam_002ddailies_002dfind_002ddirectory">Function: <strong><code>org-roam-dailies-find-directory</code></strong></dt>
|
||
<dd>
|
||
<p>Find and open <code>org-roam-dailies-directory</code>.
|
||
</p></dd></dl>
|
||
|
||
<dl>
|
||
<dt id="index-org_002droam_002ddailies_002dfind_002dprevious_002dnote">Function: <strong><code>org-roam-dailies-find-previous-note</code></strong></dt>
|
||
<dd>
|
||
<p>When in an daily-note, find the previous one.
|
||
</p></dd></dl>
|
||
|
||
<dl>
|
||
<dt id="index-org_002droam_002ddailies_002dfind_002dnext_002dnote">Function: <strong><code>org-roam-dailies-find-next-note</code></strong></dt>
|
||
<dd>
|
||
<p>When in an daily-note, find the next one.
|
||
</p></dd></dl>
|
||
|
||
<hr>
|
||
<span id="Diagnosing-and-Repairing-Files"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Finding-Unlinked-References" accesskey="n" rel="next">Finding Unlinked References</a>, Previous: <a href="#Daily_002dnotes" accesskey="p" rel="prev">Daily-notes</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Diagnosing-and-Repairing-Files-1"></span><h2 class="chapter">17 Diagnosing and Repairing Files</h2>
|
||
|
||
<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 all Org-roam files, run <code>C-u M-x
|
||
org-roam-doctor</code>, but note that this may take some time.
|
||
</p>
|
||
<dl>
|
||
<dt id="index-org_002droam_002ddoctor">Function: <strong>org-roam-doctor</strong> <em>&optional this-buffer</em></dt>
|
||
<dd>
|
||
<p>Perform a check on Org-roam files to ensure cleanliness. If THIS-BUFFER, run
|
||
the check only for the current buffer.
|
||
</p></dd></dl>
|
||
|
||
<p>The checks run are defined in <code>org-roam-doctor--checkers</code>. By default, there are
|
||
checkers for broken links and invalid ‘<samp>#+roam_*</samp>’ properties.
|
||
</p>
|
||
<p>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
|
||
:name 'org-roam-doctor-broken-links
|
||
:description "Fix broken links."
|
||
:actions '(("d" . ("Unlink" . org-roam-doctor--remove-link))
|
||
("r" . ("Replace link" . org-roam-doctor--replace-link))
|
||
("R" . ("Replace link (keep label)" . org-roam-doctor--replace-link-keep-label))))
|
||
</pre></div>
|
||
|
||
<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,
|
||
<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 <code>:actions</code>.
|
||
</p>
|
||
<hr>
|
||
<span id="Finding-Unlinked-References"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Performance-Optimization" accesskey="n" rel="next">Performance Optimization</a>, Previous: <a href="#Diagnosing-and-Repairing-Files" accesskey="p" rel="prev">Diagnosing and Repairing Files</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Finding-Unlinked-References-1"></span><h2 class="chapter">18 Finding Unlinked References</h2>
|
||
|
||
<p>Unlinked references are occurrences of strings of text that exactly match the
|
||
title or alias of an existing note in the Org-roam database. Org-roam provides
|
||
facilities for discovering these unlinked references, so one may decide whether
|
||
to convert them into links.
|
||
</p>
|
||
<p>To use this feature, simply call <code>M-x org-roam-unlinked-references</code> from within
|
||
an Org-roam note. Internally, Org-roam uses <a href="https://github.com/BurntSushi/ripgrep">ripgrep</a> and a clever PCRE regex to
|
||
find occurrences of the title or aliases of the currently open note in all
|
||
Org-roam files. Hence, this requires a version of ripgrep that is compiled with
|
||
PCRE support.
|
||
</p>
|
||
<blockquote>
|
||
<p>NOTE: Since ripgrep cannot read encrypted files, this function cannot find
|
||
unlinked references within encrypted files.
|
||
</p>
|
||
</blockquote>
|
||
|
||
<hr>
|
||
<span id="Performance-Optimization"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Appendix" accesskey="n" rel="next">Appendix</a>, Previous: <a href="#Finding-Unlinked-References" accesskey="p" rel="prev">Finding Unlinked References</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Performance-Optimization-1"></span><h2 class="chapter">19 Performance Optimization</h2>
|
||
|
||
<table class="menu" border="0" cellspacing="0">
|
||
<tr><td align="left" valign="top">• <a href="#Profiling-Key-Operations" accesskey="1">Profiling Key Operations</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Garbage-Collection" accesskey="2">Garbage Collection</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
</table>
|
||
|
||
<hr>
|
||
<span id="Profiling-Key-Operations"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Garbage-Collection" accesskey="n" rel="next">Garbage Collection</a>, Up: <a href="#Performance-Optimization" accesskey="u" rel="up">Performance Optimization</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="TODO-Profiling-Key-Operations"></span><h3 class="section">19.1 <strong>TODO</strong> Profiling Key Operations</h3>
|
||
|
||
<hr>
|
||
<span id="Garbage-Collection"></span><div class="header">
|
||
<p>
|
||
Previous: <a href="#Profiling-Key-Operations" accesskey="p" rel="prev">Profiling Key Operations</a>, Up: <a href="#Performance-Optimization" accesskey="u" rel="up">Performance Optimization</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Garbage-Collection-1"></span><h3 class="section">19.2 Garbage Collection</h3>
|
||
|
||
<p>During the cache-build process, Org-roam generates a lot of in-memory
|
||
data-structures (such as the Org file’s AST), which are discarded after use.
|
||
These structures are garbage collected at regular intervals (see <a href="https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Garbage-Collection">(elisp)info:elisp#Garbage Collection</a>).
|
||
</p>
|
||
<p>Org-roam provides the option <code>org-roam-db-gc-threshold</code> to temporarily change
|
||
the threshold value for GC to be triggered during these memory-intensive
|
||
operations. To reduce the number of garbage collection processes, one may set
|
||
<code>org-roam-db-gc-threshold</code> to a high value (such as <code>most-positive-fixnum</code>):
|
||
</p>
|
||
<div class="lisp">
|
||
<pre class="lisp">(setq org-roam-db-gc-threshold most-positive-fixnum)
|
||
</pre></div>
|
||
|
||
<hr>
|
||
<span id="Appendix"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#FAQ" accesskey="n" rel="next">FAQ</a>, Previous: <a href="#Performance-Optimization" accesskey="p" rel="prev">Performance Optimization</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Appendix-1"></span><h2 class="chapter">20 Appendix</h2>
|
||
|
||
<table class="menu" border="0" cellspacing="0">
|
||
<tr><td align="left" valign="top">• <a href="#Note_002dtaking-Workflows" accesskey="1">Note-taking Workflows</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Ecosystem" accesskey="2">Ecosystem</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
</table>
|
||
|
||
<hr>
|
||
<span id="Note_002dtaking-Workflows"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Ecosystem" accesskey="n" rel="next">Ecosystem</a>, Up: <a href="#Appendix" accesskey="u" rel="up">Appendix</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Note_002dtaking-Workflows-1"></span><h3 class="section">20.1 Note-taking Workflows</h3>
|
||
|
||
<ul>
|
||
<li> Books<ul>
|
||
<li> <a href="https://www.goodreads.com/book/show/34507927-how-to-take-smart-notes">How To Take Smart Notes</a>
|
||
</li></ul>
|
||
|
||
</li><li> Articles<ul>
|
||
<li> <a href="https://www.lesswrong.com/posts/NfdHG6oHBJ8Qxc26s/the-zettelkasten-method-1">The Zettelkasten Method - LessWrong 2.0</a>
|
||
|
||
</li><li> <a href="https://reddit.com/r/RoamResearch/comments/eho7de/building_a_second_brain_in_roamand_why_you_might">Building a Second Brain in Roam…And Why You Might Want To : RoamResearch</a>
|
||
|
||
</li><li> <a href="https://www.nateliason.com/blog/roam">Roam Research: Why I Love It and How I Use It - Nat Eliason</a>
|
||
|
||
</li><li> <a href="https://twitter.com/adam_keesling/status/1196864424725774336?s=20">Adam Keesling’s Twitter Thread</a>
|
||
|
||
</li><li> <a href="https://blog.jethro.dev/posts/how_to_take_smart_notes_org/">How To Take Smart Notes With Org-mode · Jethro Kuan</a>
|
||
</li></ul>
|
||
|
||
</li><li> Threads<ul>
|
||
<li> <a href="https://news.ycombinator.com/item?id=22473209">Ask HN: How to Take Good Notes</a>
|
||
</li></ul>
|
||
|
||
</li><li> Videos<ul>
|
||
<li> <a href="https://www.youtube.com/watch?v=RvWic15iXjk">How to Use Roam to Outline a New Article in Under 20 Minutes</a>
|
||
</li></ul>
|
||
</li></ul>
|
||
|
||
<hr>
|
||
<span id="Ecosystem"></span><div class="header">
|
||
<p>
|
||
Previous: <a href="#Note_002dtaking-Workflows" accesskey="p" rel="prev">Note-taking Workflows</a>, Up: <a href="#Appendix" accesskey="u" rel="up">Appendix</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Ecosystem-1"></span><h3 class="section">20.2 Ecosystem</h3>
|
||
|
||
<table class="menu" border="0" cellspacing="0">
|
||
<tr><td align="left" valign="top">• <a href="#Browsing-History-with-winner_002dmode" accesskey="1">Browsing History with winner-mode</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Versioning-Notes" accesskey="2">Versioning Notes</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Full_002dtext-search-interface-with-Deft" accesskey="3">Full-text search interface with Deft</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Org_002djournal" accesskey="4">Org-journal</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Note_002dtaking-Add_002dons" accesskey="5">Note-taking Add-ons</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
</table>
|
||
|
||
<hr>
|
||
<span id="Browsing-History-with-winner_002dmode"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Versioning-Notes" accesskey="n" rel="next">Versioning Notes</a>, Up: <a href="#Ecosystem" accesskey="u" rel="up">Ecosystem</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Browsing-History-with-winner_002dmode-1"></span><h4 class="subsection">20.2.1 Browsing History with winner-mode</h4>
|
||
|
||
<p><code>winner-mode</code> is a global minor mode that allows one to undo and redo changes in
|
||
the window configuration. It is included with GNU Emacs since version 20.
|
||
</p>
|
||
<p><code>winner-mode</code> can be used as a simple version of browser history for Org-roam.
|
||
Each click through org-roam links (from both Org files and the backlinks buffer)
|
||
causes changes in window configuration, which can be undone and redone using
|
||
<code>winner-mode</code>. To use <code>winner-mode</code>, simply enable it, and bind the appropriate
|
||
interactive functions:
|
||
</p>
|
||
<div class="lisp">
|
||
<pre class="lisp">(winner-mode +1)
|
||
(define-key winner-mode-map (kbd "<M-left>") #'winner-undo)
|
||
(define-key winner-mode-map (kbd "<M-right>") #'winner-redo)
|
||
|
||
</pre></div>
|
||
|
||
<hr>
|
||
<span id="Versioning-Notes"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Full_002dtext-search-interface-with-Deft" accesskey="n" rel="next">Full-text search interface with Deft</a>, Previous: <a href="#Browsing-History-with-winner_002dmode" accesskey="p" rel="prev">Browsing History with winner-mode</a>, Up: <a href="#Ecosystem" accesskey="u" rel="up">Ecosystem</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Versioning-Notes-1"></span><h4 class="subsection">20.2.2 Versioning Notes</h4>
|
||
|
||
<p>Since Org-roam notes are just plain text, it is trivial to track changes in your
|
||
notes database using version control systems such as <a href="https://git-scm.com/">Git</a>. Simply initialize
|
||
<code>org-roam-directory</code> as a Git repository, and commit your files at regular or
|
||
appropriate intervals. <a href="https://magit.vc/">Magit</a> is a great interface to Git within Emacs.
|
||
</p>
|
||
<p>In addition, it may be useful to observe how a particular note has evolved, by
|
||
looking at the file history. <a href="https://gitlab.com/pidu/git-timemachine">Git-timemachine</a> allows you to visit historic
|
||
versions of a tracked Org-roam note.
|
||
</p>
|
||
<hr>
|
||
<span id="Full_002dtext-search-interface-with-Deft"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Org_002djournal" accesskey="n" rel="next">Org-journal</a>, Previous: <a href="#Versioning-Notes" accesskey="p" rel="prev">Versioning Notes</a>, Up: <a href="#Ecosystem" accesskey="u" rel="up">Ecosystem</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Full_002dtext-search-interface-with-Deft-1"></span><h4 class="subsection">20.2.3 Full-text search interface with Deft</h4>
|
||
|
||
<p><a href="https://jblevins.org/projects/deft/">Deft</a> provides a nice interface for browsing and filtering org-roam notes.
|
||
</p>
|
||
<div class="lisp">
|
||
<pre class="lisp">(use-package deft
|
||
:after org
|
||
:bind
|
||
("C-c n d" . deft)
|
||
:custom
|
||
(deft-recursive t)
|
||
(deft-use-filter-string-for-filename t)
|
||
(deft-default-extension "org")
|
||
(deft-directory "/path/to/org-roam-files/"))
|
||
</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 <code>org-roam</code>’s functionality. Here I’m
|
||
using <a href="https://github.com/raxod502/el-patch">el-patch</a>:
|
||
</p>
|
||
<div class="lisp">
|
||
<pre class="lisp">(use-package el-patch
|
||
:straight (:host github
|
||
:repo "raxod502/el-patch"
|
||
:branch "develop"))
|
||
|
||
(eval-when-compile
|
||
(require 'el-patch))
|
||
|
||
(use-package deft
|
||
;; same as above...
|
||
:config/el-patch
|
||
(defun deft-parse-title (file contents)
|
||
"Parse the given FILE and CONTENTS and determine the title.
|
||
If `deft-use-filename-as-title' is nil, the title is taken to
|
||
be the first non-empty line of the FILE. Else the base name of the FILE is
|
||
used as title."
|
||
(el-patch-swap (if deft-use-filename-as-title
|
||
(deft-base-filename file)
|
||
(let ((begin (string-match "^.+$" contents)))
|
||
(if begin
|
||
(funcall deft-parse-title-function
|
||
(substring contents begin (match-end 0))))))
|
||
(org-roam-db--get-title file))))
|
||
</pre></div>
|
||
|
||
<p>The Deft interface can slow down quickly when the number of files get huge.
|
||
<a href="https://github.com/hasu/notdeft">Notdeft</a> is a fork of Deft that uses an external search engine and indexer.
|
||
</p>
|
||
<hr>
|
||
<span id="Org_002djournal"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Note_002dtaking-Add_002dons" accesskey="n" rel="next">Note-taking Add-ons</a>, Previous: <a href="#Full_002dtext-search-interface-with-Deft" accesskey="p" rel="prev">Full-text search interface with Deft</a>, Up: <a href="#Ecosystem" accesskey="u" rel="up">Ecosystem</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Org_002djournal-1"></span><h4 class="subsection">20.2.4 Org-journal</h4>
|
||
|
||
<p><a href="https://github.com/bastibe/org-journal">Org-journal</a> provides journaling capabilities to Org-mode. A lot of its
|
||
functionalities have been incorporated into Org-roam under the name
|
||
<a href="#Daily_002dnotes"><code>org-roam-dailies</code></a>. It remains a good tool if you want to isolate your verbose
|
||
journal entries from the ideas you would write on a scratchpad.
|
||
</p>
|
||
<div class="lisp">
|
||
<pre class="lisp">(use-package org-journal
|
||
:bind
|
||
("C-c n j" . org-journal-new-entry)
|
||
:custom
|
||
(org-journal-date-prefix "#+title: ")
|
||
(org-journal-file-format "%Y-%m-%d.org")
|
||
(org-journal-dir "/path/to/journal/files/")
|
||
(org-journal-date-format "%A, %d %B %Y"))
|
||
</pre></div>
|
||
|
||
<hr>
|
||
<span id="Note_002dtaking-Add_002dons"></span><div class="header">
|
||
<p>
|
||
Previous: <a href="#Org_002djournal" accesskey="p" rel="prev">Org-journal</a>, Up: <a href="#Ecosystem" accesskey="u" rel="up">Ecosystem</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Note_002dtaking-Add_002dons-1"></span><h4 class="subsection">20.2.5 Note-taking Add-ons</h4>
|
||
|
||
<p>These are some plugins that make note-taking in Org-mode more enjoyable.
|
||
</p>
|
||
<table class="menu" border="0" cellspacing="0">
|
||
<tr><td align="left" valign="top">• <a href="#Org_002ddownload" accesskey="1">Org-download</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#mathpixel" accesskey="2">mathpix.el</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Org_002dnoter-_002f-Interleave" accesskey="3">Org-noter / Interleave</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Bibliography" accesskey="4">Bibliography</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#Spaced-Repetition" accesskey="5">Spaced Repetition</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
</table>
|
||
|
||
<hr>
|
||
<span id="Org_002ddownload"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#mathpixel" accesskey="n" rel="next">mathpixel</a>, Up: <a href="#Note_002dtaking-Add_002dons" accesskey="u" rel="up">Note-taking Add-ons</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Org_002ddownload-1"></span><h4 class="unnumberedsubsubsec">Org-download</h4>
|
||
|
||
<p><a href="https://github.com/abo-abo/org-download">Org-download</a> lets you screenshot and yank images from the web into your notes:
|
||
</p>
|
||
<div class="float">
|
||
<img src="images/org-download.gif" alt="images/org-download">
|
||
|
||
<div class="float-caption"><p><strong>Figure: </strong>org-download</p></div></div>
|
||
<div class="lisp">
|
||
<pre class="lisp">(use-package org-download
|
||
:after org
|
||
:bind
|
||
(:map org-mode-map
|
||
(("s-Y" . org-download-screenshot)
|
||
("s-y" . org-download-yank))))
|
||
</pre></div>
|
||
|
||
<hr>
|
||
<span id="mathpixel"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Org_002dnoter-_002f-Interleave" accesskey="n" rel="next">Org-noter / Interleave</a>, Previous: <a href="#Org_002ddownload" accesskey="p" rel="prev">Org-download</a>, Up: <a href="#Note_002dtaking-Add_002dons" accesskey="u" rel="up">Note-taking Add-ons</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="mathpix_002eel"></span><h4 class="unnumberedsubsubsec">mathpix.el</h4>
|
||
|
||
<p><a href="https://github.com/jethrokuan/mathpix.el">mathpix.el</a> uses <a href="https://mathpix.com/">Mathpix’s</a> API to convert clips into latex equations:
|
||
</p>
|
||
<div class="float">
|
||
<img src="images/mathpix.gif" alt="images/mathpix">
|
||
|
||
<div class="float-caption"><p><strong>Figure: </strong>mathpix</p></div></div>
|
||
<div class="lisp">
|
||
<pre class="lisp">(use-package mathpix.el
|
||
:straight (:host github :repo "jethrokuan/mathpix.el")
|
||
:custom ((mathpix-app-id "app-id")
|
||
(mathpix-app-key "app-key"))
|
||
:bind
|
||
("C-x m" . mathpix-screenshot))
|
||
</pre></div>
|
||
|
||
<hr>
|
||
<span id="Org_002dnoter-_002f-Interleave"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Bibliography" accesskey="n" rel="next">Bibliography</a>, Previous: <a href="#mathpixel" accesskey="p" rel="prev">mathpixel</a>, Up: <a href="#Note_002dtaking-Add_002dons" accesskey="u" rel="up">Note-taking Add-ons</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Org_002dnoter-_002f-Interleave-1"></span><h4 class="unnumberedsubsubsec">Org-noter / Interleave</h4>
|
||
|
||
<p><a href="https://github.com/weirdNox/org-noter">Org-noter</a> and
|
||
<a href="https://github.com/rudolfochrist/interleave">Interleave</a> are both
|
||
projects that allow synchronised annotation of documents (PDF, EPUB
|
||
etc.) within Org-mode.
|
||
</p>
|
||
<hr>
|
||
<span id="Bibliography"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Spaced-Repetition" accesskey="n" rel="next">Spaced Repetition</a>, Previous: <a href="#Org_002dnoter-_002f-Interleave" accesskey="p" rel="prev">Org-noter / Interleave</a>, Up: <a href="#Note_002dtaking-Add_002dons" accesskey="u" rel="up">Note-taking Add-ons</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Bibliography-1"></span><h4 class="unnumberedsubsubsec">Bibliography</h4>
|
||
|
||
<p><a href="https://github.com/org-roam/org-roam-bibtex">org-roam-bibtex</a> offers
|
||
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
|
||
<code>org-roam</code>. This helps you manage your bibliographic notes under
|
||
<code>org-roam</code>.
|
||
</p>
|
||
<p>For example, though helm-bibtex provides the ability to visit notes for
|
||
bibliographic entries, org-roam-bibtex extends it with the ability to visit the
|
||
file with the right ‘<samp>#+roam_key</samp>’.
|
||
</p>
|
||
<hr>
|
||
<span id="Spaced-Repetition"></span><div class="header">
|
||
<p>
|
||
Previous: <a href="#Bibliography" accesskey="p" rel="prev">Bibliography</a>, Up: <a href="#Note_002dtaking-Add_002dons" accesskey="u" rel="up">Note-taking Add-ons</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Spaced-Repetition-1"></span><h4 class="unnumberedsubsubsec">Spaced Repetition</h4>
|
||
|
||
<p><a href="https://www.leonrische.me/fc/index.html">Org-fc</a> is a spaced repetition system that scales well with a large number of
|
||
files. Other alternatives include <a href="https://orgmode.org/worg/org-contrib/org-drill.html">org-drill</a>, and <a href="https://github.com/abo-abo/pamparam">pamparam</a>.
|
||
</p>
|
||
<hr>
|
||
<span id="FAQ"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Keystroke-Index" accesskey="n" rel="next">Keystroke Index</a>, Previous: <a href="#Appendix" accesskey="p" rel="prev">Appendix</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="FAQ-1"></span><h2 class="chapter">21 FAQ</h2>
|
||
|
||
<table class="menu" border="0" cellspacing="0">
|
||
<tr><td align="left" valign="top">• <a href="#How-do-I-have-more-than-one-Org_002droam-directory_003f" accesskey="1">How do I have more than one Org-roam directory?</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#How-do-I-migrate-from-Roam-Research_003f" accesskey="2">How do I migrate from Roam Research?</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
<tr><td align="left" valign="top">• <a href="#How-do-I-create-a-note-whose-title-already-matches-one-of-the-candidates_003f" accesskey="3">How do I create a note whose title already matches one of the candidates?</a></td><td> </td><td align="left" valign="top">
|
||
</td></tr>
|
||
</table>
|
||
|
||
<hr>
|
||
<span id="How-do-I-have-more-than-one-Org_002droam-directory_003f"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#How-do-I-migrate-from-Roam-Research_003f" accesskey="n" rel="next">How do I migrate from Roam Research?</a>, Up: <a href="#FAQ" accesskey="u" rel="up">FAQ</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="How-do-I-have-more-than-one-Org_002droam-directory_003f-1"></span><h3 class="section">21.1 How do I have more than one Org-roam directory?</h3>
|
||
|
||
<p>Emacs supports directory-local variables, allowing the value of
|
||
<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 <code>org-roam-directory</code>
|
||
variable using directory-local variables. This is what <code>.dir-locals.el</code> may
|
||
contain:
|
||
</p>
|
||
<div class="lisp">
|
||
<pre class="lisp">((nil . ((org-roam-directory . ".")
|
||
(org-roam-db-location . "./org-roam.db"))))
|
||
</pre></div>
|
||
|
||
<p>All files within that directory will be treated as their own separate 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>
|
||
<hr>
|
||
<span id="How-do-I-migrate-from-Roam-Research_003f"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#How-do-I-create-a-note-whose-title-already-matches-one-of-the-candidates_003f" accesskey="n" rel="next">How do I create a note whose title already matches one of the candidates?</a>, Previous: <a href="#How-do-I-have-more-than-one-Org_002droam-directory_003f" accesskey="p" rel="prev">How do I have more than one Org-roam directory?</a>, Up: <a href="#FAQ" accesskey="u" rel="up">FAQ</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="How-do-I-migrate-from-Roam-Research_003f-1"></span><h3 class="section">21.2 How do I migrate from Roam Research?</h3>
|
||
|
||
<p>Fabio has produced a command-line tool that converts markdown files exported
|
||
from Roam Research into Org-roam compatible markdown. More instructions are
|
||
provided <a href="https://github.com/fabioberger/roam-migration">in the repository</a>.
|
||
</p>
|
||
<hr>
|
||
<span id="How-do-I-create-a-note-whose-title-already-matches-one-of-the-candidates_003f"></span><div class="header">
|
||
<p>
|
||
Previous: <a href="#How-do-I-migrate-from-Roam-Research_003f" accesskey="p" rel="prev">How do I migrate from Roam Research?</a>, Up: <a href="#FAQ" accesskey="u" rel="up">FAQ</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="How-do-I-create-a-note-whose-title-already-matches-one-of-the-candidates_003f-1"></span><h3 class="section">21.3 How do I create a note whose title already matches one of the candidates?</h3>
|
||
|
||
<p>This situation arises when, for example, one would like to create a note titled
|
||
“bar” when “barricade” already exists.
|
||
</p>
|
||
<p>The solution is dependent on the mini-buffer completion framework in use. Here
|
||
are the solutions:
|
||
</p>
|
||
<ul>
|
||
<li> Ivycall <code>ivy-immediate-done</code>, typically bound to <code>C-M-j</code>. Alternatively,
|
||
set <code>ivy-use-selectable-prompt</code> to <code>t</code>, so that “bar” is now selectable.
|
||
|
||
</li><li> HelmOrg-roam should provide a selectable “[?] bar” candidate at the top of
|
||
the candidate list.
|
||
</li></ul>
|
||
|
||
<hr>
|
||
<span id="Keystroke-Index"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Command-Index" accesskey="n" rel="next">Command Index</a>, Previous: <a href="#FAQ" accesskey="p" rel="prev">FAQ</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Keystroke-Index-1"></span><h2 class="appendix">Appendix A Keystroke Index</h2>
|
||
|
||
|
||
<hr>
|
||
<span id="Command-Index"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Function-Index" accesskey="n" rel="next">Function Index</a>, Previous: <a href="#Keystroke-Index" accesskey="p" rel="prev">Keystroke Index</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Command-Index-1"></span><h2 class="appendix">Appendix B Command Index</h2>
|
||
|
||
|
||
<hr>
|
||
<span id="Function-Index"></span><div class="header">
|
||
<p>
|
||
Next: <a href="#Variable-Index" accesskey="n" rel="next">Variable Index</a>, Previous: <a href="#Command-Index" accesskey="p" rel="prev">Command Index</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Function-Index-1"></span><h2 class="appendix">Appendix C Function Index</h2>
|
||
|
||
<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Function-Index_fn_letter-O"><b>O</b></a>
|
||
|
||
</td></tr></table>
|
||
<table class="index-fn" border="0">
|
||
<tr><td></td><th align="left">Index Entry</th><td> </td><th align="left"> Section</th></tr>
|
||
<tr><td colspan="4"> <hr></td></tr>
|
||
<tr><th id="Function-Index_fn_letter-O">O</th><td></td><td></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002ddailies_002dcapture_002ddate"><code><code>org-roam-dailies-capture-date</code></code></a>:</td><td> </td><td valign="top"><a href="#Capturing-and-finding-daily_002dnotes">Capturing and finding daily-notes</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002ddailies_002dcapture_002dtoday"><code><code>org-roam-dailies-capture-today</code></code></a>:</td><td> </td><td valign="top"><a href="#Capturing-and-finding-daily_002dnotes">Capturing and finding daily-notes</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002ddailies_002dcapture_002dyesterday"><code><code>org-roam-dailies-capture-yesterday</code></code></a>:</td><td> </td><td valign="top"><a href="#Capturing-and-finding-daily_002dnotes">Capturing and finding daily-notes</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002ddailies_002dfind_002ddate"><code><code>org-roam-dailies-find-date</code></code></a>:</td><td> </td><td valign="top"><a href="#Capturing-and-finding-daily_002dnotes">Capturing and finding daily-notes</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002ddailies_002dfind_002ddirectory"><code><code>org-roam-dailies-find-directory</code></code></a>:</td><td> </td><td valign="top"><a href="#Navigation">Navigation</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002ddailies_002dfind_002dnext_002dnote"><code><code>org-roam-dailies-find-next-note</code></code></a>:</td><td> </td><td valign="top"><a href="#Navigation">Navigation</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002ddailies_002dfind_002dprevious_002dnote"><code><code>org-roam-dailies-find-previous-note</code></code></a>:</td><td> </td><td valign="top"><a href="#Navigation">Navigation</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002ddailies_002dfind_002dtoday"><code><code>org-roam-dailies-find-today</code></code></a>:</td><td> </td><td valign="top"><a href="#Capturing-and-finding-daily_002dnotes">Capturing and finding daily-notes</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002ddailies_002dfind_002dyesterday"><code><code>org-roam-dailies-find-yesterday</code></code></a>:</td><td> </td><td valign="top"><a href="#Capturing-and-finding-daily_002dnotes">Capturing and finding daily-notes</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002ddoctor"><code>org-roam-doctor</code></a>:</td><td> </td><td valign="top"><a href="#Diagnosing-and-Repairing-Files">Diagnosing and Repairing Files</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dfind_002dindex"><code>org-roam-find-index</code></a>:</td><td> </td><td valign="top"><a href="#Index-File">Index File</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dgraph"><code>org-roam-graph</code></a>:</td><td> </td><td valign="top"><a href="#Graphing">Graphing</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dlink_002dcomplete_002dat_002dpoint"><code>org-roam-link-complete-at-point</code></a>:</td><td> </td><td valign="top"><a href="#Link-Completion">Link Completion</a></td></tr>
|
||
<tr><td colspan="4"> <hr></td></tr>
|
||
</table>
|
||
<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Function-Index_fn_letter-O"><b>O</b></a>
|
||
|
||
</td></tr></table>
|
||
|
||
<hr>
|
||
<span id="Variable-Index"></span><div class="header">
|
||
<p>
|
||
Previous: <a href="#Function-Index" accesskey="p" rel="prev">Function Index</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#Keystroke-Index" title="Index" rel="index">Index</a>]</p>
|
||
</div>
|
||
<span id="Variable-Index-1"></span><h2 class="appendix">Appendix D Variable Index</h2>
|
||
|
||
<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Variable-Index_vr_letter-O"><b>O</b></a>
|
||
|
||
</td></tr></table>
|
||
<table class="index-vr" border="0">
|
||
<tr><td></td><th align="left">Index Entry</th><td> </td><th align="left"> Section</th></tr>
|
||
<tr><td colspan="4"> <hr></td></tr>
|
||
<tr><th id="Variable-Index_vr_letter-O">O</th><td></td><td></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dbuffer"><code>org-roam-buffer</code></a>:</td><td> </td><td valign="top"><a href="#The-Org_002droam-Buffer">The Org-roam Buffer</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dbuffer_002dheight"><code>org-roam-buffer-height</code></a>:</td><td> </td><td valign="top"><a href="#The-Org_002droam-Buffer">The Org-roam Buffer</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dbuffer_002dposition"><code>org-roam-buffer-position</code></a>:</td><td> </td><td valign="top"><a href="#The-Org_002droam-Buffer">The Org-roam Buffer</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dbuffer_002dwidth"><code>org-roam-buffer-width</code></a>:</td><td> </td><td valign="top"><a href="#The-Org_002droam-Buffer">The Org-roam Buffer</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dbuffer_002dwindow_002dparameters"><code>org-roam-buffer-window-parameters</code></a>:</td><td> </td><td valign="top"><a href="#The-Org_002droam-Buffer">The Org-roam Buffer</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dcompletion_002deverywhere"><code>org-roam-completion-everywhere</code></a>:</td><td> </td><td valign="top"><a href="#Link-Completions-Everywhere">Link Completions Everywhere</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dcompletion_002dfunctions"><code>org-roam-completion-functions</code></a>:</td><td> </td><td valign="top"><a href="#Completions">Completions</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dcompletion_002dignore_002dcase"><code>org-roam-completion-ignore-case</code></a>:</td><td> </td><td valign="top"><a href="#Completions">Completions</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002ddailies_002dcapture_002dtemplates"><code><code>org-roam-dailies-capture-templates</code></code></a>:</td><td> </td><td valign="top"><a href="#Configuration">Configuration</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002ddailies_002ddirectory"><code><code>org-roam-dailies-directory</code></code></a>:</td><td> </td><td valign="top"><a href="#Configuration">Configuration</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002ddb_002dlocation"><code>org-roam-db-location</code></a>:</td><td> </td><td valign="top"><a href="#Directories-and-Files">Directories and Files</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002ddb_002dupdate_002didle_002dseconds"><code>org-roam-db-update-idle-seconds</code></a>:</td><td> </td><td valign="top"><a href="#The-Database">The Database</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002ddb_002dupdate_002dmethod"><code>org-roam-db-update-method</code></a>:</td><td> </td><td valign="top"><a href="#The-Database">The Database</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002ddirectory"><code>org-roam-directory</code></a>:</td><td> </td><td valign="top"><a href="#Directories-and-Files">Directories and Files</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dencrypt_002dfiles"><code>org-roam-encrypt-files</code></a>:</td><td> </td><td valign="top"><a href="#Encryption">Encryption</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dfile_002dexclude_002dregexp"><code>org-roam-file-exclude-regexp</code></a>:</td><td> </td><td valign="top"><a href="#Directories-and-Files">Directories and Files</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dgraph_002dedge_002dcites_002dextra_002dconfig"><code>org-roam-graph-edge-cites-extra-config</code></a>:</td><td> </td><td valign="top"><a href="#Graph-Options">Graph Options</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dgraph_002dedge_002dextra_002dconfig"><code>org-roam-graph-edge-extra-config</code></a>:</td><td> </td><td valign="top"><a href="#Graph-Options">Graph Options</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dgraph_002dexclude_002dmatcher"><code>org-roam-graph-exclude-matcher</code></a>:</td><td> </td><td valign="top"><a href="#Excluding-Nodes-and-Edges">Excluding Nodes and Edges</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dgraph_002dexecutable"><code>org-roam-graph-executable</code></a>:</td><td> </td><td valign="top"><a href="#Graphing">Graphing</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dgraph_002dextra_002dconfig"><code>org-roam-graph-extra-config</code></a>:</td><td> </td><td valign="top"><a href="#Graph-Options">Graph Options</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dgraph_002dnode_002dextra_002dconfig"><code>org-roam-graph-node-extra-config</code></a>:</td><td> </td><td valign="top"><a href="#Graph-Options">Graph Options</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dgraph_002dviewer"><code>org-roam-graph-viewer</code></a>:</td><td> </td><td valign="top"><a href="#Graphing">Graphing</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dindex_002dfile"><code>org-roam-index-file</code></a>:</td><td> </td><td valign="top"><a href="#Index-File">Index File</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dlink_002dauto_002dreplace"><code>org-roam-link-auto-replace</code></a>:</td><td> </td><td valign="top"><a href="#Inserting-Links">Inserting Links</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dlink_002dtitle_002dformat"><code>org-roam-link-title-format</code></a>:</td><td> </td><td valign="top"><a href="#Inserting-Links">Inserting Links</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dlink_002duse_002dcustom_002dfaces"><code>org-roam-link-use-custom-faces</code></a>:</td><td> </td><td valign="top"><a href="#Org_002droam-Faces">Org-roam Faces</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dtag_002dsources"><code>org-roam-tag-sources</code></a>:</td><td> </td><td valign="top"><a href="#Customizing-Tag-Extraction">Customizing Tag Extraction</a></td></tr>
|
||
<tr><td></td><td valign="top"><a href="#index-org_002droam_002dtitle_002dsources"><code>org-roam-title-sources</code></a>:</td><td> </td><td valign="top"><a href="#Customizing-Title-Extraction">Customizing Title Extraction</a></td></tr>
|
||
<tr><td colspan="4"> <hr></td></tr>
|
||
</table>
|
||
<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Variable-Index_vr_letter-O"><b>O</b></a>
|
||
|
||
</td></tr></table>
|
||
|
||
<p>Emacs 28.0.50 (Org mode 9.5)
|
||
</p><div class="footnote">
|
||
<hr>
|
||
<h4 class="footnotes-heading">Footnotes</h4>
|
||
|
||
<h5><a id="FOOT1" href="#DOCF1">(1)</a></h3>
|
||
<p>To understand more about Roam, a collection of links are available in <a href="#Note_002dtaking-Workflows">Note-taking Workflows</a>.</p>
|
||
<h5><a id="FOOT2" href="#DOCF2">(2)</a></h3>
|
||
<p>Depending on your completion framework, you may need to press TAB to
|
||
see the list.</p>
|
||
</div>
|
||
<hr>
|
||
|
||
|
||
|
||
</body>
|
||
</html>
|