awesome-emacs/org-roam
1
0
Fork 0
mirror of https://github.com/org-roam/org-roam synced 2025-08-21 13:53:31 -05:00
Code Issues Packages Projects Releases Wiki Activity

Deploying to gh-pages from @ eaf99cba03 🚀

Browse Source
This commit is contained in:
jethrokuan
2020-11-13 05:18:05 +00:00
parent cdd70d1556
commit f4539ac2e6
3 changed files with 241 additions and 234 deletions
Download Patch File Download Diff File Expand all files Collapse all files

162
manual.html
View File

@@ -292,16 +292,17 @@ Next: <a href="#Target-Audience" accesskey="n" rel="next">Target Audience</a>, P
<a name="Introduction-1"></a> <a name="Introduction-1"></a>
<h2 class="chapter">1 Introduction</h2> <h2 class="chapter">1 Introduction</h2>
<p>Org-roam is a <a href="https://roamresearch.com/">Roam Research</a> replica built around the <p>Org-roam is a tool for network thought. It reproduces some of <a href="https://roamresearch.com/">Roam
all-powerful <a href="https://orgmode.org/">Org-mode</a>. Research&rsquo;s</a> <a name="DOCF1" href="#FOOT1"><sup>1</sup></a> features within the all-powerful <a href="https://orgmode.org/">Org-mode</a>.
</p> </p>
<p>Org-roam is a solution for effortless non-hierarchical note-taking <p>Org-roam is a solution for effortless non-hierarchical note-taking with
with Org-mode. With Org-roam, notes flow naturally, making note-taking Org-mode. With Org-roam, notes flow naturally, making note-taking fun and easy.
fun and easy. Org-roam should also work as a plug-and-play solution Org-roam keeps closely to Org syntax, and will work for anyone already using
for anyone already using Org-mode for their personal wiki. Org-mode for their personal wiki.
</p> </p>
<p>To understand more about Roam, a collection of links are available in <p>Org-roam gains its superpowers by leveraging the mature ecosystem around
<a href="#Note_002dtaking-Workflows">Note-taking Workflows</a>. 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>
<p>Org-roam aims to implement the core features of Roam, leveraging the <p>Org-roam aims to implement the core features of Roam, leveraging the
mature ecosystem around Org-mode where possible. Eventually, we hope mature ecosystem around Org-mode where possible. Eventually, we hope
@@ -310,25 +311,25 @@ to further introduce features enabled by the Emacs ecosystem.
<p>Org-roam provides several benefits over other tooling: <p>Org-roam provides several benefits over other tooling:
</p> </p>
<ul> <ul>
<li> Privacy and SecurityEdit your personal wiki completely offline, entirely <li> <strong>Privacy and Security:</strong> Keep your personal wiki entirely offline and in your
in your control. Encrypt your notes with GPG. control. Encrypt your notes with GPG.
</li><li> Longevity of Plain TextUnlike web solutions like Roam research, the notes </li><li> <strong>Longevity of Plain Text:</strong> Unlike web solutions like Roam Research, the notes
are first and foremost plain Org-mode files &ndash; Org-roam simply builds up an are first and foremost plain Org-mode files &ndash; Org-roam simply builds an
auxilliary database to give the personal wiki superpowers. Having your notes 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 in plain-text is crucial for the longevity of your wiki. Never have to worry
about proprietary web solutions being taken down. Edit your plain-text notes about proprietary web solutions being taken down. The notes are still
in notepad if all other editors cease to exist functional even if Org-roam ceases to exist.
</li><li> Free and Open SourceOrg-roam is free and open-source, which means that if </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, you feel unhappy with any part of Org-roam, you may choose to extend Org-roam,
or open a PR. or open a pull request.
</li><li> Leverages the Org-mode ecosystemOver the years, Emacs and Org-mode has </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 developed into a mature system for plain-text organization. Building upon
Org-mode already puts Org-roam light-years ahead of many other solutions. Org-mode already puts Org-roam light-years ahead of many other solutions.
</li><li> Built on EmacsEmacs is also a fantastic interface for editing text, and we </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 can inherit many of the powerful text-navigation and editing packages
available to Emacs. available to Emacs.
</li></ul> </li></ul>
@@ -386,30 +387,32 @@ Next: <a href="#Installation" accesskey="n" rel="next">Installation</a>, Previou
aims to provide a brief introduction to the &ldquo;slip-box&rdquo;, or &ldquo;Zettelkasten&rdquo; aims to provide a brief introduction to the &ldquo;slip-box&rdquo;, or &ldquo;Zettelkasten&rdquo;
method. By providing some background on the method, we hope that the design 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 decisions of Org-roam will become clear, and that will aid in using Org-roam
appropriately. In this section we will also introduce terms commonly used within appropriately. In this section we will introduce terms commonly used within the
the Zettelkasten community, which will also commonly appear in the Org-roam Zettelkasten community and the Org-roam forums.
forums and channels of discussion.
</p> </p>
<p>The Zettelkasten method of note-taking is designed to increase research <p>The Zettelkasten is a personal tool for thinking and writing. It places heavy
productivity: in particular, it acts as a research partner, where conversations emphasis on connecting ideas, building up a web of thought. Hence, it is well
with it may produce new and surprising lines of thought. This method is suited for knowledge workers and intellectual tasks, such as conducting
attributed to German sociologist Niklas Luhmann, who using the method had research. The Zettelkasten can act as a research partner, where conversations
produced volumes of written works. with it may produce new and surprising lines of thought.
</p> </p>
<p>In its paper form, the slip-box is simply a box of cards. These cards are small <p>This method is attributed to German sociologist Niklas Luhmann, who using the
&ndash; often only large enough to fit a single concept. The size limitation method had produced volumes of written works. Luhmann&rsquo;s slip-box was simply a
encourages ideas to be broken down into individual concepts. These ideas are box of cards. These cards are small &ndash; often only large enough to fit a single
explicitly linked together. The breakdown of ideas encourages tangential concept. The size limitation encourages ideas to be broken down into individual
exploration of ideas, increasing the surface for thought. Making linking concepts. These ideas are explicitly linked together. The breakdown of ideas
explicit between notes also encourages one to think about the connections encourages tangential exploration of ideas, increasing the surface for thought.
between concepts. 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>
<p>Org-roam is the slip-box, digitalized in Org-mode. Every zettel (card) is a <p>Org-roam is the slip-box, digitalized in Org-mode. Every zettel (card) is a
plain-text, Org-mode file. These files are often placed in the same directory. plain-text, Org-mode file. In the same way one would maintain a paper slip-box,
In the same way one would maintain a paper slip-box, Org-roam makes it easy to Org-roam makes it easy to create new zettels, pre-filling boilerplate content
create new zettels, pre-filling boilerplate content using a powerful templating using a powerful templating system.
system. Org-roam also facilitates the linking of zettels using Org-mode <code>file:</code>
links.
</p> </p>
<table class="menu" border="0" cellspacing="0"> <table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Fleeting-notes" accesskey="1">Fleeting notes</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> <tr><td align="left" valign="top">&bull; <a href="#Fleeting-notes" accesskey="1">Fleeting notes</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
@@ -427,7 +430,7 @@ Next: <a href="#Permanent-notes" accesskey="n" rel="next">Permanent notes</a>, U
<a name="Fleeting-notes-1"></a> <a name="Fleeting-notes-1"></a>
<h3 class="section">3.1 Fleeting notes</h3> <h3 class="section">3.1 Fleeting notes</h3>
<p>A slip-box requires a method of quickly capturing ideas. These are called <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 <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 need to be processed later on, or trashed. This is typically accomplished using
<code>org-capture</code> (see <a href="http://www.gnu.org/software/emacs/manual/html_mono/org.html#capture">(org)capture</a>), or using Org-roam&rsquo;s daily notes <code>org-capture</code> (see <a href="http://www.gnu.org/software/emacs/manual/html_mono/org.html#capture">(org)capture</a>), or using Org-roam&rsquo;s daily notes
@@ -602,8 +605,7 @@ dependencies that it requires. These include:
</li></ul> </li></ul>
<p>You can install this manually as well, or get the latest version from MELPA. You <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>, or some other tool or tools to help 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.
manage this.
</p> </p>
<p>If you would like to install the manual for access from Emacs&rsquo; built-in Info <p>If you would like to install the manual for access from Emacs&rsquo; built-in Info
system, you&rsquo;ll need to compile the .texi source file, and install it in an system, you&rsquo;ll need to compile the .texi source file, and install it in an
@@ -693,10 +695,10 @@ 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>. more about the methods and madness, see <a href="#Note_002dtaking-Workflows">Note-taking Workflows</a>.
</p> </p>
<p>To first start using Org-roam, one needs to pick a location to store the <p>To first start using Org-roam, one needs to pick a location to store the
Org-roam files. The directory that will contain your notes, and database index Org-roam files. The directory that will contain your notes is specified by the
is specified by the variable <code>org-roam-directory</code>. This variable needs to be set variable <code>org-roam-directory</code>. This variable needs to be set before any calls to
before any calls to Org-roam functions, including enabling <code>org-roam-mode</code>. For Org-roam functions, including enabling <code>org-roam-mode</code>. For this tutorial,
this tutorial, create an empty directory, and set <code>org-roam-directory</code>: create an empty directory, and set <code>org-roam-directory</code>:
</p> </p>
<div class="lisp"> <div class="lisp">
<pre class="lisp">(make-directory &quot;~/org-roam&quot;) <pre class="lisp">(make-directory &quot;~/org-roam&quot;)
@@ -705,39 +707,38 @@ this tutorial, create an empty directory, and set <code>org-roam-directory</code
<p>We encourage using a flat hierarchy for storing notes, but some prefer using <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 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 any notes. 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, we Instead of relying on the file hierarchy for any form of categorization, one
solely rely on links between files to establish connections between notes. should use links between files to establish connections between notes.
</p> </p>
<p>Next, we need to enable the global minor mode <code>org-roam-mode</code>. This sets up Emacs <p>Next, we need to enable the global minor mode <code>org-roam-mode</code>. This sets up
with several hooks, builds a cache and keeps it consistent. We recommend Emacs with several hooks, building a cache that is kept consistent as your
starting <code>org-roam-mode</code> on startup: slip-box grows. We recommend starting <code>org-roam-mode</code> on startup:
</p> </p>
<div class="lisp"> <div class="lisp">
<pre class="lisp">(add-hook 'after-init-hook 'org-roam-mode) <pre class="lisp">(add-hook 'after-init-hook 'org-roam-mode)
</pre></div> </pre></div>
<p>To build the cache manually, one can run <code>M-x org-roam-db-build-cache</code>. The <p>To build the cache manually, one can run <code>M-x org-roam-db-build-cache</code>. Cache
cache is a sqlite database named <code>org-roam.db</code>, which defaults to residing in builds may take a while the first time, but is often instantaneous in subsequent
the root <code>org-roam-directory</code>. Cache builds may take a while the first time, but runs because it only reprocesses modified files.
is often instantaneous in subsequent runs.
</p> </p>
<p>Let us now create our first note. Call <code>M-x org-roam-find-file</code>. This shows a list <p>Let us now create our first note. Call <code>M-x org-roam-find-file</code>. This shows a
of titles for notes that reside in <code>org-roam-directory</code>. It should show nothing list of titles for notes that reside in <code>org-roam-directory</code>. It should show
right now, since there are no notes in the directory. Entering the title of the nothing right now, since there are no notes in the directory. Entering the title
note you wish to create, and pressing <code>RET</code> should begin the note creation of the note you wish to create, and pressing <code>RET</code> should begin the note
process. This process uses <code>org-capture</code>&rsquo;s templating system, and can be freely creation process. This process uses <code>org-capture</code>&rsquo;s templating system, and can
customized (see <a href="#The-Templating-System">The Templating System</a>). Using the default template, pressing <code>C-c be customized (see <a href="#The-Templating-System">The Templating System</a>). Using the default template, pressing
C-c</code> finishes the note capture. Running <code>M-x org-roam-find-file</code> again should show <code>C-c C-c</code> finishes the note capture. Running <code>M-x org-roam-find-file</code> again
the note you have created, and selecting that entry will bring you to that note. should show the note you have created, and selecting that entry will bring you
to that note.
</p> </p>
<p>The crux of Org-roam is making it easy to create notes, and link them together. <p>Org-roam makes it easy to create notes, and link them together. To link notes
To link notes together, we call <code>M-x org-roam-insert</code>. This brings up a prompt together, we call <code>M-x org-roam-insert</code>. This brings up a prompt with a list of
with a list of title for existing notes. Selecting an existing entry will create title for existing notes. Selecting an existing entry will create and insert a
and insert a link to the current file. Entering a non-existent title will create link to the current file. Entering a non-existent title will create a new note
a new note with that title. Good usage of Org-roam requires liberally linking with that title. Good usage of Org-roam requires liberally linking files: this
files: this facilitates building up a dense knowledge graph of inter-connected facilitates building up a dense graph of inter-connected notes.
notes.
</p> </p>
<p>Org-roam provides an interface to view backlinks. It shows backlinks for the <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 currently active Org-roam note, along with some surrounding context. To toggle
@@ -746,8 +747,7 @@ the visibility of this buffer, call <code>M-x org-roam</code>.
<p>For a visual representation of the notes and their connections, Org-roam also <p>For a visual representation of the notes and their connections, Org-roam also
provides graphing capabilities, using Graphviz. It generates graphs with notes 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 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 navigate to the files, but this requires some additional setup (see <a href="#Roam-Protocol">Roam Protocol</a>).
Protocol</a>).
</p> </p>
<hr> <hr>
<a name="Anatomy-of-an-Org_002droam-File"></a> <a name="Anatomy-of-an-Org_002droam-File"></a>
@@ -758,10 +758,9 @@ Next: <a href="#The-Templating-System" accesskey="n" rel="next">The Templating S
<a name="Anatomy-of-an-Org_002droam-File-1"></a> <a name="Anatomy-of-an-Org_002droam-File-1"></a>
<h2 class="chapter">6 Anatomy of an Org-roam File</h2> <h2 class="chapter">6 Anatomy of an Org-roam File</h2>
<p>The bulk of Org-roam&rsquo;s functionality is built on top of vanilla <p>The bulk of Org-roam&rsquo;s functionality is built on top of vanilla Org-mode.
Org-mode. However, to support additional functionality, Org-roam adds However, to support additional functionality, Org-roam adds several
several Org-roam-specific keywords. These functionality are not crucial Org-roam-specific keywords.
to effective use of Org-roam.
</p> </p>
<table class="menu" border="0" cellspacing="0"> <table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Titles" accesskey="1">Titles</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top"> <tr><td align="left" valign="top">&bull; <a href="#Titles" accesskey="1">Titles</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
@@ -2566,7 +2565,14 @@ Previous: <a href="#Function-Index" accesskey="p" rel="prev">Function Index</a>,
</td></tr></table> </td></tr></table>
<p>Emacs 28.0.50 (Org mode 9.4) <p>Emacs 28.0.50 (Org mode 9.4)
</p><hr> </p><div class="footnote">
<hr>
<h4 class="footnotes-heading">Footnotes</h4>
<h3><a name="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>
</div>
<hr>

