mirror of
https://github.com/org-roam/org-roam
synced 2025-08-11 13:07:24 -05:00
149 lines
7.7 KiB
HTML
149 lines
7.7 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<!-- Copyright (C) 2020-2020 Jethro Kuan <jethrokuan95@gmail.com>
|
|
|
|
You can redistribute this document and/or modify it under the terms
|
|
of the GNU General Public License as published by the Free Software
|
|
Foundation, either version 3 of the License, or (at your option) any
|
|
later version.
|
|
|
|
This document is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
General Public License for more details.
|
|
-->
|
|
<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<title>Getting Started (Org-roam User Manual)</title>
|
|
|
|
<meta name="description" content="Getting Started (Org-roam User Manual)">
|
|
<meta name="keywords" content="Getting Started (Org-roam User Manual)">
|
|
<meta name="resource-type" content="document">
|
|
<meta name="distribution" content="global">
|
|
<meta name="Generator" content="makeinfo">
|
|
<link href="index.html#Top" rel="start" title="Top">
|
|
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
|
<link href="index.html#Top" rel="up" title="Top">
|
|
<link href="Anatomy-of-an-Org_002droam-File.html#Anatomy-of-an-Org_002droam-File" rel="next" title="Anatomy of an Org-roam File">
|
|
<link href="Post_002dInstallation-Tasks.html#Post_002dInstallation-Tasks" rel="prev" title="Post-Installation Tasks">
|
|
<style type="text/css">
|
|
<!--
|
|
a.summary-letter {text-decoration: none}
|
|
blockquote.indentedblock {margin-right: 0em}
|
|
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
|
|
blockquote.smallquotation {font-size: smaller}
|
|
div.display {margin-left: 3.2em}
|
|
div.example {margin-left: 3.2em}
|
|
div.lisp {margin-left: 3.2em}
|
|
div.smalldisplay {margin-left: 3.2em}
|
|
div.smallexample {margin-left: 3.2em}
|
|
div.smalllisp {margin-left: 3.2em}
|
|
kbd {font-style: oblique}
|
|
pre.display {font-family: inherit}
|
|
pre.format {font-family: inherit}
|
|
pre.menu-comment {font-family: serif}
|
|
pre.menu-preformatted {font-family: serif}
|
|
pre.smalldisplay {font-family: inherit; font-size: smaller}
|
|
pre.smallexample {font-size: smaller}
|
|
pre.smallformat {font-family: inherit; font-size: smaller}
|
|
pre.smalllisp {font-size: smaller}
|
|
span.nolinebreak {white-space: nowrap}
|
|
span.roman {font-family: initial; font-weight: normal}
|
|
span.sansserif {font-family: sans-serif; font-weight: normal}
|
|
ul.no-bullet {list-style: none}
|
|
-->
|
|
</style>
|
|
<link rel="stylesheet" type="text/css" href="assets/page.css">
|
|
|
|
|
|
</head>
|
|
|
|
<body lang="en">
|
|
<a name="Getting-Started"></a>
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="Anatomy-of-an-Org_002droam-File.html#Anatomy-of-an-Org_002droam-File" accesskey="n" rel="next">Anatomy of an Org-roam File</a>, Previous: <a href="Installation.html#Installation" accesskey="p" rel="prev">Installation</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
|
|
</div>
|
|
<hr>
|
|
<a name="Getting-Started-1"></a>
|
|
<h2 class="chapter">5 Getting Started</h2>
|
|
|
|
<p>This short tutorial describes the essential commands used in Org-roam, to help
|
|
you get started.
|
|
</p>
|
|
<p>First, it is important to understand how Org-roam was designed. Org-roam was
|
|
built to support a workflow that was not possible with vanilla Org-mode. This
|
|
flow is modelled after the <a href="https://zettelkasten.de/">Zettelkasten Method</a>, and many of <a href="https://roamresearch.com">Roam Research’s</a>
|
|
workflows. Org-roam does not magically make note-taking better – this often
|
|
requires a radical change in your current note-taking workflow. To understand
|
|
more about the methods and madness, see <a href="Note_002dtaking-Workflows.html#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>:
|
|
</p>
|
|
<div class="lisp">
|
|
<pre class="lisp">(make-directory "~/org-roam")
|
|
(setq org-roam-directory "~/org-roam")
|
|
</pre></div>
|
|
|
|
<p>We encourage using a flat hierarchy for storing notes, but some prefer using
|
|
folders for storing specific kinds of notes (e.g. websites, papers). This is
|
|
fine; Org-roam searches recursively within <code>org-roam-directory</code> for any notes.
|
|
Instead of relying on the file hierarchy for any form of categorization, we
|
|
solely rely on links between files to establish connections between notes.
|
|
</p>
|
|
<p>Next, we need to enable the global minor mode <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>
|
|
<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>
|
|
<p>Let us now create our first note. Call <code>M-x org-roam-find-file</code>. This shows a list
|
|
of titles for notes that reside in <code>org-roam-directory</code>. It should show nothing
|
|
right now, since there are no notes in the directory. Entering the title of the
|
|
note you wish to create, and pressing <code>RET</code> should begin the note creation
|
|
process. This process uses <code>org-capture</code>’s templating system, and can be freely
|
|
customized (see <a href="The-Templating-System.html#The-Templating-System">The Templating System</a>). Using the default template, pressing <code>C-c
|
|
C-c</code> finishes the note capture. Running <code>M-x org-roam-find-file</code> again should show
|
|
the note you have created, and selecting that entry will bring you to that note.
|
|
</p>
|
|
<p>The crux of Org-roam is making it easy to create notes, and link them together.
|
|
To link notes together, we call <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>
|
|
<p>Org-roam provides an interface to view backlinks. It shows backlinks for the
|
|
currently active Org-roam note, along with some surrounding context. To toggle
|
|
the visibility of this buffer, call <code>M-x org-roam</code>.
|
|
</p>
|
|
<p>For a visual representation of the notes and their connections, Org-roam also
|
|
provides graphing capabilities, using Graphviz. It generates graphs with notes
|
|
as nodes, and links between them as edges. The generated graph can be used to
|
|
navigate to the files, but this requires some additional setup (see <a href="Roam-Protocol.html#Roam-Protocol">Roam
|
|
Protocol</a>).
|
|
</p>
|
|
<hr>
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="Anatomy-of-an-Org_002droam-File.html#Anatomy-of-an-Org_002droam-File" accesskey="n" rel="next">Anatomy of an Org-roam File</a>, Previous: <a href="Installation.html#Installation" accesskey="p" rel="prev">Installation</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
|
|
</div>
|
|
|
|
|
|
|
|
</body>
|
|
</html>
|