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>
<h2 class="chapter">1 Introduction</h2>
<p>Org-roam is a <a href="https://roamresearch.com/">Roam Research</a> replica built around the
all-powerful <a href="https://orgmode.org/">Org-mode</a>.
<p>Org-roam is a tool for network thought. It reproduces some of <a href="https://roamresearch.com/">Roam
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>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 should also work as a plug-and-play solution
for anyone already using Org-mode for their personal wiki.
<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>To understand more about Roam, a collection of links are available in
<a href="#Note_002dtaking-Workflows">Note-taking Workflows</a>.
<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
@@ -310,25 +311,25 @@ to further introduce features enabled by the Emacs ecosystem.
<p>Org-roam provides several benefits over other tooling:
</p>
<ul>
<li> Privacy and SecurityEdit your personal wiki completely offline, entirely
in your control. Encrypt your notes with GPG.
<li> <strong>Privacy and Security:</strong> Keep your personal wiki entirely offline and in your
control. Encrypt your notes with GPG.
</li><li> Longevity of Plain TextUnlike web solutions like Roam research, the notes
are first and foremost plain Org-mode files &ndash; Org-roam simply builds up an
auxilliary database to give the personal wiki superpowers. Having your 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 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. Edit your plain-text notes
in notepad if all other editors cease to exist
about proprietary web solutions being taken down. The notes are still
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,
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
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
available to Emacs.
</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;
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 also introduce terms commonly used within
the Zettelkasten community, which will also commonly appear in the Org-roam
forums and channels of discussion.
appropriately. In this section we will introduce terms commonly used within the
Zettelkasten community and the Org-roam forums.
</p>
<p>The Zettelkasten method of note-taking is designed to increase research
productivity: in particular, it acts as a research partner, where conversations
with it may produce new and surprising lines of thought. This method is
attributed to German sociologist Niklas Luhmann, who using the method had
produced volumes of written works.
<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>In its paper form, the slip-box is simply a box of cards. These cards are small
&ndash; 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>This method is attributed to German sociologist Niklas Luhmann, who using the
method had produced volumes of written works. Luhmann&rsquo;s slip-box was simply a
box of cards. These cards are small &ndash; 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. These files are often placed in the same directory.
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. Org-roam also facilitates the linking of zettels using Org-mode <code>file:</code>
links.
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">&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>
<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
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
@@ -602,8 +605,7 @@ dependencies that it requires. These include:
</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>, or some other tool or tools to help
manage this.
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&rsquo; built-in Info
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>.
</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, and database index
is specified by the variable <code>org-roam-directory</code>. This variable needs to be set
before any calls to Org-roam functions, including enabling <code>org-roam-mode</code>. For
this tutorial, create an empty directory, and set <code>org-roam-directory</code>:
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 &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
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.
Instead of relying on the file hierarchy for any form of categorization, we
solely rely on links between files to establish connections between 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, 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, builds a cache and keeps it consistent. We recommend
starting <code>org-roam-mode</code> on startup:
<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>. The
cache is a sqlite database named <code>org-roam.db</code>, which defaults to residing in
the root <code>org-roam-directory</code>. Cache builds may take a while the first time, but
is often instantaneous in subsequent runs.
<p>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>&rsquo;s templating system, and can be freely
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. Running <code>M-x org-roam-find-file</code> again should show
the note you have created, and selecting that entry will bring you to that note.
<p>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>&rsquo;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. Running <code>M-x org-roam-find-file</code> again
should show the note you have created, and selecting that entry will bring you
to that note.
</p>
<p>The crux of Org-roam is making it easy to create notes, and link them together.
To link notes together, we call <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 knowledge graph of inter-connected
notes.
<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
@@ -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
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>).
navigate to the files, but this requires some additional setup (see <a href="#Roam-Protocol">Roam Protocol</a>).
</p>
<hr>
<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>
<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
Org-mode. However, to support additional functionality, Org-roam adds
several Org-roam-specific keywords. These functionality are not crucial
to effective use of Org-roam.
<p>The bulk of Org-roam&rsquo;s functionality is built on top of vanilla Org-mode.
However, to support additional functionality, Org-roam adds several
Org-roam-specific keywords.
</p>
<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">
@@ -2566,7 +2565,14 @@ Previous: <a href="#Function-Index" accesskey="p" rel="prev">Function Index</a>,
</td></tr></table>
<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
Org-roam is a [[https://roamresearch.com/][Roam Research]] replica built around the
all-powerful [[https://orgmode.org/][Org-mode]].
Org-roam is a tool for network thought. It reproduces some of [[https://roamresearch.com/][Roam
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
with Org-mode. With Org-roam, notes flow naturally, making note-taking
fun and easy. Org-roam should also work as a plug-and-play solution
for anyone already using Org-mode for their personal wiki.
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.
To understand more about Roam, a collection of links are available in
[[*Note-taking Workflows][Note-taking Workflows]].
Org-roam gains its superpowers by leveraging the mature ecosystem around
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
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:
- Privacy and Security :: Edit your personal wiki completely offline, entirely
in your control. Encrypt your notes with GPG.
- 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
auxilliary database to give the personal wiki superpowers. Having your notes
- *Privacy and Security:* Keep your personal wiki entirely offline and in your
control. Encrypt your notes with GPG.
- *Longevity of Plain Text:* 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. Edit your plain-text notes
in notepad if all other editors cease to exist
- Free and Open Source :: Org-roam is free and open-source, which means that if
about proprietary web solutions being taken down. The notes are still
functional even if Org-roam ceases to exist.
- *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,
or open a PR.
- Leverages the Org-mode ecosystem :: Over the years, Emacs and Org-mode has
or open a pull request.
- *Leverage the Org-mode ecosystem:* 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.
- 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
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"
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 also introduce terms commonly used within
the Zettelkasten community, which will also commonly appear in the Org-roam
forums and channels of discussion.
appropriately. In this section we will introduce terms commonly used within the
Zettelkasten community and the Org-roam forums.
The Zettelkasten method of note-taking is designed to increase research
productivity: in particular, it acts as a research partner, where conversations
with it may produce new and surprising lines of thought. This method is
attributed to German sociologist Niklas Luhmann, who using the method had
produced volumes of written works.
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.
In its paper form, the slip-box is 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.
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.
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
plain-text, Org-mode file. These files are often placed in the same directory.
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. Org-roam also facilitates the linking of zettels using Org-mode ~file:~
links.
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.
** 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
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
@@ -249,8 +252,7 @@ dependencies that it requires. These include:
- emacsql-sqlite3
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
manage this.
may wish to use [[https://github.com/jwiegley/use-package][use-package]], [[https://github.com/raxod502/straight.el][straight.el]] to help manage this.
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
@@ -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]].
To first start using Org-roam, one needs to pick a location to store the
Org-roam files. The directory that will contain your notes, and database index
is specified by the variable ~org-roam-directory~. This variable needs to be set
before any calls to Org-roam functions, including enabling ~org-roam-mode~. For
this tutorial, create an empty directory, and set ~org-roam-directory~:
Org-roam files. The directory that will contain your notes is specified by the
variable ~org-roam-directory~. This variable needs to be set before any calls to
Org-roam functions, including enabling ~org-roam-mode~. For this tutorial,
create an empty directory, and set ~org-roam-directory~:
#+BEGIN_SRC emacs-lisp
(make-directory "~/org-roam")
@@ -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
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.
Instead of relying on the file hierarchy for any form of categorization, we
solely rely on links between files to establish connections between notes.
fine; Org-roam searches recursively within ~org-roam-directory~ 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.
Next, we need to enable the global minor mode ~org-roam-mode~. This sets up Emacs
with several hooks, builds a cache and keeps it consistent. We recommend
starting ~org-roam-mode~ on startup:
Next, we need to enable the global minor mode ~org-roam-mode~. This sets up
Emacs with several hooks, building a cache that is kept consistent as your
slip-box grows. We recommend starting ~org-roam-mode~ on startup:
#+BEGIN_SRC emacs-lisp
(add-hook 'after-init-hook 'org-roam-mode)
#+END_SRC
To build the cache manually, one can run ~M-x org-roam-db-build-cache~. The
cache is a sqlite database named ~org-roam.db~, which defaults to residing in
the root ~org-roam-directory~. Cache builds may take a while the first time, but
is often instantaneous in subsequent runs.
To build the cache manually, one can run ~M-x org-roam-db-build-cache~. Cache
builds may take a while the first time, but is often instantaneous in subsequent
runs because it only reprocesses modified files.
Let us now create our first note. Call ~M-x org-roam-find-file~. This shows a list
of titles for notes that reside in ~org-roam-directory~. It should show nothing
right now, since there are no notes in the directory. Entering the title of the
note you wish to create, and pressing ~RET~ should begin the note creation
process. This process uses ~org-capture~'s templating system, and can be freely
customized (see [[*The Templating System][The Templating System]]). Using the default template, pressing ~C-c
C-c~ finishes the note capture. Running ~M-x org-roam-find-file~ again should show
the note you have created, and selecting that entry will bring you to that note.
Let us now create our first note. Call ~M-x org-roam-find-file~. This shows a
list of titles for notes that reside in ~org-roam-directory~. It should show
nothing right now, since there are no notes in the directory. Entering the title
of the note you wish to create, and pressing ~RET~ should begin the note
creation process. This process uses ~org-capture~'s templating system, and can
be customized (see [[*The Templating System][The Templating System]]). Using the default template, pressing
~C-c C-c~ finishes the note capture. Running ~M-x org-roam-find-file~ again
should show the note you have created, and selecting that entry will bring you
to that note.
The crux of Org-roam is making it easy to create notes, and link them together.
To link notes together, we call ~M-x org-roam-insert~. This brings up a prompt
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 knowledge graph of inter-connected
notes.
Org-roam makes it easy to create notes, and link them together. To link notes
together, we call ~M-x org-roam-insert~. This brings up a prompt 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.
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
@@ -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
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 [[*Roam Protocol][Roam
Protocol]]).
navigate to the files, but this requires some additional setup (see [[*Roam
Protocol][Roam Protocol]]).
* Anatomy of an Org-roam File
The bulk of Org-roam's functionality is built on top of vanilla
Org-mode. However, to support additional functionality, Org-roam adds
several Org-roam-specific keywords. These functionality are not crucial
to effective use of Org-roam.
The bulk of Org-roam's functionality is built on top of vanilla Org-mode.
However, to support additional functionality, Org-roam adds several
Org-roam-specific keywords.
** Titles
@@ -1543,6 +1543,8 @@ are the solutions:
:INDEX: vr
:END:
* Footnotes
[fn:roam] To understand more about Roam, a collection of links are available in [[*Note-taking Workflows][Note-taking Workflows]].
# Local Variables:
# eval: (require 'ol-info)

153
org-roam.texi
View File

@@ -180,16 +180,17 @@ FAQ
@node Introduction
@chapter Introduction
Org-roam is a @uref{https://roamresearch.com/, Roam Research} replica built around the
all-powerful @uref{https://orgmode.org/, Org-mode}.
Org-roam is a tool for network thought. It reproduces some of @uref{https://roamresearch.com/, Roam
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
with Org-mode. With Org-roam, notes flow naturally, making note-taking
fun and easy. Org-roam should also work as a plug-and-play solution
for anyone already using Org-mode for their personal wiki.
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.
To understand more about Roam, a collection of links are available in
@ref{Note-taking Workflows}.
Org-roam gains its superpowers by leveraging the mature ecosystem around
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
mature ecosystem around Org-mode where possible. Eventually, we hope
@@ -199,29 +200,29 @@ Org-roam provides several benefits over other tooling:
@itemize
@item
Privacy and SecurityEdit your personal wiki completely offline, entirely
in your control. Encrypt your notes with GPG@.
@strong{Privacy and Security:} Keep your personal wiki entirely offline and in your
control. Encrypt your notes with GPG@.
@item
Longevity of Plain TextUnlike web solutions like Roam research, the notes
are first and foremost plain Org-mode files -- Org-roam simply builds up an
auxilliary database to give the personal wiki superpowers. Having your 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 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. Edit your plain-text notes
in notepad if all other editors cease to exist
about proprietary web solutions being taken down. The notes are still
functional even if Org-roam ceases to exist.
@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,
or open a PR@.
or open a pull request.
@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
Org-mode already puts Org-roam light-years ahead of many other solutions.
@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
available to Emacs.
@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''
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 also introduce terms commonly used within
the Zettelkasten community, which will also commonly appear in the Org-roam
forums and channels of discussion.
appropriately. In this section we will introduce terms commonly used within the
Zettelkasten community and the Org-roam forums.
The Zettelkasten method of note-taking is designed to increase research
productivity: in particular, it acts as a research partner, where conversations
with it may produce new and surprising lines of thought. This method is
attributed to German sociologist Niklas Luhmann, who using the method had
produced volumes of written works.
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.
In its paper form, the slip-box is 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.
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.
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
plain-text, Org-mode file. These files are often placed in the same directory.
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. Org-roam also facilitates the linking of zettels using Org-mode @code{file:}
links.
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.
@menu
* Fleeting notes::
@@ -300,7 +303,7 @@ links.
@node 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
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
@@ -449,8 +452,7 @@ emacsql-sqlite3
@end itemize
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
manage this.
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.
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
@@ -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}.
To first start using Org-roam, one needs to pick a location to store the
Org-roam files. The directory that will contain your notes, and database index
is specified by the variable @code{org-roam-directory}. This variable needs to be set
before any calls to Org-roam functions, including enabling @code{org-roam-mode}. For
this tutorial, create an empty directory, and set @code{org-roam-directory}:
Org-roam files. The directory that will contain your notes is specified by the
variable @code{org-roam-directory}. This variable needs to be set before any calls to
Org-roam functions, including enabling @code{org-roam-mode}. For this tutorial,
create an empty directory, and set @code{org-roam-directory}:
@lisp
(make-directory "~/org-roam")
@@ -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
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.
Instead of relying on the file hierarchy for any form of categorization, we
solely rely on links between files to establish connections between 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, one
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
with several hooks, builds a cache and keeps it consistent. We recommend
starting @code{org-roam-mode} on startup:
Next, we need to enable the global minor mode @code{org-roam-mode}. 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} on startup:
@lisp
(add-hook 'after-init-hook 'org-roam-mode)
@end lisp
To build the cache manually, one can run @code{M-x org-roam-db-build-cache}. The
cache is a sqlite database named @code{org-roam.db}, which defaults to residing in
the root @code{org-roam-directory}. Cache builds may take a while the first time, but
is often instantaneous in subsequent runs.
To build the cache manually, one can run @code{M-x org-roam-db-build-cache}. Cache
builds may take a while the first time, but is often instantaneous in subsequent
runs because it only reprocesses modified files.
Let us now create our first note. Call @code{M-x org-roam-find-file}. This shows a list
of titles for notes that reside in @code{org-roam-directory}. It should show nothing
right now, since there are no notes in the directory. Entering the title of the
note you wish to create, and pressing @code{RET} should begin the note creation
process. This process uses @code{org-capture}'s templating system, and can be freely
customized (see @ref{The Templating System}). Using the default template, pressing @code{C-c
C-c} finishes the note capture. Running @code{M-x org-roam-find-file} again should show
the note you have created, and selecting that entry will bring you to that note.
Let us now create our first note. Call @code{M-x org-roam-find-file}. This shows a
list of titles for notes that reside in @code{org-roam-directory}. It should show
nothing right now, since there are no notes in the directory. Entering the title
of the note you wish to create, and pressing @code{RET} should begin the note
creation process. This process uses @code{org-capture}'s templating system, and can
be customized (see @ref{The Templating System}). Using the default template, pressing
@code{C-c C-c} finishes the note capture. Running @code{M-x org-roam-find-file} again
should show the note you have created, and selecting that entry will bring you
to that note.
The crux of Org-roam is making it easy to create notes, and link them together.
To link notes together, we call @code{M-x org-roam-insert}. This brings up a prompt
with a list of title for existing notes. Selecting an existing entry will create
and insert a link to the current file. Entering a non-existent title will create
a new note with that title. Good usage of Org-roam requires liberally linking
files: this facilitates building up a dense knowledge graph of inter-connected
notes.
Org-roam makes it easy to create notes, and link them together. To link notes
together, we call @code{M-x org-roam-insert}. This brings up a prompt with a list of
title for existing notes. Selecting an existing entry will create and insert a
link to the current file. Entering a non-existent title will create a new note
with that title. Good usage of Org-roam requires liberally linking files: this
facilitates building up a dense graph of inter-connected notes.
Org-roam provides an interface to view backlinks. It shows backlinks for the
currently active Org-roam note, along with some surrounding context. To toggle
@@ -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
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 @ref{Roam Protocol, , Roam
Protocol}).
navigate to the files, but this requires some additional setup (see @ref{Roam Protocol}).
@node 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
Org-mode. However, to support additional functionality, Org-roam adds
several Org-roam-specific keywords. These functionality are not crucial
to effective use of Org-roam.
The bulk of Org-roam's functionality is built on top of vanilla Org-mode.
However, to support additional functionality, Org-roam adds several
Org-roam-specific keywords.
@menu
* Titles::