156
org-roam.org
View File

@@ -31,16 +31,17 @@ General Public License for more details.
* Introduction * Introduction
Org-roam is a [[https://roamresearch.com/][Roam Research]] replica built around the Org-roam is a tool for network thought. It reproduces some of [[https://roamresearch.com/][Roam
all-powerful [[https://orgmode.org/][Org-mode]]. Research's]] [fn:roam] features within the all-powerful [[https://orgmode.org/][Org-mode]].
Org-roam is a solution for effortless non-hierarchical note-taking Org-roam is a solution for effortless non-hierarchical note-taking with
with Org-mode. With Org-roam, notes flow naturally, making note-taking Org-mode. With Org-roam, notes flow naturally, making note-taking fun and easy.
fun and easy. Org-roam should also work as a plug-and-play solution Org-roam keeps closely to Org syntax, and will work for anyone already using
for anyone already using Org-mode for their personal wiki. Org-mode for their personal wiki.
To understand more about Roam, a collection of links are available in Org-roam gains its superpowers by leveraging the mature ecosystem around
[[*Note-taking Workflows][Note-taking Workflows]]. Org-mode. For example, it has first-class support for [[https://github.com/jkitchin/org-ref][org-ref]] for citation
management.
Org-roam aims to implement the core features of Roam, leveraging the Org-roam aims to implement the core features of Roam, leveraging the
mature ecosystem around Org-mode where possible. Eventually, we hope mature ecosystem around Org-mode where possible. Eventually, we hope
@@ -48,21 +49,21 @@ to further introduce features enabled by the Emacs ecosystem.
Org-roam provides several benefits over other tooling: Org-roam provides several benefits over other tooling:
- Privacy and Security :: Edit your personal wiki completely offline, entirely - *Privacy and Security:* Keep your personal wiki entirely offline and in your
in your control. Encrypt your notes with GPG. control. Encrypt your notes with GPG.
- Longevity of Plain Text :: Unlike web solutions like Roam research, the notes - *Longevity of Plain Text:* Unlike web solutions like Roam Research, the notes
are first and foremost plain Org-mode files -- Org-roam simply builds up an are first and foremost plain Org-mode files -- Org-roam simply builds an
auxilliary database to give the personal wiki superpowers. Having your notes 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 in plain-text is crucial for the longevity of your wiki. Never have to worry
about proprietary web solutions being taken down. Edit your plain-text notes about proprietary web solutions being taken down. The notes are still
in notepad if all other editors cease to exist functional even if Org-roam ceases to exist.
- Free and Open Source :: Org-roam is free and open-source, which means that if - *Free and Open Source:* 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, you feel unhappy with any part of Org-roam, you may choose to extend Org-roam,
or open a PR. or open a pull request.
- Leverages the Org-mode ecosystem :: Over the years, Emacs and Org-mode has - *Leverage the Org-mode ecosystem:* Over the years, Emacs and Org-mode has
developed into a mature system for plain-text organization. Building upon developed into a mature system for plain-text organization. Building upon
Org-mode already puts Org-roam light-years ahead of many other solutions. Org-mode already puts Org-roam light-years ahead of many other solutions.
- Built on Emacs :: Emacs is also a fantastic interface for editing text, and we - *Built on Emacs:* Emacs is also a fantastic interface for editing text, and we
can inherit many of the powerful text-navigation and editing packages can inherit many of the powerful text-navigation and editing packages
available to Emacs. available to Emacs.
@@ -104,34 +105,36 @@ Org-roam provides utilities for maintaining a digital slip-box. This section
aims to provide a brief introduction to the "slip-box", or "Zettelkasten" 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 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 decisions of Org-roam will become clear, and that will aid in using Org-roam
appropriately. In this section we will also introduce terms commonly used within appropriately. In this section we will introduce terms commonly used within the
the Zettelkasten community, which will also commonly appear in the Org-roam Zettelkasten community and the Org-roam forums.
forums and channels of discussion.
The Zettelkasten method of note-taking is designed to increase research The Zettelkasten is a personal tool for thinking and writing. It places heavy
productivity: in particular, it acts as a research partner, where conversations emphasis on connecting ideas, building up a web of thought. Hence, it is well
with it may produce new and surprising lines of thought. This method is suited for knowledge workers and intellectual tasks, such as conducting
attributed to German sociologist Niklas Luhmann, who using the method had research. The Zettelkasten can act as a research partner, where conversations
produced volumes of written works. with it may produce new and surprising lines of thought.
In its paper form, the slip-box is simply a box of cards. These cards are small This method is attributed to German sociologist Niklas Luhmann, who using the
-- often only large enough to fit a single concept. The size limitation method had produced volumes of written works. Luhmann's slip-box was simply a
encourages ideas to be broken down into individual concepts. These ideas are box of cards. These cards are small -- often only large enough to fit a single
explicitly linked together. The breakdown of ideas encourages tangential concept. The size limitation encourages ideas to be broken down into individual
exploration of ideas, increasing the surface for thought. Making linking concepts. These ideas are explicitly linked together. The breakdown of ideas
explicit between notes also encourages one to think about the connections encourages tangential exploration of ideas, increasing the surface for thought.
between concepts. Making linking explicit between notes also encourages one to think about the
connections between concepts.
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.
Org-roam is the slip-box, digitalized in Org-mode. Every zettel (card) is a Org-roam is the slip-box, digitalized in Org-mode. Every zettel (card) is a
plain-text, Org-mode file. These files are often placed in the same directory. plain-text, Org-mode file. In the same way one would maintain a paper slip-box,
In the same way one would maintain a paper slip-box, Org-roam makes it easy to Org-roam makes it easy to create new zettels, pre-filling boilerplate content
create new zettels, pre-filling boilerplate content using a powerful templating using a powerful templating system.
system. Org-roam also facilitates the linking of zettels using Org-mode ~file:~
links.
** Fleeting notes ** Fleeting notes
A slip-box requires a method of quickly capturing ideas. These are called A slip-box requires a method for quickly capturing ideas. These are called
*fleeting notes*: they are simple reminders of information or ideas that will *fleeting notes*: they are simple reminders of information or ideas that will
need to be processed later on, or trashed. This is typically accomplished using need to be processed later on, or trashed. This is typically accomplished using
~org-capture~ (see info:org#capture), or using Org-roam's daily notes ~org-capture~ (see info:org#capture), or using Org-roam's daily notes
@@ -249,8 +252,7 @@ dependencies that it requires. These include:
- emacsql-sqlite3 - emacsql-sqlite3
You can install this manually as well, or get the latest version from MELPA. You You can install this manually as well, or get the latest version from MELPA. You
may wish to use [[https://github.com/jwiegley/use-package][use-package]], [[https://github.com/raxod502/straight.el][straight.el]], or some other tool or tools to help may wish to use [[https://github.com/jwiegley/use-package][use-package]], [[https://github.com/raxod502/straight.el][straight.el]] to help manage this.
manage this.
If you would like to install the manual for access from Emacs' built-in Info 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 system, you'll need to compile the .texi source file, and install it in an
@@ -322,10 +324,10 @@ requires a radical change in your current note-taking workflow. To understand
more about the methods and madness, see [[*Note-taking Workflows][Note-taking Workflows]]. more about the methods and madness, see [[*Note-taking Workflows][Note-taking Workflows]].
To first start using Org-roam, one needs to pick a location to store the To first start using Org-roam, one needs to pick a location to store the
Org-roam files. The directory that will contain your notes, and database index Org-roam files. The directory that will contain your notes is specified by the
is specified by the variable ~org-roam-directory~. This variable needs to be set variable ~org-roam-directory~. This variable needs to be set before any calls to
before any calls to Org-roam functions, including enabling ~org-roam-mode~. For Org-roam functions, including enabling ~org-roam-mode~. For this tutorial,
this tutorial, create an empty directory, and set ~org-roam-directory~: create an empty directory, and set ~org-roam-directory~:
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(make-directory "~/org-roam") (make-directory "~/org-roam")
@@ -334,39 +336,38 @@ this tutorial, create an empty directory, and set ~org-roam-directory~:
We encourage using a flat hierarchy for storing notes, but some prefer using 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 folders for storing specific kinds of notes (e.g. websites, papers). This is
fine; Org-roam searches recursively within ~org-roam-directory~ for any notes. fine; Org-roam searches recursively within ~org-roam-directory~ for notes.
Instead of relying on the file hierarchy for any form of categorization, we Instead of relying on the file hierarchy for any form of categorization, one
solely rely on links between files to establish connections between notes. should use links between files to establish connections between notes.
Next, we need to enable the global minor mode ~org-roam-mode~. This sets up Emacs Next, we need to enable the global minor mode ~org-roam-mode~. This sets up
with several hooks, builds a cache and keeps it consistent. We recommend Emacs with several hooks, building a cache that is kept consistent as your
starting ~org-roam-mode~ on startup: slip-box grows. We recommend starting ~org-roam-mode~ on startup:
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(add-hook 'after-init-hook 'org-roam-mode) (add-hook 'after-init-hook 'org-roam-mode)
#+END_SRC #+END_SRC
To build the cache manually, one can run ~M-x org-roam-db-build-cache~. The To build the cache manually, one can run ~M-x org-roam-db-build-cache~. Cache
cache is a sqlite database named ~org-roam.db~, which defaults to residing in builds may take a while the first time, but is often instantaneous in subsequent
the root ~org-roam-directory~. Cache builds may take a while the first time, but runs because it only reprocesses modified files.
is often instantaneous in subsequent runs.
Let us now create our first note. Call ~M-x org-roam-find-file~. This shows a list Let us now create our first note. Call ~M-x org-roam-find-file~. This shows a
of titles for notes that reside in ~org-roam-directory~. It should show nothing list of titles for notes that reside in ~org-roam-directory~. It should show
right now, since there are no notes in the directory. Entering the title of the nothing right now, since there are no notes in the directory. Entering the title
note you wish to create, and pressing ~RET~ should begin the note creation of the note you wish to create, and pressing ~RET~ should begin the note
process. This process uses ~org-capture~'s templating system, and can be freely creation process. This process uses ~org-capture~'s templating system, and can
customized (see [[*The Templating System][The Templating System]]). Using the default template, pressing ~C-c be customized (see [[*The Templating System][The Templating System]]). Using the default template, pressing
C-c~ finishes the note capture. Running ~M-x org-roam-find-file~ again should show ~C-c C-c~ finishes the note capture. Running ~M-x org-roam-find-file~ again
the note you have created, and selecting that entry will bring you to that note. should show the note you have created, and selecting that entry will bring you
to that note.
The crux of Org-roam is making it easy to create notes, and link them together. Org-roam makes it easy to create notes, and link them together. To link notes
To link notes together, we call ~M-x org-roam-insert~. This brings up a prompt together, we call ~M-x org-roam-insert~. This brings up a prompt with a list of
with a list of title for existing notes. Selecting an existing entry will create title for existing notes. Selecting an existing entry will create and insert a
and insert a link to the current file. Entering a non-existent title will create link to the current file. Entering a non-existent title will create a new note
a new note with that title. Good usage of Org-roam requires liberally linking with that title. Good usage of Org-roam requires liberally linking files: this
files: this facilitates building up a dense knowledge graph of inter-connected facilitates building up a dense graph of inter-connected notes.
notes.
Org-roam provides an interface to view backlinks. It shows backlinks for the 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 currently active Org-roam note, along with some surrounding context. To toggle
@@ -375,15 +376,14 @@ the visibility of this buffer, call ~M-x org-roam~.
For a visual representation of the notes and their connections, Org-roam also For a visual representation of the notes and their connections, Org-roam also
provides graphing capabilities, using Graphviz. It generates graphs with notes 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 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 [[*Roam Protocol][Roam navigate to the files, but this requires some additional setup (see [[*Roam
Protocol]]). Protocol][Roam Protocol]]).
* Anatomy of an Org-roam File * Anatomy of an Org-roam File
The bulk of Org-roam's functionality is built on top of vanilla The bulk of Org-roam's functionality is built on top of vanilla Org-mode.
Org-mode. However, to support additional functionality, Org-roam adds However, to support additional functionality, Org-roam adds several
several Org-roam-specific keywords. These functionality are not crucial Org-roam-specific keywords.
to effective use of Org-roam.
** Titles ** Titles
@@ -1543,6 +1543,8 @@ are the solutions:
:INDEX: vr :INDEX: vr
:END: :END:
* Footnotes
[fn:roam] To understand more about Roam, a collection of links are available in [[*Note-taking Workflows][Note-taking Workflows]].
# Local Variables: # Local Variables:
# eval: (require 'ol-info) # eval: (require 'ol-info)

153
org-roam.texi
View File

@@ -180,16 +180,17 @@ FAQ
@node Introduction @node Introduction
@chapter Introduction @chapter Introduction
Org-roam is a @uref{https://roamresearch.com/, Roam Research} replica built around the Org-roam is a tool for network thought. It reproduces some of @uref{https://roamresearch.com/, Roam
all-powerful @uref{https://orgmode.org/, Org-mode}. Research's} @footnote{To understand more about Roam, a collection of links are available in @ref{Note-taking Workflows}.} features within the all-powerful @uref{https://orgmode.org/, Org-mode}.
Org-roam is a solution for effortless non-hierarchical note-taking Org-roam is a solution for effortless non-hierarchical note-taking with
with Org-mode. With Org-roam, notes flow naturally, making note-taking Org-mode. With Org-roam, notes flow naturally, making note-taking fun and easy.
fun and easy. Org-roam should also work as a plug-and-play solution Org-roam keeps closely to Org syntax, and will work for anyone already using
for anyone already using Org-mode for their personal wiki. Org-mode for their personal wiki.
To understand more about Roam, a collection of links are available in Org-roam gains its superpowers by leveraging the mature ecosystem around
@ref{Note-taking Workflows}. Org-mode. For example, it has first-class support for @uref{https://github.com/jkitchin/org-ref, org-ref} for citation
management.
Org-roam aims to implement the core features of Roam, leveraging the Org-roam aims to implement the core features of Roam, leveraging the
mature ecosystem around Org-mode where possible. Eventually, we hope mature ecosystem around Org-mode where possible. Eventually, we hope
@@ -199,29 +200,29 @@ Org-roam provides several benefits over other tooling:
@itemize @itemize
@item @item
Privacy and SecurityEdit your personal wiki completely offline, entirely @strong{Privacy and Security:} Keep your personal wiki entirely offline and in your
in your control. Encrypt your notes with GPG@. control. Encrypt your notes with GPG@.
@item @item
Longevity of Plain TextUnlike web solutions like Roam research, the notes @strong{Longevity of Plain Text:} Unlike web solutions like Roam Research, the notes
are first and foremost plain Org-mode files -- Org-roam simply builds up an are first and foremost plain Org-mode files -- Org-roam simply builds an
auxilliary database to give the personal wiki superpowers. Having your notes 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 in plain-text is crucial for the longevity of your wiki. Never have to worry
about proprietary web solutions being taken down. Edit your plain-text notes about proprietary web solutions being taken down. The notes are still
in notepad if all other editors cease to exist functional even if Org-roam ceases to exist.
@item @item
Free and Open SourceOrg-roam is free and open-source, which means that if @strong{Free and Open Source:} 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, you feel unhappy with any part of Org-roam, you may choose to extend Org-roam,
or open a PR@. or open a pull request.
@item @item
Leverages the Org-mode ecosystemOver the years, Emacs and Org-mode has @strong{Leverage the Org-mode ecosystem:} Over the years, Emacs and Org-mode has
developed into a mature system for plain-text organization. Building upon developed into a mature system for plain-text organization. Building upon
Org-mode already puts Org-roam light-years ahead of many other solutions. Org-mode already puts Org-roam light-years ahead of many other solutions.
@item @item
Built on EmacsEmacs is also a fantastic interface for editing text, and we @strong{Built on Emacs:} Emacs is also a fantastic interface for editing text, and we
can inherit many of the powerful text-navigation and editing packages can inherit many of the powerful text-navigation and editing packages
available to Emacs. available to Emacs.
@end itemize @end itemize
@@ -267,30 +268,32 @@ Org-roam provides utilities for maintaining a digital slip-box. This section
aims to provide a brief introduction to the ``slip-box'', or ``Zettelkasten'' 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 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 decisions of Org-roam will become clear, and that will aid in using Org-roam
appropriately. In this section we will also introduce terms commonly used within appropriately. In this section we will introduce terms commonly used within the
the Zettelkasten community, which will also commonly appear in the Org-roam Zettelkasten community and the Org-roam forums.
forums and channels of discussion.
The Zettelkasten method of note-taking is designed to increase research The Zettelkasten is a personal tool for thinking and writing. It places heavy
productivity: in particular, it acts as a research partner, where conversations emphasis on connecting ideas, building up a web of thought. Hence, it is well
with it may produce new and surprising lines of thought. This method is suited for knowledge workers and intellectual tasks, such as conducting
attributed to German sociologist Niklas Luhmann, who using the method had research. The Zettelkasten can act as a research partner, where conversations
produced volumes of written works. with it may produce new and surprising lines of thought.
In its paper form, the slip-box is simply a box of cards. These cards are small This method is attributed to German sociologist Niklas Luhmann, who using the
-- often only large enough to fit a single concept. The size limitation method had produced volumes of written works. Luhmann's slip-box was simply a
encourages ideas to be broken down into individual concepts. These ideas are box of cards. These cards are small -- often only large enough to fit a single
explicitly linked together. The breakdown of ideas encourages tangential concept. The size limitation encourages ideas to be broken down into individual
exploration of ideas, increasing the surface for thought. Making linking concepts. These ideas are explicitly linked together. The breakdown of ideas
explicit between notes also encourages one to think about the connections encourages tangential exploration of ideas, increasing the surface for thought.
between concepts. Making linking explicit between notes also encourages one to think about the
connections between concepts.
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.
Org-roam is the slip-box, digitalized in Org-mode. Every zettel (card) is a Org-roam is the slip-box, digitalized in Org-mode. Every zettel (card) is a
plain-text, Org-mode file. These files are often placed in the same directory. plain-text, Org-mode file. In the same way one would maintain a paper slip-box,
In the same way one would maintain a paper slip-box, Org-roam makes it easy to Org-roam makes it easy to create new zettels, pre-filling boilerplate content
create new zettels, pre-filling boilerplate content using a powerful templating using a powerful templating system.
system. Org-roam also facilitates the linking of zettels using Org-mode @code{file:}
links.
@menu @menu
* Fleeting notes:: * Fleeting notes::
@@ -300,7 +303,7 @@ links.
@node Fleeting notes @node Fleeting notes
@section Fleeting notes @section Fleeting notes
A slip-box requires a method of quickly capturing ideas. These are called A slip-box requires a method for quickly capturing ideas. These are called
@strong{fleeting notes}: they are simple reminders of information or ideas that will @strong{fleeting notes}: they are simple reminders of information or ideas that will
need to be processed later on, or trashed. This is typically accomplished using need to be processed later on, or trashed. This is typically accomplished using
@code{org-capture} (see @ref{capture,,,org,}), or using Org-roam's daily notes @code{org-capture} (see @ref{capture,,,org,}), or using Org-roam's daily notes
@@ -449,8 +452,7 @@ emacsql-sqlite3
@end itemize @end itemize
You can install this manually as well, or get the latest version from MELPA@. You You can install this manually as well, or get the latest version from MELPA@. You
may wish to use @uref{https://github.com/jwiegley/use-package, use-package}, @uref{https://github.com/raxod502/straight.el, straight.el}, or some other tool or tools to help may wish to use @uref{https://github.com/jwiegley/use-package, use-package}, @uref{https://github.com/raxod502/straight.el, straight.el} to help manage this.
manage this.
If you would like to install the manual for access from Emacs' built-in Info 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 system, you'll need to compile the .texi source file, and install it in an
@@ -531,10 +533,10 @@ requires a radical change in your current note-taking workflow. To understand
more about the methods and madness, see @ref{Note-taking Workflows}. more about the methods and madness, see @ref{Note-taking Workflows}.
To first start using Org-roam, one needs to pick a location to store the To first start using Org-roam, one needs to pick a location to store the
Org-roam files. The directory that will contain your notes, and database index Org-roam files. The directory that will contain your notes is specified by the
is specified by the variable @code{org-roam-directory}. This variable needs to be set variable @code{org-roam-directory}. This variable needs to be set before any calls to
before any calls to Org-roam functions, including enabling @code{org-roam-mode}. For Org-roam functions, including enabling @code{org-roam-mode}. For this tutorial,
this tutorial, create an empty directory, and set @code{org-roam-directory}: create an empty directory, and set @code{org-roam-directory}:
@lisp @lisp
(make-directory "~/org-roam") (make-directory "~/org-roam")
@@ -543,39 +545,38 @@ this tutorial, create an empty directory, and set @code{org-roam-directory}:
We encourage using a flat hierarchy for storing notes, but some prefer using 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 folders for storing specific kinds of notes (e.g. websites, papers). This is
fine; Org-roam searches recursively within @code{org-roam-directory} for any notes. fine; Org-roam searches recursively within @code{org-roam-directory} for notes.
Instead of relying on the file hierarchy for any form of categorization, we Instead of relying on the file hierarchy for any form of categorization, one
solely rely on links between files to establish connections between notes. should use links between files to establish connections between notes.
Next, we need to enable the global minor mode @code{org-roam-mode}. This sets up Emacs Next, we need to enable the global minor mode @code{org-roam-mode}. This sets up
with several hooks, builds a cache and keeps it consistent. We recommend Emacs with several hooks, building a cache that is kept consistent as your
starting @code{org-roam-mode} on startup: slip-box grows. We recommend starting @code{org-roam-mode} on startup:
@lisp @lisp
(add-hook 'after-init-hook 'org-roam-mode) (add-hook 'after-init-hook 'org-roam-mode)
@end lisp @end lisp
To build the cache manually, one can run @code{M-x org-roam-db-build-cache}. The To build the cache manually, one can run @code{M-x org-roam-db-build-cache}. Cache
cache is a sqlite database named @code{org-roam.db}, which defaults to residing in builds may take a while the first time, but is often instantaneous in subsequent
the root @code{org-roam-directory}. Cache builds may take a while the first time, but runs because it only reprocesses modified files.
is often instantaneous in subsequent runs.
Let us now create our first note. Call @code{M-x org-roam-find-file}. This shows a list Let us now create our first note. Call @code{M-x org-roam-find-file}. This shows a
of titles for notes that reside in @code{org-roam-directory}. It should show nothing list of titles for notes that reside in @code{org-roam-directory}. It should show
right now, since there are no notes in the directory. Entering the title of the nothing right now, since there are no notes in the directory. Entering the title
note you wish to create, and pressing @code{RET} should begin the note creation of the note you wish to create, and pressing @code{RET} should begin the note
process. This process uses @code{org-capture}'s templating system, and can be freely creation process. This process uses @code{org-capture}'s templating system, and can
customized (see @ref{The Templating System}). Using the default template, pressing @code{C-c be customized (see @ref{The Templating System}). Using the default template, pressing
C-c} finishes the note capture. Running @code{M-x org-roam-find-file} again should show @code{C-c C-c} finishes the note capture. Running @code{M-x org-roam-find-file} again
the note you have created, and selecting that entry will bring you to that note. should show the note you have created, and selecting that entry will bring you
to that note.
The crux of Org-roam is making it easy to create notes, and link them together. Org-roam makes it easy to create notes, and link them together. To link notes
To link notes together, we call @code{M-x org-roam-insert}. This brings up a prompt together, we call @code{M-x org-roam-insert}. This brings up a prompt with a list of
with a list of title for existing notes. Selecting an existing entry will create title for existing notes. Selecting an existing entry will create and insert a
and insert a link to the current file. Entering a non-existent title will create link to the current file. Entering a non-existent title will create a new note
a new note with that title. Good usage of Org-roam requires liberally linking with that title. Good usage of Org-roam requires liberally linking files: this
files: this facilitates building up a dense knowledge graph of inter-connected facilitates building up a dense graph of inter-connected notes.
notes.
Org-roam provides an interface to view backlinks. It shows backlinks for the 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 currently active Org-roam note, along with some surrounding context. To toggle
@@ -584,16 +585,14 @@ the visibility of this buffer, call @code{M-x org-roam}.
For a visual representation of the notes and their connections, Org-roam also For a visual representation of the notes and their connections, Org-roam also
provides graphing capabilities, using Graphviz. It generates graphs with notes 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 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 @ref{Roam Protocol, , Roam navigate to the files, but this requires some additional setup (see @ref{Roam Protocol}).
Protocol}).
@node Anatomy of an Org-roam File @node Anatomy of an Org-roam File
@chapter Anatomy of an Org-roam File @chapter Anatomy of an Org-roam File
The bulk of Org-roam's functionality is built on top of vanilla The bulk of Org-roam's functionality is built on top of vanilla Org-mode.
Org-mode. However, to support additional functionality, Org-roam adds However, to support additional functionality, Org-roam adds several
several Org-roam-specific keywords. These functionality are not crucial Org-roam-specific keywords.
to effective use of Org-roam.
@menu @menu
* Titles:: * Titles::