mirror of
https://github.com/org-roam/org-roam
synced 2025-08-03 12:27:23 -05:00
146 lines
7.6 KiB
HTML
146 lines
7.6 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>
|
|
|
|
|
|
</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">3 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 begin using Org-roam, one should set the ‘<samp>org-roam-directory</samp>’ to the directory
|
|
containing your notes. For this tutorial, create an empty directory, and set the
|
|
‘<samp>org-roam-directory</samp>’:
|
|
</p>
|
|
<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 ‘<samp>org-roam-directory</samp>’ for any notes.
|
|
Instead of relying on the file hierarchy for any form of categorization, we
|
|
solely rely on links between files to establish connections between notes.
|
|
</p>
|
|
<p>Next, we need to enable the global minor mode ‘<samp>org-roam-mode</samp>’. This sets up Emacs
|
|
with several hooks, builds a cache and keeps it consistent. We recommend
|
|
starting ‘<samp>org-roam-mode</samp>’ on startup:
|
|
</p>
|
|
<div class="lisp">
|
|
<pre class="lisp">(add-hook 'after-init-hook 'org-roam-mode)
|
|
</pre></div>
|
|
|
|
<p>To build the cache manually, one can run ‘<samp>M-x org-roam-db-build-cache</samp>’. The cache
|
|
is a sqlite database named ‘<samp>org-roam.db</samp>’, which defaults to residing in the root
|
|
‘<samp>org-roam-directory</samp>’. Cache builds may take a while the first time, but is often
|
|
instantaneous in subsequent runs.
|
|
</p>
|
|
<p>Let us now create our first note. Call ‘<samp>M-x org-roam-find-file</samp>’. This shows a list
|
|
of titles for notes that reside in ‘<samp>org-roam-directory</samp>’. It should show nothing
|
|
right now, since there are no notes in the directory. Entering the title of the
|
|
note you wish to create, and pressing ‘<samp>RET</samp>’ should begin the note creation
|
|
process. This process uses ‘<samp>org-capture</samp>’’s templating system, and can be freely
|
|
customized (see <a href="The-Templating-System.html#The-Templating-System">The Templating System</a>). Using the default template, pressing ‘<samp>C-c
|
|
C-c</samp>’ finishes the note capture. Running ‘<samp>M-x org-roam-find-file</samp>’ again should show
|
|
the note you have created, and selecting that entry will bring you to that note.
|
|
</p>
|
|
<p>The crux of Org-roam is making it easy to create notes, and link them together.
|
|
To link notes together, we call ‘<samp>M-x org-roam-insert</samp>’. This brings up a prompt
|
|
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 ‘<samp>M-x org-roam</samp>’.
|
|
</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>
|