From 1381b12c7924a758733f452d9508b4b39670818b Mon Sep 17 00:00:00 2001 From: jethrokuan Date: Sat, 17 Jul 2021 11:29:59 +0000 Subject: [PATCH] =?UTF-8?q?Deploying=20to=20gh-pages=20from=20=20@=20aee34?= =?UTF-8?q?67b3e89ddf49393584586252c2fb4509433=20=F0=9F=9A=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- manual.html | 933 +++++++++++++------------- org-roam.org | 1790 ++++++++++++++++++++++--------------------------- org-roam.texi | 702 ++++++++++--------- 3 files changed, 1611 insertions(+), 1814 deletions(-) diff --git a/manual.html b/manual.html index 11571f0..665cc68 100644 --- a/manual.html +++ b/manual.html @@ -60,10 +60,10 @@ Next:   [

Org-roam User Manual

-

This manual is for Org-roam version 1.2.3. +

This manual is for Org-roam version 2.0.0.

-

Copyright (C) 2020-2020 Jethro Kuan <jethrokuan95@gmail.com> +

Copyright (C) 2020-2021 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 @@ -87,19 +87,41 @@ General Public License for more details. • Getting Started   -• Files   +• Viewing the links   -• The Templating System   +• Node Properties   -• Concepts and Configuration   +• The Org-roam Buffer   -• Inserting Links   +• Styling Org-roam   + +• Completion   + +• Encryption   + +• Org-roam protocol   + +• Diagnosing and Repair   + +• Building Extensions   + +• The Org-mode Ecosystem   + +• Frequently Asked Questions   + +• Developer's Guide to Org-roam   + +• The Templating System   + +• Concepts and Configuration   + +• Inserting Links   • Completions   • Navigating Around   -• Encryption   +• Encryption   • Graphing   @@ -131,45 +153,49 @@ General Public License for more details. 

— The Detailed Node Listing —
 
-A Brief Introduction to the Zettelkasten Method
-
-
• Fleeting notes   - -• Permanent notes   - -
-
 Installation
• Installing from MELPA   • Installing from Apt   -• Installing from the Git Repository   +• Installing from Source   • Post-Installation Tasks   
 
-Files
+Getting Started
 
-
• File Titles   +• The Org-roam Node   -• File Tags   +• Links between Nodes   -• File Refs   +• Setting up Org-roam   + +• Creating and Linking Nodes   
 
-File Titles
+Node Properties
 
-
• Customizing Title Extraction   +• Standard Org properties   + +• Aliases   + +• Refs   
 
-File Tags
+Building Extensions
 
-
• Customizing Tag Extraction   +• Public Interface   + +
+
+Developer’s Guide to Org-roam
+
+
• Org-roam's Design Principles   
 
@@ -185,14 +211,12 @@ Concepts and Configuration
• Directories and Files   -• The Org-roam Buffer   +• The Org-roam Buffer   • Org-roam Files   • Org-roam Faces   -• The Database   - 
 
 Completions
@@ -306,27 +330,23 @@ Next: , P
 
 
1 Introduction

 
-
Org-roam is a tool for network thought. It reproduces some of Roam
-Research’s 1 features within the all-powerful Org-mode.
+
Org-roam is a tool for networked thought. It reproduces some of Roam
+Research’s 1 key features within 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 keeps closely to Org syntax, and will work for anyone already using
-Org-mode for their personal wiki.
+
Org-roam allows for effortless non-hierarchical note-taking: with Org-roam,
+notes flow naturally, making note-taking fun and easy. Org-roam augments the
+Org-mode syntax, and will work for anyone already using Org-mode for their
+personal wiki.
 

-
Org-roam gains its superpowers by leveraging the mature ecosystem around
-Org-mode. For example, it has first-class support for org-ref for citation
-management.
+
Org-roam leverages the mature ecosystem around Org-mode. For example, it has
+first-class support for org-ref for citation management, and is able to
+piggyback off Org’s excellent LaTeX and source-block evaluation capabilities.
 

-
Org-roam aims to implement the core features of Roam, leveraging the
-mature ecosystem around Org-mode where possible. Eventually, we hope
-to further introduce features enabled by the Emacs ecosystem.
-

-
Org-roam provides several benefits over other tooling:
+
Org-roam provides these benefits over other tooling:
 

 
    
-
  •  Privacy and Security: Keep your personal wiki entirely offline and in your
-control. Encrypt your notes with GPG.
+
  •  Privacy and Security: Your personal wiki belongs only to you, 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
@@ -339,12 +359,12 @@ functional even if Org-roam ceases to exist.
 you feel unhappy with any part of Org-roam, you may choose to extend Org-roam,
 or open a pull request.
 
-
  •  Leverage the Org-mode ecosystem: Over the years, Emacs and Org-mode has
+
  •  Leverage the Org-mode ecosystem: Over the decades, 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
-can inherit many of the powerful text-navigation and editing packages
+
  •  Built on Emacs: Emacs is also a fantastic interface for editing text, and
+Org-roam inherits many of the powerful text-navigation and editing packages
 available to Emacs.
 

 
@@ -356,18 +376,18 @@ Next: 
2 Target Audience

 
 
Org-roam is a tool that will appear unfriendly to anyone unfamiliar with Emacs
-and Org-mode, but is also extremely powerful to those willing to put effort in
-mastering the intricacies of the tools. Org-roam stands on the shoulders on
-giants. Emacs was first created in 1976, and remains a top tier tool for editing
+and Org-mode, but it is also extremely powerful to those willing to put effort
+inn mastering the intricacies. Org-roam stands on the shoulders of giants. Emacs
+was first created in 1976, and remains the tool of choice for many for editing
 text and designing textual interfaces. The malleability of Emacs allowed the
 creation of Org-mode, an all-purpose plain-text system for maintaining TODO
 lists, planning projects, and authoring documents. Both of these tools are
 incredibly vast and require significant time investment to master.
 

-
Org-roam assumes basic familiarity with these tools. It is not difficult to get
-up and running with basic text-editing functionality, but one will only fully
-appreciate the power of building Roam functionality into Emacs and Org-mode when
-the usage of these tools become more advanced.
+
Org-roam assumes only basic familiarity with these tools. It is not difficult to
+get up and running with basic text-editing functionality, but one will only
+fully appreciate the power of building Roam functionality into Emacs and
+Org-mode when the usage of these tools become more advanced.
 

 
One key advantage to Org-roam is that building on top of Emacs gives it
 malleability. This is especially important for note-taking workflows. It is our
@@ -424,20 +444,8 @@ 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  
-
• Permanent notes  
-

-
-

-

-

-Next: , Up: A Brief Introduction to the Zettelkasten Method   [Index]

-

-
3.1 Fleeting notes

-
+
Fleeting notes
+

 
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
@@ -445,13 +453,8 @@ need to be processed later on, or trashed. This is typically accomplished using
 functionality (see Daily-notes). This provides a central inbox for collecting
 thoughts, to be processed later into permanent notes.
 

-

-

-

-Previous: , Up: A Brief Introduction to the Zettelkasten Method   [Index]

-

-
3.2 Permanent notes

-
+
Permanent notes
+

 
Permanent notes are further split into two categories: literature notes and
 concept notes. Literature notes can be brief annotations on a particular
 source (e.g. book, website or paper), that you’d like to access later on.
@@ -459,6 +462,9 @@ Concept notes require much more care in authoring: they need to be
 self-explanatory and detailed. Org-roam’s templating system supports the
 addition of different templates to facilitate the creation of these notes.
 

+
For further reading on the Zettelkasten method, “How to Take Smart Notes” by
+Sonke Ahrens is a decent guide.
+

 

 

 

@@ -474,7 +480,7 @@ development repository.
 
 • Installing from Apt  
 
-• Installing from the Git Repository  
+• Installing from Source  
 
 • Post-Installation Tasks  
 
@@ -538,7 +544,7 @@ using:
 

 

 

-Next: , Previous: , Up: Installation   [Index]

+Next: , Previous: , Up: Installation   [Index]

 

 
4.2 Installing from Apt

 
@@ -552,11 +558,11 @@ using Apt:
 
Org-roam will then be autoloaded into Emacs.
 

 

-

+

 

 Next: , Previous: , Up: Installation   [Index]

 

-
4.3 Installing from the Git Repository

+
4.3 Installing from Source

 
 
You may install Org-roam directly from the repository on GitHub if you like.
 This will give you access to the latest version hours or days before it appears
@@ -650,22 +656,21 @@ file:
 

 

 

-Previous: , Up: Installation   [Index]

+Previous: , Up: Installation   [Index]

 

 
4.4 Post-Installation Tasks

 
-
Org-roam uses emacsql-sqlite3, which requires sqlite3 to be located on
-exec-path. Please ensure that sqlite3 is installed appropriately on your
-operating system. You can verify that this is the case by executing:
+
Org-roam requires sqlite3 to be locatable by Emacs (i.e. on exec-path).
+Please ensure that sqlite3 is installed appropriately on your operating
+system. You can verify that this is the case by executing 2:
 

 

 
(executable-find "sqlite3")
 

 
 
If you have sqlite3 installed, and executable-find still reports nil, then
-it is likely that the path to the executable is not a member of the Emacs
-variable exec-path. You may rectify this by manually adding the path within
-your Emacs configuration:
+the path to the executable is not a member of the Emacs variable exec-path.
+Rectify this by manually adding the path within your Emacs configuration:
 

 

 
(add-to-list 'exec-path "path/to/sqlite3")
@@ -674,306 +679,188 @@ your Emacs configuration:
 

 

 

-Next: , Previous: , Up: Top   [Index]

+Next: , Previous: , Up: Top   [Index]

 

 
5 Getting Started

 
-
This short tutorial describes the essential commands used in Org-roam, to help
-you get started.
+
+
+
+
+
+
• The Org-roam Node  
+
• Links between Nodes  
+
• Setting up Org-roam  
+
• Creating and Linking Nodes  
+

+
+

+

+

+Next: , Up: Getting Started   [Index]

+

+
5.1 The Org-roam Node

+
+
We first begin with some terminology we’ll use throughout the manual. We term
+the basic denomination in Org-roam a node. We define a node as follows:
 

-
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 Zettelkasten Method, and many of Roam Research’s
-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 Note-taking Workflows.
+

+
A node is any headline or top level file with an ID.
+

+

+
+
For example, with this example file content:
+

+

+
:PROPERTIES:
+:ID:       foo
+:END:
+#+title: Foo
+
+* Bar
+:PROPERTIES:
+:ID:       bar
+:END:
+

+
+
We create two nodes:
+

+
    
+
  •  A file node “Foo” with id foo.
+
+
  •  A headline node “Bar” with id bar.
+

+
+
Headlines without IDs will not be considered Org-roam nodes. Org IDs can be
+added to files or headlines via the interactive command M-x org-id-get-create.
+

+

+

+

+Next: , Previous: , Up: Getting Started   [Index]

+

+
5.2 Links between Nodes

+
+
We link between nodes using Org’s standard ID link (e.g. id:foo). While only
+ID links will be considered during the computation of links between nodes,
+Org-roam caches all other links in the documents for external use.
+

+

+

+

+Next: , Previous: , Up: Getting Started   [Index]

+

+
5.3 Setting up Org-roam

+
+
Org-roam’s capabilities stem from its aggressive caching: it crawls all files
+within org-roam-directory, keeping a cache of all its links and nodes, while
+making sure that the cache is consistent.
 

 
To first start using Org-roam, one needs to pick a location to store the
 Org-roam files. The directory that will contain your notes is specified by the
-variable 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:
+variable org-roam-directory. Org-roam searches recursively within
+org-roam-directory for notes. This variable needs to be set before any calls
+to Org-roam functions. For this tutorial, create an empty directory, and set
+org-roam-directory:
 

 

 
(make-directory "~/org-roam")
 (setq org-roam-directory "~/org-roam")
 

 
-
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 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, building a cache that is kept consistent as your
-slip-box grows. We recommend starting org-roam-mode on startup:
+
Next, we need to setup Org-roam to maintain cache consistency. This is achieved
+by running M-x org-roam-setup. To ensure that Org-roam is available on
+startup, one can place this in their Emacs configuration:
 

 

-
(add-hook 'after-init-hook 'org-roam-mode)
+
(require 'org-roam)
+(org-roam-setup)
 

 
 
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
+

+

+

+Previous: , Up: Getting Started   [Index]

+

+
5.4 TODO Creating and Linking Nodes

+
+
Org-roam makes it easy to create notes and link them together. There are 2 main
+functions for creating nodes:
+

+
    
+
  •  org-roam-node-insert: creates a node if it does not exist, and inserts a
+link to the node at point.
+
+
  •  org-roam-node-find: creates a node if it does not exist, and visits the
+node.
+

+
+
Let’s first try org-roam-node-find. Calling M-x org-roam-node-find will
+show a list of titles for nodes that reside in org-roam-directory. It should
+show nothing right now, since there are no notes in the directory. Enter the
+title of the note you wish to create, and press RET. This begins the note
 creation process. This process uses org-capture’s templating system, and can
 be customized (see The Templating System). Using the default template, pressing
 C-c C-c finishes the note capture.
 

-
By default, Org-roam updates the cache asynchronously in the background to
-avoid getting in the way of writing. Org-roam queues updates to the files,
-waits for you to be idle for 2 seconds, and then automatically triggers
-updating the cache. After the cache has been updated, running M-x
-org-roam-find-file again should show the note you have created, and selecting
-that entry will bring you to that note 2. One can customize the waiting
-time by setting org-roam-db-update-idle-seconds; or change the cache update
-to be triggered immediately after buffer save by setting
-org-roam-db-update-method to 'immediate.
-

-
For experienced org-capture users, the behavior of M-x org-roam-find-file 
-may seem unfamiliar: after finishing a capture with C-c C-c, you are returned  
-not to the original buffer from which you called M-x org-roam-find-file, but 
-to a buffer pointing to the note you just created. For the usual org-capture 
-behavior you can call M-x org-roam-capture instead of M-x org-roam-find-file. 
-

-
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
-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).
+
Now that we have a node, we can try inserting a link to the node using M-x
+org-roam-node-insert. This brings up the list of nodes, which should contain
+the node you just created. Selecting the node will insert an id: link to the
+node. If you instead entered a title that does not exist, you will once again be
+brought through the node creation process. To enable link auto-completion,
+see Completion.
 

 

-

+

 

-Next: , Previous: , Up: Top   [Index]

+Next: , Previous: , Up: Top   [Index]

 

-
6 Files

+
6 TODO Viewing the links

 
-
In Org-roam, notes typically consist of multiple files, where each file is a
-zettel.
-

-
While the bulk of Org-roam’s functionality is built on top of vanilla Org-mode,
-Org-roam adds several Org-roam-specific keywords to support additional
-functionality.
-

-
This section explains the important components of a file, and the extensions to
-Org-mode.
+
Org-roam provides an interface to view relationships with other notes
+(backlinks, reference links, unlinked references etc.). To pop up this info
+buffer, call M-x org-roam-buffer.
 

+

+

+

+Next: , Previous: , Up: Top   [Index]

+

+
7 TODO Node Properties

+
 
-
-
-
• File Titles  
+
• Standard Org properties  
 
• File Tags  
+
• Aliases  
 
• File Refs  
+
• Refs  
 

 

 
 

-

+

 

-Next: , Up: Files   [Index]

+Next: , Up: Node Properties   [Index]

 

-
6.1 File Titles

-
-
To easily find a note, a title needs to be prescribed to a note.
-

-
A note can have many titles: this allows a note to be referred to by different
-names, which is especially useful for topics or concepts with acronyms. For
-example, for a note like “World War 2”, it may be desirable to also refer to it
-using the acronym “WWII”.
-

-
Org-roam calls org-roam--extract-titles to extract titles. It uses the
-variable org-roam-title-sources, to control how the titles are extracted. The
-title extraction methods supported are:
-

-
    
-
  •  'title: This extracts the title using the file #+title property
-
-
  •  'headline: This extracts the title from the first headline in the Org file
-
-
  •  'alias: This extracts a list of titles using the #+roam_alias property.
-The aliases are space-delimited, and can be multi-worded using quotes.
-

-
-
Take for example the following org file:
-

-

-
#+title: World War 2
-#+roam_alias: "WWII" "World War II"
-
-* Headline
-

-
-
-
-
-
-
-
MethodTitles
'title’(“World War 2”)
'headline’(“Headline”)
'alias’(“WWII” “World War II”)

-
-
If no title is provided, Org-roam defaults to using the file-path.
-

-
-
-
• Customizing Title Extraction  
-

+
7.1 TODO Standard Org properties

 
 

-

+

 

-Up: File Titles   [Index]

+Next: , Previous: , Up: Node Properties   [Index]

 

-
6.1.1 Customizing Title Extraction

-
-
To control how Org-roam extracts titles, customize org-roam-title-sources. If
-all methods of title extraction return no results, the file-name is used as the
-note’s title.
-

-

-
User Option: org-roam-title-sources

-

-
The list of sources from which to retrieve a note title.
-Each element in the list is either:
-

-
-
    
-
  •  a symbol – this symbol corresponds to a title retrieval function, which
-returns the list of titles for the current buffer
-
      
-
    •  a list of symbols – symbols in the list are treated as with (1). The
-return value of this list is the first symbol in the list returning a
-non-nil value.
-
    
-
-
    The return results of the root list are concatenated.
-
    
-
    For example the setting: ’((title headline) alias) means the following:
-
    
-
      
-
    •  Return the ’title + ’alias, if the title of current buffer is non-empty;
-
-
    •  Or return ’headline + ’alias otherwise.
-
    
-
-
    The currently supported symbols are:
-
    
-
    'title
-The #+title property of org file.
-
    
-
    'alias
-The #+roam_alias property of the org file, using
-space-delimited strings.
-
    
-
    'headline
-The first headline in the org file.
-

-
-
Adding your own title extraction method requires two steps. First, define a
-method (defun org-roam--extract-titles-foo () ...), where foo a
-self-prescribed name for the title extraction method. This method takes no
-arguments, and returns a list of strings (titles). Finally, push the symbol
-foo into org-roam-title-sources. You may need to rebuild the cache from
-scratch to re-process all files to pick up the new titles.
-

-

-

-

-Next: , Previous: , Up: Files   [Index]

-

-
6.2 File Tags

-
-
Tags are used as meta-data for files: they facilitate interactions with notes
-where titles are insufficient. For example, tags allow for categorization of
-notes: differentiating between bibliographical and structure notes during
-interactive commands.
-

-
By default, tags are extracted from the #+roam_tags property. To add
-additional extraction methods, see Customizing Tag Extraction.
-

-
-
-
• Customizing Tag Extraction  
-

+
7.2 TODO Aliases

 
 

-

+

 

-Up: File Tags   [Index]

+Previous: , Up: Node Properties   [Index]

 

-
6.2.1 Customizing Tag Extraction

-
-
Org-roam calls org-roam--extract-tags to extract tags from files. The variable
-org-roam-tag-sources, to control how tags are extracted.
-

-

-
User Option: org-roam-tag-sources

-

-
-
Sources to obtain tags from.
-

-
It should be a list of symbols representing any of the following extraction
-methods:
-

-
'prop
-  Extract tags from the #+roam_tags property.
-  Tags are space delimited.
-  Tags may contain spaces if they are double-quoted.
-  e.g. #+roam_tags: TAG "tag with spaces"
-

-
'vanilla
-  Extract vanilla org-mode tags, including #+FILETAGS and
-  inherited tags.
-

-
'all-directories
-  Extract sub-directories relative to org-roam-directory.
-  That is, if a file is located at relative path foo/bar/file.org,
-  the file will have tags “foo” and “bar”.
-

-
'last-directory
-  Extract the last directory relative to ‘org-roam-directory’.
-  That is, if a file is located at relative path foo/bar/file.org,
-  the file will have tag \“bar\”.
-

-
'first-directory
-  Extract the first directory relative to org-roam-directory.
-  That is, if a file is located at relative path foo/bar/file.org,
-  the file will have tag “foo”
-

-
By default, only the 'prop extraction method is enabled. To enable the other
-extraction methods, you may modify org-roam-tag-sources, for example:
-

-

-
(setq org-roam-tag-sources '(prop last-directory))
-

-
-
Adding your own tag extraction method requires two steps. First, define a method
-(defun org-roam--extract-tags-foo (file) ...), where foo a self-prescribed
-name for the tag extraction method. This method takes the file path as an
-argument, and returns a list of strings (titles). Finally, push the symbol foo
-into org-roam-tag-sources. You may need to rebuild the cache from scratch to
-re-process all files to pick up the new tags.
-

-

-

-

-Previous: , Up: Files   [Index]

-

-
6.3 File Refs

+
7.3 TODO Refs

 
 
Refs are unique identifiers for files. For example, a note for a website may
 contain a ref:
@@ -1006,11 +893,195 @@ multiple papers in a series to share the same note, or an article has a citation
 key and a URL at the same time.
 

 

+

+

+Next: , Previous: , Up: Top   [Index]

+

+
8 TODO The Org-roam Buffer

+
+

+

+

+Next: , Previous: , Up: Top   [Index]

+

+
9 TODO Styling Org-roam

+
+

+

+

+Next: , Previous: , Up: Top   [Index]

+

+
10 TODO Completion

+
+

+

+

+Next: , Previous: , Up: Top   [Index]

+

+
11 TODO Encryption

+
+

+

+

+Next: , Previous: , Up: Top   [Index]

+

+
12 TODO Org-roam protocol

+
+

+

+

+Next: , Previous: , Up: Top   [Index]

+

+
13 TODO Diagnosing and Repair

+
+

+

+

+Next: , Previous: , Up: Top   [Index]

+

+
14 TODO Building Extensions

+
+
+
+
• Public Interface  
+

+
+

+

+

+Up: Building Extensions   [Index]

+

+
14.1 TODO Public Interface

+
+
Database (for developers)
+
    
+
  •  querying: (org-roam-db-query)
+
+
  •  updating full database: (org-roam-db-sync)
+
+
  •  update current file: (org-roam-db-update-file)
+
+
  •  remove file from database: (org-roam-db-clear-file)
+

+
+
Nodes:
+
    
+
  •  List all nodes
+
+
  •  Read a node in from completion
+
+
  •  Get node at point
+

+
+
Links:
+
    
+
  •  Get backlinks for node
+

+
+
Tags:
+
    
+
  •  Add tag to node
+
+
  •  delete tag for node
+
+
  •  Get tags for node
+

+
+
Aliases:
+
    
+
  •  Add alias to node
+
+
  •  Delete alias for node
+
+
  •  Get aliases for node
+

+
+
Ref:
+
    
+
  •  Add ref to node
+

+
+
Capture:
+

+
Navigation:
+
    
+
  •  Find or create a node
+

+
+

+

+

+Next: , Previous: , Up: Top   [Index]

+

+
15 TODO The Org-mode Ecosystem

+
+

+

+

+Next: , Previous: , Up: Top   [Index]

+

+
16 TODO Frequently Asked Questions

+
+

+

+

+Next: , Previous: , Up: Top   [Index]

+

+
17 TODO Developer’s Guide to Org-roam

+
+
+
+
• Org-roam's Design Principles  
+

+
+

+

+

+Up: Developer's Guide to Org-roam   [Index]

+

+
17.1 Org-roam’s Design Principles

+
+
Org-roam is primarily motivated by the need for a dual representation. We
+(humans) love operating in a plain-text environment. The syntax rules of
+Org-mode are simple and fit snugly within our brain. This also allows us to use
+the tools and packages we love to explore and edit our notes. Org-mode is simply
+the most powerful plain-text format available, with support for images, LaTeX,
+TODO planning and much more.
+

+
But this plain-text format is simply ill-suited for exploration of these notes:
+plain-text is simply not amenable for answering large-scale, complex queries
+(e.g. how many tasks do I have that are due by next week?). Interfaces such as
+Org-agenda slow to a crawl when the number of files becomes unwieldy, which
+can quickly become the case.
+

+
At its core, Org-roam provides a database abstraction layer, providing a dual
+representation of what’s already available in plain-text. This allows us
+(humans) to continue working with plain-text, while programs can utilize the
+database layer to perform complex queries. These capabilities include, but are
+not limited to:
+

+
    
+
  •  link graph traversal and visualization
+
+
  •  Instantaneous SQL-like queries on headlines
+
      
+
    •  What are my TODOs, scheduled for X, or due by Y?
+
    
+

+
+
All of these functionality is powered by this database abstraction layer. Hence,
+at its core Org-roam’s primary goal is to provide a resilient dual
+representation that is cheap to maintain, easy to understand, and is as
+up-to-date as it possibly can. Org-roam also then exposes an API to this
+database abstraction layer for users who would like to perform programmatic
+queries on their Org files.
+

+

 

 

-Next: , Previous: , Up: Top   [Index]

+Next: , Previous: , Up: Top   [Index]

 

-
7 The Templating System

+
18 The Templating System

 
 
Rather than creating blank files on org-roam-insert and org-roam-find-file,
 it may be desirable to prefill the file with templated content. This may
@@ -1051,7 +1122,7 @@ will be no prompt for template selection.
 

 Next: , Up: The Templating System   [Index]

 

-
7.1 Template Walkthrough

+
18.1 Template Walkthrough

 
 
To demonstrate the additions made to org-capture templates. Here, we walkthrough
 the default template, reproduced below.
@@ -1075,7 +1146,7 @@ automatically chooses this template for you.
 
 
  •  (function org-roam--capture-get-point) should not be changed.
 
-
  •  "%?" is the template inserted on each call to org-roam-capture--capture.
+
  •  "%?" is the template inserted on each call to org-roam-capture-.
 This template means don’t insert any content, but place the cursor here.
 
 
  •  :file-name is the file-name template for a new note, if it doesn’t yet
@@ -1100,7 +1171,7 @@ file, rather than narrowing to just the entry.
 
    
 Previous: , Up: The Templating System   [Index]
    
 
    • 
-
    7.2 Org-roam Template Expansion
    
+
    18.2 Org-roam Template Expansion
    
 
 
    Org-roam’s template definitions also extend org-capture’s template syntax, to
 allow prefilling of strings. We have seen a glimpse of this in Template
@@ -1141,7 +1212,7 @@ directly to provide its third argument to specify UTC.
 
    
 Next: , Previous: , Up: Top   [Index]
    
 
    
-
    8 Concepts and Configuration
    
+
    19 Concepts and Configuration
    
 
 
    The number of configuration options is deliberately kept small, to keep the
 Org-roam codebase manageable. However, we attempt to accommodate as many usage
@@ -1153,22 +1224,20 @@ org-roam.
 
-
-
    
 
    • Directories and Files  
 
    • The Org-roam Buffer  
+
    • The Org-roam Buffer  
 
    
 
    • Org-roam Files  
 
    
 
    • Org-roam Faces  
 
    • The Database  
-
    
 
    
 
 
    
 
    
 
    
-Next: , Up: Concepts and Configuration   [Index]
    
+Next: , Up: Concepts and Configuration   [Index]
    
 
    
-
    8.1 Directories and Files
    
+
    19.1 Directories and Files
    
 
 
    This section concerns the placement and creation of files.
 
    
@@ -1196,11 +1265,11 @@ with multiple Org-roam instances.
 
    
 
 
    
-
    
+
    
 
    
 Next: , Previous: , Up: Concepts and Configuration   [Index]
    
 
    
-
    8.2 The Org-roam Buffer
    
+
    19.2 The Org-roam Buffer
    
 
 
    The Org-roam buffer displays backlinks for the currently active Org-roam note.
 
    
@@ -1245,9 +1314,9 @@ Next: ,
 
    
 
    
 
    
-Next: , Previous: , Up: Concepts and Configuration   [Index]
    
+Next: , Previous: , Up: Concepts and Configuration   [Index]
    
 
    
-
    8.3 Org-roam Files
    
+
    19.3 Org-roam Files
    
 
 
    Org-roam files are created and prefilled using Org-roam’s templating
 system. The templating system is customizable (see The Templating System).
@@ -1255,9 +1324,9 @@ system. The templating system is customizable (see 
    
 
    
-Next: , Previous: , Up: Concepts and Configuration   [Index]
    
+Previous: , Up: Concepts and Configuration   [Index]
    
 
    
-
    8.4 Org-roam Faces
    
+
    19.4 Org-roam Faces
    
 
 
    Org-roam introduces several faces to distinguish links within the same buffer.
 These faces are enabled by default in Org-roam notes.
@@ -1278,39 +1347,12 @@ This distinguishes internal links from external links (e.g. external web links).
 
    The org-roam-link-invalid face is applied to links that are broken. These are
 links to files or IDs that cannot be found.
 
    
-
    
-
    
-
    
-Previous: , Up: Concepts and Configuration   [Index]
    
-
    
-
    8.5 TODO The Database
    
-
-
    Org-roam is backed by a Sqlite database.
-
    
-
    
-
    User Option: org-roam-db-update-method
    
-
    
-
    Method to update the Org-roam database.
-
    
-
    'immediate: Update the database immediately upon file changes.
-
    
-
    'idle-timer: Updates the database if dirty, if Emacs idles for
-org-roam-db-update-idle-seconds.
-
    
-
-
    
-
    User Option: org-roam-db-update-idle-seconds
    
-
    
-
    Number of idle seconds before triggering an Org-roam database update. This is
-only valid if org-roam-db-update-method is 'idle-timer.
-
    
-
 
    
 
    
 
    
 Next: , Previous: , Up: Top   [Index]
    
 
    
-
    9 Inserting Links
    
+
    20 Inserting Links
    
 
 
    The preferred mode of linking is via file links to files, and id links for
 headlines. This maintains the strongest compatibility with Org-mode, ensuring
@@ -1361,7 +1403,7 @@ harder to edit. Defaults to t.
 
    
 Next: , Previous: , Up: Top   [Index]
    
 
    
-
    10 Completions
    
+
    21 Completions
    
 
 
    Completions for Org-roam are provided via completion-at-point. Completion
 suggestions are implemented as separate functions. Org-roam installs all
@@ -1396,7 +1438,7 @@ to variable company-backends.
 
    
 Next: , Up: Completions   [Index]
    
 
    
-
    10.1 Link Completion
    
+
    21.1 Link Completion
    
 
 
    roam links support auto-completion via completion-at-point: simply call
 M-x completion-at-point within a roam link. That is, where the | character
@@ -1405,7 +1447,7 @@ represents the cursor:
 
      
 
    •  [[|]]: completes for a file title
 
-
    •  [[roam:]]: completes for a file title
+
    •  [[roam:|]]: completes for a file title
 
 
    •  [[*|]]: completes for a headline within this file
 
@@ -1414,6 +1456,9 @@ represents the cursor:
 
    •  [[roam:foo*|]] completes a headline within the file with title “foo”
 
    
 
+
    If you don’t see the literal display of your links like the above examples,
+call M-x org-toggle-link-display
+
    
 
    Completions account for the current input. For example, for [[f|]], the
 completions (by default) only show for files with titles that start with “f”.
 
    
@@ -1433,7 +1478,7 @@ completions (by default) only show for files with titles that start with “
 
    
 Up: Link Completion   [Index]
    
 
    
-
    10.1.1 Link Completions Everywhere
    
+
    21.1.1 Link Completions Everywhere
    
 
 
    Org-roam is able to provide completions from the current word at point, enabling
 as-you-type link completions. However, this is disabled by default: the author
@@ -1456,7 +1501,7 @@ completions for titles that begin with “sent”.
 
    
 Previous: , Up: Completions   [Index]
    
 
    
-
    10.2 Tag Completion
    
+
    21.2 Tag Completion
    
 
 
    Org-roam facilitates the insertion of existing tags via completion-at-point.
 
    
@@ -1469,9 +1514,9 @@ appear as-you-type if they match.
 
    
 
    
 
    
-Next: , Previous: , Up: Top   [Index]
    
+Next: , Previous: , Up: Top   [Index]
    
 
    
-
    11 Navigating Around
    
+
    22 Navigating Around
    
 
 
    
 
    • Index File  
@@ -1483,7 +1528,7 @@ Next: , Previous: <
 
    
 Up: Navigating Around   [Index]
    
 
-
    11.1 Index File
    
+
    22.1 Index File
    
 
 
    As your collection grows, you might want to create an index where you keep links
 to your main files.
@@ -1510,11 +1555,11 @@ title is "Index".
 
    
 
 
    
-
    
+
    
 
    
 Next: , Previous: , Up: Top   [Index]
    
 
    
-
    12 Encryption
    
+
    23 Encryption
    
 
 
    One may wish to keep private, encrypted files. Org-roam supports encryption (via
 GPG), which can be enabled for all new files by setting org-roam-encrypt-files
@@ -1534,9 +1579,9 @@ password prompts, you may wish to cache the password.
 
    
 
    
 
    
-Next: , Previous: , Up: Top   [Index]
    
+Next: , Previous: , Up: Top   [Index]
    
 
    
-
    13 Graphing
    
+
    24 Graphing
    
 
 
    Org-roam provides graphing capabilities to explore interconnections between
 notes. This is done by performing SQL queries and generating images using
@@ -1613,7 +1658,7 @@ the second option to set the browser and network file path:
 
    
 Next: , Up: Graphing   [Index]
    
 
    
-
    13.1 Graph Options
    
+
    24.1 Graph Options
    
 
 
    Graphviz provides many options for customizing the graph output, and Org-roam
 supports some of them. See https://graphviz.gitlab.io/_pages/doc/info/attrs.html
@@ -1652,7 +1697,7 @@ Example: '(("color" . "red"))
 
    
 Previous: , Up: Graphing   [Index]
    
 
-
    13.2 Excluding Nodes and Edges
    
+
    24.2 Excluding Nodes and Edges
    
 
 
    One may want to exclude certain files to declutter the graph.
 
    
@@ -1679,7 +1724,7 @@ are excluded.
 
    
 Next: , Previous: , Up: Top   [Index]
    
 
-
    14 Minibuffer Completion
    
+
    25 Minibuffer Completion
    
 
 
    Org-roam allows customization of which minibuffer completion system to use for
 its interactive commands. The default setting uses Emacs’ standard
@@ -1706,7 +1751,7 @@ commands, set:
 
    
 Next: , Previous: , Up: Top   [Index]
    
 
-
    15 Roam Protocol
    
+
    26 Roam Protocol
    
 
 
    Org-roam extends org-protocol with 2 protocols: the roam-file and roam-ref
 protocols.
@@ -1725,7 +1770,7 @@ protocols.
 
    
 Next: , Up: Roam Protocol   [Index]
    
 
-
    15.1 Installation
    
+
    26.1 Installation
    
 
 
    To enable Org-roam’s protocol extensions, you have to add the following to your
 init file:
@@ -1871,7 +1916,7 @@ file.
 
    
 Next: , Previous: , Up: Roam Protocol   [Index]
    
 
-
    15.2 The roam-file protocol
    
+
    26.2 The roam-file protocol
    
 
 
    This is a simple protocol that opens the path specified by the file
 key (e.g. org-protocol://roam-file?file=/tmp/file.org). This is used
@@ -1882,9 +1927,9 @@ in the generated graph.
 
    
 Previous: , Up: Roam Protocol   [Index]
    
 
-
    15.3 The roam-ref protocol
    
+
    26.3 The roam-ref protocol
    
 
-
    This protocol finds or creates a new note with a given roam_key (see Files):
+
    This protocol finds or creates a new note with a given roam_key:
 
    
 images/roam-ref
 
@@ -1916,7 +1961,7 @@ should contain a #+roam_key: ${ref} in it.
 
    
 Next: , Previous: , Up: Top   [Index]
    
 
-
    16 Daily-notes
    
+
    27 Daily-notes
    
 
 
    Org-roam provides journaling capabilities akin to
 Org-journal with org-roam-dailies.
@@ -1935,7 +1980,7 @@ Next: 
    , Up: Daily-notes   [Index]
    
 
-
    16.1 Configuration
    
+
    27.1 Configuration
    
 
 
    For org-roam-dailies to work, you need to define two variables:
 
    
@@ -1998,14 +2043,14 @@ template j will put its notes under the heading ‘Journal’.
 
    
 Next: , Previous: , Up: Daily-notes   [Index]
    
 
-
    16.2 Capturing and finding daily-notes
    
+
    27.2 Capturing and finding daily-notes
    
 
 
    
 
    Function: org-roam-dailies-capture-today &optional goto
    
 
    
 
    Create an entry in the daily note for today.
 
    
-
    When goto is non-nil, go the note without creating an entry.
+
    When goto is non-nil, go to the note without creating an entry.
 
    
 
 
    
@@ -2056,7 +2101,7 @@ creating an entry.
 
    
 Previous: , Up: Daily-notes   [Index]
    
 
-
    16.3 Navigation
    
+
    27.3 Navigation
    
 
 
    You can navigate between daily-notes:
 
    
@@ -2083,7 +2128,7 @@ Previous: Finding Unlinked References, Previous: , Up: Top   [Index]
    
 
-
    17 Diagnosing and Repairing Files
    
+
    28 Diagnosing and Repairing Files
    
 
 
    Org-roam provides a utility for diagnosing and repairing problematic files via
 org-roam-doctor. By default, org-roam-doctor runs the check on the current
@@ -2126,7 +2171,7 @@ taken provided in :actions.
 
    
 Next: , Previous: , Up: Top   [Index]
    
 
-
    18 Finding Unlinked References
    
+
    29 Finding Unlinked References
    
 
 
    Unlinked references are occurrences of strings of text that exactly match the
 title or alias of an existing note in the Org-roam database. Org-roam provides
@@ -2150,7 +2195,7 @@ unlinked references within encrypted files.
 
    
 Next: , Previous: , Up: Top   [Index]
    
 
-
    19 Performance Optimization
    
+
    30 Performance Optimization
    
 
 
    
 
    • Profiling Key Operations  
@@ -2164,14 +2209,14 @@ Next: , Previous: 
 Next: , Up: Performance Optimization   [Index]
    
 
-
    19.1 TODO Profiling Key Operations
    
+
    30.1 TODO Profiling Key Operations
    
 
 
    
 
    
 
    
 Previous: , Up: Performance Optimization   [Index]
    
 
    
-
    19.2 Garbage Collection
    
+
    30.2 Garbage Collection
    
 
 
    During the cache-build process, Org-roam generates a lot of in-memory
 data-structures (such as the Org file’s AST), which are discarded after use.
@@ -2191,7 +2236,7 @@ operations. To reduce the number of garbage collection processes, one may set
 
    
 Next: , Previous: , Up: Top   [Index]
    
 
-
    20 Appendix
    
+
    31 Appendix
    
 
 
    
 
    • Note-taking Workflows  
@@ -2205,7 +2250,7 @@ Next: , Previous: , Up: Appendix   [Index]
    
 
-
    20.1 Note-taking Workflows
    
+
    31.1 Note-taking Workflows
    
 
 
      
 
    •  Books
        
@@ -2238,7 +2283,7 @@ Next: , Up: , Up: Appendix   [Index]
        
 
-
        20.2 Ecosystem
        
+
        31.2 Ecosystem
        
 
 
        
 
        • Browsing History with winner-mode  
@@ -2258,7 +2303,7 @@ Previous: 
        , Up: Ecosystem   [Index]
        
 
-
        20.2.1 Browsing History with winner-mode
        
+
        31.2.1 Browsing History with winner-mode
        
 
 
        winner-mode is a global minor mode that allows one to undo and redo changes in
 the window configuration. It is included with GNU Emacs since version 20.
@@ -2281,7 +2326,7 @@ interactive functions:
 
        
 Next: , Previous: , Up: Ecosystem   [Index]
        
 
-
        20.2.2 Versioning Notes
        
+
        31.2.2 Versioning Notes
        
 
 
        Since Org-roam notes are just plain text, it is trivial to track changes in your
 notes database using version control systems such as Git. Simply initialize
@@ -2297,7 +2342,7 @@ versions of a tracked Org-roam note.
 
        
 Next: , Previous: , Up: Ecosystem   [Index]
        
 
-
        20.2.3 Full-text search interface with Deft
        
+
        31.2.3 Full-text search interface with Deft
        
 
 
        Deft provides a nice interface for browsing and filtering org-roam notes.
 
        
@@ -2325,22 +2370,6 @@ using el-patch:
 
 (eval-when-compile
   (require 'el-patch))
-
-(use-package deft
-  ;; same as above...
-  :config/el-patch
-  (defun deft-parse-title (file contents)
-    "Parse the given FILE and CONTENTS and determine the title.
-If `deft-use-filename-as-title' is nil, the title is taken to
-be the first non-empty line of the FILE.  Else the base name of the FILE is
-used as title."
-    (el-patch-swap (if deft-use-filename-as-title
-                       (deft-base-filename file)
-                     (let ((begin (string-match "^.+$" contents)))
-                       (if begin
-                           (funcall deft-parse-title-function
-                                    (substring contents begin (match-end 0))))))
-                   (org-roam-db--get-title file))))
 
 
 
        The Deft interface can slow down quickly when the number of files get huge.
@@ -2351,7 +2380,7 @@ used as title."
 
        
 Next: , Previous: , Up: Ecosystem   [Index]
        
 
-
        20.2.4 Org-journal
        
+
        31.2.4 Org-journal
        
 
 
        Org-journal provides journaling capabilities to Org-mode. A lot of its
 functionalities have been incorporated into Org-roam under the name
@@ -2374,7 +2403,7 @@ journal entries from the ideas you would write on a scratchpad.
 
        
 Previous: , Up: Ecosystem   [Index]
        
 
-
        20.2.5 Note-taking Add-ons
        
+
        31.2.5 Note-taking Add-ons
        
 
 
        These are some plugins that make note-taking in Org-mode more enjoyable.
 
        
@@ -2475,12 +2504,15 @@ Previous: , Up:
 
        Org-fc is a spaced repetition system that scales well with a large number of
 files. Other alternatives include org-drill, and pamparam.
 
        
+
        To use Anki for spaced repetition, anki-editor allows you to write your cards in
+Org-mode, and sync your cards to Anki via anki-connect.
+
        
 
        
 
        
 
        
 Next: , Previous: , Up: Top   [Index]
        
 
        
-
        21 FAQ
        
+
        32 FAQ
        
 
 
-
-
-
-
-
+
+
+
+
+
-
-
-
+
@@ -2637,8 +2667,6 @@ Previous: ,
 
-
-
        
 
        • How do I have more than one Org-roam directory?  
@@ -2496,7 +2528,7 @@ Next: , P
 
        
 Next: , Up: FAQ   [Index]
        
 
-
        21.1 How do I have more than one Org-roam directory?
        
+
        32.1 How do I have more than one Org-roam directory?
        
 
 
        Emacs supports directory-local variables, allowing the value of
 org-roam-directory to be different in different directories. It does this by
@@ -2520,7 +2552,7 @@ that directory, at least once.
 
        
 Next: , Previous: , Up: FAQ   [Index]
        
 
-
        21.2 How do I migrate from Roam Research?
        
+
        32.2 How do I migrate from Roam Research?
        
 
 
        Fabio has produced a command-line tool that converts markdown files exported
 from Roam Research into Org-roam compatible markdown. More instructions are
@@ -2531,7 +2563,7 @@ provided in the reposito
 
        
 Previous: , Up: FAQ   [Index]
        
 
-
        21.3 How do I create a note whose title already matches one of the candidates?
        
+
        32.3 How do I create a note whose title already matches one of the candidates?
        
 
 
        This situation arises when, for example, one would like to create a note titled
 “bar” when “barricade” already exists.
@@ -2610,21 +2642,19 @@ Previous: ,
 
        Index Entry  Section
        
 
         
        
 
        O
        org-roam-buffer: The Org-roam Buffer
        org-roam-buffer-height: The Org-roam Buffer
        org-roam-buffer-position: The Org-roam Buffer
        org-roam-buffer-width: The Org-roam Buffer
        org-roam-buffer-window-parameters: The Org-roam Buffer
        org-roam-buffer: The Org-roam Buffer (1)
        org-roam-buffer-height: The Org-roam Buffer (1)
        org-roam-buffer-position: The Org-roam Buffer (1)
        org-roam-buffer-width: The Org-roam Buffer (1)
        org-roam-buffer-window-parameters: The Org-roam Buffer (1)
        
 
        org-roam-completion-everywhere: Link Completions Everywhere
        
 
        org-roam-completion-functions: Completions
        
 
        org-roam-completion-ignore-case: Completions
        
 
        org-roam-dailies-capture-templates: Configuration
        
 
        org-roam-dailies-directory: Configuration
        
 
        org-roam-db-location: Directories and Files
        org-roam-db-update-idle-seconds: The Database
        org-roam-db-update-method: The Database
        
 
        org-roam-directory: Directories and Files
        org-roam-encrypt-files: Encryption
        org-roam-encrypt-files: Encryption (1)
        
 
        org-roam-file-exclude-regexp: Directories and Files
        
 
        org-roam-graph-edge-cites-extra-config: Graph Options
        
 
        org-roam-graph-edge-extra-config: Graph Options
        org-roam-link-auto-replace: Inserting Links
        
 
        org-roam-link-title-format: Inserting Links
        
 
        org-roam-link-use-custom-faces: Org-roam Faces
        org-roam-tag-sources: Customizing Tag Extraction
        org-roam-title-sources: Customizing Title Extraction
        
 
         
        
 
        
 
        Jump to:   O
@@ -2653,8 +2681,9 @@ Previous: ,
 
        (1)
        
 
        To understand more about Roam, a collection of links are available in Note-taking Workflows.
        
 
        (2)
        
-
        Depending on your completion framework, you may need to press TAB to
-see the list.
        
+
        Two easy ways to evaluate elisp: 1) Place the cursor after the closing
+paren and run ‘M-x eval-last-sexp RET’ or 2) Press ‘C-c C-c’ with your cursor in
+an Org file code block (like ‘#+BEGIN_SRC emacs-lisp’).
        
 
 
        
 
diff --git a/org-roam.org b/org-roam.org
index 109abfa..eaf6589 100644
--- a/org-roam.org
+++ b/org-roam.org
@@ -1,23 +1,23 @@
 #+title: Org-roam User Manual
 #+author: Jethro Kuan
 #+email: jethrokuan95@gmail.com
-#+date: 2020-2020
+#+date: 2020-2021
 #+language: en
 
 #+texinfo_deffn: t
 #+texinfo_dir_category: Emacs
 #+texinfo_dir_title: Org-roam: (org-roam).
-#+texinfo_dir_desc: Rudimentary Roam Replica for Emacs.
-#+subtitle: for version 1.2.3
+#+texinfo_dir_desc: Roam Research for Emacs.
+#+subtitle: for version 2.0.0
 
 #+options: H:4 num:3 toc:nil creator:t ':t
 #+property: header-args :eval never
 #+texinfo: @noindent
 
-This manual is for Org-roam version 1.2.3.
+This manual is for Org-roam version 2.0.0.
 
 #+BEGIN_QUOTE
-Copyright (C) 2020-2020 Jethro Kuan 
+Copyright (C) 2020-2021 Jethro Kuan 
 
 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
@@ -31,26 +31,22 @@ General Public License for more details.
 
 * Introduction
 
-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 tool for networked thought. It reproduces some of [[https://roamresearch.com/][Roam
+Research's]] [fn:roam] key features within [[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 keeps closely to Org syntax, and will work for anyone already using
-Org-mode for their personal wiki.
+Org-roam allows for effortless non-hierarchical note-taking: with Org-roam,
+notes flow naturally, making note-taking fun and easy. Org-roam augments the
+Org-mode syntax, and will work for anyone already using Org-mode for their
+personal wiki.
 
-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 leverages 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, and is able to
+piggyback off Org's excellent LaTeX and source-block evaluation capabilities.
 
-Org-roam aims to implement the core features of Roam, leveraging the
-mature ecosystem around Org-mode where possible. Eventually, we hope
-to further introduce features enabled by the Emacs ecosystem.
+Org-roam provides these benefits over other tooling:
 
-Org-roam provides several benefits over other tooling:
-
-- *Privacy and Security:* Keep your personal wiki entirely offline and in your
-  control. Encrypt your notes with GPG.
+- *Privacy and Security:* Your personal wiki belongs only to you, 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
@@ -60,28 +56,28 @@ Org-roam provides several benefits over other tooling:
 - *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 pull request.
-- *Leverage the Org-mode ecosystem:* Over the years, Emacs and Org-mode has
+- *Leverage the Org-mode ecosystem:* Over the decades, 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
-  can inherit many of the powerful text-navigation and editing packages
+- *Built on Emacs:* Emacs is also a fantastic interface for editing text, and
+  Org-roam inherits many of the powerful text-navigation and editing packages
   available to Emacs.
 
 * Target Audience
 
 Org-roam is a tool that will appear unfriendly to anyone unfamiliar with Emacs
-and Org-mode, but is also extremely powerful to those willing to put effort in
-mastering the intricacies of the tools. Org-roam stands on the shoulders on
-giants. Emacs was first created in 1976, and remains a top tier tool for editing
+and Org-mode, but it is also extremely powerful to those willing to put effort
+inn mastering the intricacies. Org-roam stands on the shoulders of giants. Emacs
+was first created in 1976, and remains the tool of choice for many for editing
 text and designing textual interfaces. The malleability of Emacs allowed the
 creation of Org-mode, an all-purpose plain-text system for maintaining TODO
 lists, planning projects, and authoring documents. Both of these tools are
 incredibly vast and require significant time investment to master.
 
-Org-roam assumes basic familiarity with these tools. It is not difficult to get
-up and running with basic text-editing functionality, but one will only fully
-appreciate the power of building Roam functionality into Emacs and Org-mode when
-the usage of these tools become more advanced.
+Org-roam assumes only basic familiarity with these tools. It is not difficult to
+get up and running with basic text-editing functionality, but one will only
+fully appreciate the power of building Roam functionality into Emacs and
+Org-mode when the usage of these tools become more advanced.
 
 One key advantage to Org-roam is that building on top of Emacs gives it
 malleability. This is especially important for note-taking workflows. It is our
@@ -132,7 +128,7 @@ 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
+*Fleeting notes*
 
 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
@@ -141,7 +137,7 @@ need to be processed later on, or trashed. This is typically accomplished using
 functionality (see [[*Daily-notes][Daily-notes]]). This provides a central inbox for collecting
 thoughts, to be processed later into permanent notes.
 
-** Permanent notes
+*Permanent notes*
 
 Permanent notes are further split into two categories: *literature notes* and
 *concept notes*. Literature notes can be brief annotations on a particular
@@ -150,6 +146,9 @@ Concept notes require much more care in authoring: they need to be
 self-explanatory and detailed. Org-roam's templating system supports the
 addition of different templates to facilitate the creation of these notes.
 
+For further reading on the Zettelkasten method, "How to Take Smart Notes" by
+Sonke Ahrens is a decent guide.
+
 * Installation
 
 Org-roam can be installed using Emacs' package manager or manually from its
@@ -212,7 +211,7 @@ using Apt:
 
 Org-roam will then be autoloaded into Emacs.
 
-** Installing from the Git Repository
+** Installing from Source
 
 You may install Org-roam directly from the repository on [[https://github.com/org-roam/org-roam][GitHub]] if you like.
 This will give you access to the latest version hours or days before it appears
@@ -294,40 +293,71 @@ install-info /path/to/my/info/files/org-roam.info /path/to/my/info/files/dir
 
 ** Post-Installation Tasks
 
-Org-roam uses ~emacsql-sqlite3~, which requires ~sqlite3~ to be located on
-~exec-path~. Please ensure that ~sqlite3~ is installed appropriately on your
-operating system. You can verify that this is the case by executing:
+Org-roam requires ~sqlite3~ to be locatable by Emacs (i.e. on ~exec-path~).
+Please ensure that ~sqlite3~ is installed appropriately on your operating
+system. You can verify that this is the case by executing [fn:2]:
 
 #+BEGIN_SRC emacs-lisp
   (executable-find "sqlite3")
 #+END_SRC
 
 If you have ~sqlite3~ installed, and ~executable-find~ still reports ~nil~, then
-it is likely that the path to the executable is not a member of the Emacs
-variable ~exec-path~. You may rectify this by manually adding the path within
-your Emacs configuration:
+the path to the executable is not a member of the Emacs variable ~exec-path~.
+Rectify this by manually adding the path within your Emacs configuration:
 
 #+BEGIN_SRC emacs-lisp
   (add-to-list 'exec-path "path/to/sqlite3")
 #+END_SRC
 
 * Getting Started
+** The Org-roam Node
 
-This short tutorial describes the essential commands used in Org-roam, to help
-you get started.
+We first begin with some terminology we'll use throughout the manual. We term
+the basic denomination in Org-roam a node. We define a node as follows:
 
-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 [[https://zettelkasten.de/][Zettelkasten Method]], and many of [[https://roamresearch.com][Roam Research's]]
-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 [[*Note-taking Workflows][Note-taking Workflows]].
+#+begin_quote
+A node is any headline or top level file with an ID.
+#+end_quote
 
-To first start using Org-roam, one needs to pick a location to store the
-Org-roam files. The directory that will contain your notes is specified by the
-variable ~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~:
+For example, with this example file content:
+
+#+begin_src org
+  :PROPERTIES:
+  :ID:       foo
+  :END:
+  ,#+title: Foo
+
+  ,* Bar
+  :PROPERTIES:
+  :ID:       bar
+  :END:
+#+end_src
+
+We create two nodes:
+
+1. A file node "Foo" with id ~foo~.
+2. A headline node "Bar" with id ~bar~.
+
+Headlines without IDs will not be considered Org-roam nodes. Org IDs can be
+added to files or headlines via the interactive command ~M-x org-id-get-create~.
+
+** Links between Nodes
+
+We link between nodes using Org's standard ID link (e.g. ~id:foo~). While only
+ID links will be considered during the computation of links between nodes,
+Org-roam caches all other links in the documents for external use.
+
+** Setting up Org-roam
+
+Org-roam's capabilities stem from its aggressive caching: it crawls all files
+within ~org-roam-directory~, and maintains a cache of all links and nodes.
+
+To start using Org-roam, pick a location to store the Org-roam files. The
+directory that will contain your notes is specified by the variable
+~org-roam-directory~. Org-roam searches recursively within ~org-roam-directory~
+for notes. This variable needs to be set before any calls to Org-roam functions.
+
+For this tutorial, create an empty directory, and set ~org-roam-directory~:
 
 #+BEGIN_SRC emacs-lisp
 (make-directory "~/org-roam")
@@ -337,725 +367,322 @@ create an empty directory, and set ~org-roam-directory~:
 The ~file-truename~ function is only necessary when you use symbolic links
 inside ~org-roam-directory~: Org-roam does not resolve symbolic links.
 
-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 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 setup Org-roam to run functions on file changes to maintain cache
+consistency. This is achieved by running ~M-x org-roam-setup~. To ensure that
+Org-roam is available on startup, place this in your Emacs configuration:
 
-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
+  (require 'org-roam)
+  (org-roam-setup)
+#+end_src
 
-#+BEGIN_SRC emacs-lisp
-(add-hook 'after-init-hook 'org-roam-mode)
-#+END_SRC
+To build the cache manually, run ~M-x org-roam-db-build-cache~. Cache builds may
+take a while the first time, but subsequent builds are often instantaneous
+because they only reprocess modified files.
 
-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.
+** Customizing Node Caching
 
-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
+By default, all nodes (any headline or file with an ID) are cached by Org-roam.
+There are instances where you may want to have headlines with ID, but not have
+them cached by Org-roam.
+
+To exclude a headline from the Org-roam database, set the ~ROAM_EXCLUDE~
+property to a non-nil value. For example:
+
+#+begin_src org
+,* Foo
+  :PROPERTIES:
+  :ID:       foo
+  :ROAM_EXCLUDE: t
+  :END:
+#+end_src
+
+One can also set ~org-roam-db-node-include-function~. For example, to exclude
+all headlines with the ~ATTACH~ tag from the Org-roam database, one can set:
+
+#+begin_src org
+(setq org-roam-db-node-include-function
+      (lambda ()
+        (not (member "ATTACH" (org-get-tags)))))
+#+end_src
+
+** TODO Creating and Linking Nodes
+
+Org-roam makes it easy to create notes and link them together. There are 2 main
+functions for creating nodes:
+
+- ~org-roam-node-insert~: creates a node if it does not exist, and inserts a
+  link to the node at point.
+- ~org-roam-node-find~: creates a node if it does not exist, and visits the
+  node.
+- ~org-roam-capture~: creates a node if it does not exist, and restores the
+  current window configuration upon completion.
+
+Let's first try ~org-roam-node-find~. Calling ~M-x org-roam-node-find~ will
+show a list of titles for nodes that reside in ~org-roam-directory~. It should
+show nothing right now, since there are no notes in the directory. Enter the
+title of the note you wish to create, and press ~RET~. This begins 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.
 
-By default, Org-roam updates the cache asynchronously in the background to
-avoid getting in the way of writing. Org-roam queues updates to the files,
-waits for you to be idle for 2 seconds, and then automatically triggers
-updating the cache. After the cache has been updated, running ~M-x
-org-roam-find-file~ again should show the note you have created, and selecting
-that entry will bring you to that note [fn:1]. One can customize the waiting
-time by setting ~org-roam-db-update-idle-seconds~; or change the cache update
-to be triggered immediately after buffer save by setting
-~org-roam-db-update-method~ to ~'immediate~.
+Now that we have a node, we can try inserting a link to the node using ~M-x
+org-roam-node-insert~. This brings up the list of nodes, which should contain
+the node you just created. Selecting the node will insert an ~id:~ link to the
+node. If you instead entered a title that does not exist, you will once again be
+brought through the node creation process.
 
-For experienced ~org-capture~ users, the behavior of ~M-x org-roam-find-file~ 
-may seem unfamiliar: after finishing a capture with ~C-c C-c~, you are returned  
-not to the original buffer from which you called ~M-x org-roam-find-file~, but 
-to a buffer pointing to the note you just created. For the usual ~org-capture~ 
-behavior you can call ~M-x org-roam-capture~ instead of ~M-x org-roam-find-file~. 
+One can also conveniently insert links via the completion-at-point functions
+Org-roam provides (see [[id:70083bfd-d1e3-42b9-bf83-5b05708791c0][Completion]]).
 
-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.
+* The Org-roam Buffer
 
-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 ~M-x org-roam~.
+Org-roam provides the Org-roam buffer: an interface to view relationships with
+other notes (backlinks, reference links, unlinked references etc.). There are
+two main functions to use here:
 
-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]]).
+- ~org-roam-buffer~: Launch an Org-roam buffer for the current node at point.
+- ~org-roam-buffer-toggle~: Launch an Org-roam buffer that tracks the node
+  currently at point. This means that the content of the buffer changes as the
+  point is moved, if necessary.
 
-* Files
-:PROPERTIES:
-:ID:       3edec3e6-8e26-4a43-8a0a-bf204268bbb3
-:END:
+Use ~org-roam-buffer-toggle~ when you want wish for the Org-roam buffer to
+buffer, call ~M-x org-roam-buffer~.
 
-In Org-roam, notes typically consist of multiple files, where each file is a
-zettel.
+- Function: org-roam-buffer
 
-While the bulk of Org-roam's functionality is built on top of vanilla Org-mode,
-Org-roam adds several Org-roam-specific keywords to support additional
-functionality.
+  Launch an Org-roam buffer for the current node at point.
 
-This section explains the important components of a file, and the extensions to
-Org-mode.
+To bring up a buffer that tracks the current node at point, call ~M-x
+org-roam-buffer-toggle~.
 
-** File Titles
+- Function: org-roam-buffer-toggle
 
-To easily find a note, a title needs to be prescribed to a note.
+  Toggle display of the ~org-roam-buffer~.
 
-A note can have many titles: this allows a note to be referred to by different
-names, which is especially useful for topics or concepts with acronyms. For
-example, for a note like "World War 2", it may be desirable to also refer to it
-using the acronym "WWII".
+** Navigating the Org-roam Buffer
 
-Org-roam calls ~org-roam--extract-titles~ to extract titles. It uses the
-variable ~org-roam-title-sources~, to control how the titles are extracted. The
-title extraction methods supported are:
+The Org-roam buffer uses ~magit-section~, making the typical ~magit-section~
+keybindings available. Here are several of the more useful ones:
 
-1. ~'title~: This extracts the title using the file ~#+title~ property
-2. ~'headline~: This extracts the title from the first headline in the Org file
-3. ~'alias~: This extracts a list of titles using the ~#+roam_alias~ property.
-   The aliases are space-delimited, and can be multi-worded using quotes.
+- ~M-{N}~: ~magit-section-show-level-{N}-all~
+- ~n~: ~magit-section-forward~
+-~~: ~magit-section-toggle~
+- ~~: ~org-roam-visit-thing~
 
-Take for example the following org file:
+~org-roam-visit-thing~ is a placeholder command, that is replaced by
+section-specific commands such as ~org-roam-node-visit~.
 
-#+BEGIN_SRC org
-  #+title: World War 2
-  #+roam_alias: "WWII" "World War II"
+** Configuring what is displayed in the buffer
 
-  * Headline
-#+END_SRC
+There are currently 3 provided widget types:
 
-| Method      | Titles                   |
-|-------------+--------------------------|
-| ~'title~    | '("World War 2")         |
-| ~'headline~ | '("Headline")            |
-| ~'alias~    | '("WWII" "World War II") |
+- Backlinks :: View (preview of) nodes that link to this node
+- Reference Links :: Nodes that reference this node (see [[id:57c1f991-be38-4fab-b27d-60227047f3b7][Refs]])
+- Unlinked references :: View nodes that contain text that match the nodes
+  title/alias but are not linked
 
-If no title is provided, Org-roam defaults to using the file-path.
+To configure what sections are displayed in the buffer, set ~org-roam-mode-sections~.
 
-*** Customizing Title Extraction
+#+begin_src emacs-lisp
+  (setq org-roam-mode-sections
+        (list #'org-roam-backlinks-section
+              #'org-roam-reflinks-section
+              ;; #'org-roam-unlinked-references-section
+              ))
+#+end_src
 
-To control how Org-roam extracts titles, customize ~org-roam-title-sources~. If
-all methods of title extraction return no results, the file-name is used as the
-note's title.
+Note that computing unlinked references may be slow, and has not been added in by default.
 
-- User Option: org-roam-title-sources
+** Configuring the Org-roam buffer display
 
-  The list of sources from which to retrieve a note title.
-  Each element in the list is either:
+Org-roam does not control how the pop-up buffer is displayed: this is left to
+the user. The author's recommended configuration is as follows:
 
-1. a symbol -- this symbol corresponds to a title retrieval function, which
-   returns the list of titles for the current buffer
-  2. a list of symbols -- symbols in the list are treated as with (1). The
-     return value of this list is the first symbol in the list returning a
-     non-nil value.
+#+begin_src emacs-lisp
+  (add-to-list 'display-buffer-alist
+               '(("\\*org-roam\\*"
+                  (display-buffer-in-direction)
+                  (direction . right)
+                  (window-width . 0.33)
+                  (window-height . fit-window-to-buffer))))
+#+end_src
 
-  The return results of the root list are concatenated.
+Crucially, the window is a regular window (not a side-window), and this allows
+for predictable navigation:
 
-  For example the setting: '((title headline) alias) means the following:
+- ~RET~ navigates to thing-at-point in the current window, replacing the
+  Org-roam buffer.
+- ~C-u RET~ navigates to thing-at-point in the other window.
 
-  1. Return the 'title + 'alias, if the title of current buffer is non-empty;
-  2. Or return 'headline + 'alias otherwise.
+** TODO Styling the Org-roam buffer
+* Node Properties
+** Standard Org properties
 
-  The currently supported symbols are:
+Org-roam caches most of the standard Org properties. The full list now includes:
 
-   ~'title~
-   The ~#+title~ property of org file.
+- outline level
+- todo state
+- priority
+- scheduled
+- deadline
+- tags
 
-   ~'alias~
-   The ~#+roam_alias~ property of the org file, using
-   space-delimited strings.
+** Titles and Aliases
 
-   ~'headline~
-   The first headline in the org file.
+Each node has a single title. For file nodes, this is specified with the
+`#+title` property for the file. For headline nodes, this is the main text.
 
-Adding your own title extraction method requires two steps. First, define a
-method ~(defun org-roam--extract-titles-foo () ...)~, where ~foo~ a
-self-prescribed name for the title extraction method. This method takes no
-arguments, and returns a list of strings (titles). Finally, push the symbol
-~foo~ into ~org-roam-title-sources~. You may need to rebuild the cache from
-scratch to re-process all files to pick up the new titles.
+Nodes can also have multiple aliases. Aliases allow searching for nodes via an
+alternative name. For example, one may want to assign a well-known acronym (AI)
+to a node titled "Artificial Intelligence".
 
-** File Tags
+To assign an alias to a node, add the "ROAM_ALIASES" property to the node:
 
-Tags are used as meta-data for files: they facilitate interactions with notes
-where titles are insufficient. For example, tags allow for categorization of
-notes: differentiating between bibliographical and structure notes during
-interactive commands.
+#+begin_src org
+  ,* Artificial Intelligence
+  :PROPERTIES:
+  :ROAM_ALIASES: AI
+  :END:
+#+end_src
 
-By default, tags are extracted from the ~#+roam_tags~ property. To add
-additional extraction methods, see [[id:c986edba-9498-4af1-b033-c94b733d42c8][Customizing Tag Extraction]].
+Alternatively, Org-roam provides some functions to add or remove aliases.
 
-*** Customizing Tag Extraction
-:PROPERTIES:
-:ID:       c986edba-9498-4af1-b033-c94b733d42c8
-:END:
+- Function: org-roam-alias-add alias
 
-Org-roam calls ~org-roam--extract-tags~ to extract tags from files. The variable
-~org-roam-tag-sources~, to control how tags are extracted.
+  Add ALIAS to the node at point. When called interactively, prompt for the
+  alias to add.
 
-- User Option: org-roam-tag-sources
+- Function: org-roam-alias-remove
 
-Sources to obtain tags from.
+  Remove an alias from the node at point.
 
-It should be a list of symbols representing any of the following extraction
-methods:
+** Tags
 
-  ~'prop~
-    Extract tags from the ~#+roam_tags~ property.
-    Tags are space delimited.
-    Tags may contain spaces if they are double-quoted.
-    e.g. ~#+roam_tags: TAG "tag with spaces"~
+Tags for top-level (file) nodes are pulled from the variable ~org-file-tags~,
+which is set by the ~#+filetags~ keyword, as well as other tags the file may
+have inherited. Tags for headline level nodes are regular Org tags.
 
-  ~'vanilla~
-    Extract vanilla org-mode tags, including ~#+FILETAGS~ and
-    inherited tags.
+Note that the ~#+filetags~ keyword results in tags being inherited by headers
+within the file. This makes it impossible for selective tag inheritance: i.e.
+either tag inheritance is turned off, or all headline nodes will inherit the
+tags from the file node. This is a design compromise of Org-roam.
 
-  ~'all-directories~
-    Extract sub-directories relative to ~org-roam-directory~.
-    That is, if a file is located at relative path foo/bar/file.org,
-    the file will have tags "foo" and "bar".
+** Refs
 
-  ~'last-directory~
-    Extract the last directory relative to `org-roam-directory'.
-    That is, if a file is located at relative path foo/bar/file.org,
-    the file will have tag \"bar\".
+Refs are unique identifiers for nodes. These keys allow references to the key to
+show up in the Org-roam buffer. For example, a node for a website may use the URL
+as the ref, and a node for a paper may use an Org-ref citation key.
 
-  ~'first-directory~
-    Extract the first directory relative to ~org-roam-directory~.
-    That is, if a file is located at relative path foo/bar/file.org,
-    the file will have tag "foo"
-    
-By default, only the ~'prop~ extraction method is enabled. To enable the other
-extraction methods, you may modify ~org-roam-tag-sources~, for example:
+To add a ref, add to the "ROAM_REFS" property as follows:
 
-#+BEGIN_SRC emacs-lisp
-(setq org-roam-tag-sources '(prop last-directory))
-#+END_SRC
+#+begin_src org
+  ,* Google
+  :PROPERTIES:
+  :ROAM_REFS: https://www.google.com/
+  :END:
+#+end_src
 
-Adding your own tag extraction method requires two steps. First, define a method
-~(defun org-roam--extract-tags-foo (file) ...)~, where ~foo~ a self-prescribed
-name for the tag extraction method. This method takes the file path as an
-argument, and returns a list of strings (titles). Finally, push the symbol ~foo~
-into ~org-roam-tag-sources~. You may need to rebuild the cache from scratch to
-re-process all files to pick up the new tags.
-
-** File Refs
-
-Refs are unique identifiers for files. For example, a note for a website may
-contain a ref:
-
-#+BEGIN_SRC org
-  #+title: Google
-  #+roam_key: https://www.google.com/
-#+END_SRC
-
-These keys allow references to the key to show up in the backlinks buffer. For
-instance, with the example above, if another file then links to
-https://www.google.com, that will show up as a “Ref Backlink”.
+With the above example, if another node links to https://www.google.com/, it
+will show up as a “reference backlink”.
 
 These keys also come in useful for when taking website notes, using the
  ~roam-ref~ protocol (see [[*Roam Protocol][Roam Protocol]]).
 
-[[https://github.com/jkitchin/org-ref][org-ref]] citation keys can also be used as refs:
-
-#+BEGIN_SRC org
-  #+title: Neural Ordinary Differential Equations
-  #+roam_key: cite:chen18_neural_ordin_differ_equat
-#+END_SRC
-
-#+CAPTION: org-ref-citelink
-[[file:images/org-ref-citelink.png]]
-
-You may assign multiple refs to a single file, for example when you want
+You may assign multiple refs to a single node, for example when you want
 multiple papers in a series to share the same note, or an article has a citation
 key and a URL at the same time.
 
-* The Templating System
+Org-roam also provides some functions to add or remove refs.
 
-Rather than creating blank files on ~org-roam-insert~ and ~org-roam-find-file~,
-it may be desirable to prefill the file with templated content. This may
-include:
+- Function: org-roam-ref-add ref
 
-- Time of creation
-- File it was created from
-- Clipboard content
-- Any other data you may want to input manually
+  Add REF to the node at point. When called interactively, prompt for the
+  ref to add.
 
-This requires a complex template insertion system. Fortunately, Org ships with a
-powerful one: ~org-capture~ (see info:org#capture). However, org-capture was not
-designed for such use. Org-roam abuses ~org-capture~, extending its syntax and
-capabilities. To first understand how org-roam's templating system works, it may
-be useful to look into basic usage of ~org-capture~.
+- Function: org-roam-ref-remove
 
-For these reasons, Org-roam capture templates are not compatible with regular
-~org-capture~. Hence, Org-roam's templates can be customized by instead
-modifying the variable ~org-roam-capture-templates~. Just like
-~org-capture-templates~, ~org-roam-capture-templates~ can contain multiple
-templates. If ~org-roam-capture-templates~ only contains one template, there
-will be no prompt for template selection.
+  Remove a ref from the node at point.
 
-** Template Walkthrough
+* Completion
+:PROPERTIES:
+:ID:       70083bfd-d1e3-42b9-bf83-5b05708791c0
+:END:
 
-To demonstrate the additions made to org-capture templates. Here, we walkthrough
-the default template, reproduced below.
+Completions for Org-roam are provided via ~completion-at-point~. Org-roam
+currently provides completions in two scenarios:
 
-#+BEGIN_SRC emacs-lisp
-  ("d" "default" plain (function org-roam--capture-get-point)
-       "%?"
-       :file-name "%<%Y%m%d%H%M%S>-${slug}"
-       :head "#+title: ${title}\n"
-       :unnarrowed t)
-#+END_SRC
+- When within an Org bracket link
+- Anywhere
 
-1. The template has short key ~"d"~. If you have only one template, org-roam
-   automatically chooses this template for you.
-2. The template is given a description of ~"default"~.
-3. ~plain~ text is inserted. Other options include Org headings via
-   ~entry~.
-4. ~(function org-roam--capture-get-point)~ should not be changed.
-5. ~"%?"~ is the template inserted on each call to ~org-roam-capture--capture~.
-   This template means don't insert any content, but place the cursor here.
-6. ~:file-name~ is the file-name template for a new note, if it doesn't yet
-   exist. This creates a file at path that looks like
-   ~/path/to/org-roam-directory/20200213032037-foo.org~. This template also
-   allows you to specify if you want the note to go into a subdirectory. For
-   example, the template ~private/${slug}~ will create notes in
-   ~/path/to/org-roam-directory/private~.
-7. ~:head~ contains the initial template to be inserted (once only), at
-   the beginning of the file. Here, the title global attribute is
-   inserted.
-8. ~:unnarrowed t~ tells org-capture to show the contents for the whole
-   file, rather than narrowing to just the entry.
+Completions are installed locally in all Org-roam files. To trigger completions,
+call ~M-x completion-at-point~. If using ~company-mode~, add ~company-capf~ to
+~company-backends~.
 
-Other options you may want to learn about include ~:immediate-finish~.
+Completions respect ~completion-styles~: the user is free to choose how
+candidates are matched. An example of a completion style that has grown in
+popularity is [[https://github.com/oantolin/orderless][orderless]].
 
-** Org-roam Template Expansion
+** Completing within Link Brackets
 
-Org-roam's template definitions also extend org-capture's template syntax, to
-allow prefilling of strings. We have seen a glimpse of this in [[*Template Walkthrough][Template
-Walkthrough]].
+Completions within link brackets are provided by
+~org-roam-complete-link-at-point~.
 
-In org-roam templates, the ~${var}~ syntax allows for the expansion of
-variables, stored in ~org-roam-capture--info~. For example, during
-~org-roam-insert~, the user is prompted for a title. Upon entering a
-non-existent title, the ~title~ key in ~org-roam-capture--info~ is set to the
-provided title. ~${title}~ is then expanded into the provided title during the
-org-capture process. Any variables that do not contain strings, are prompted for
-values using ~completing-read~.
+The completion candidates are the titles and aliases for all Org-roam nodes.
+Upon choosing a candidate, a ~roam:Title~ link will be inserted, linking to node
+of choice.
 
-After doing this expansion, the org-capture's template expansion system is used
-to fill up the rest of the template. You may read up more on this on
-[[https://orgmode.org/manual/Template-expansion.html#Template-expansion][org-capture's documentation page]].
+** Completing anywhere
 
-To illustrate this dual expansion process, take for example the template string:
-~"%<%Y%m%d%H%M%S>-${title}"~, with the title ~"Foo"~. The template is first
-expanded into ~%<%Y%m%d%H%M%S>-Foo~. Then org-capture expands ~%<%Y%m%d%H%M%S>~
-with timestamp: e.g. ~20200213032037-Foo~.
+The same completions can be triggered anywhere for the symbol at point if not
+within a bracketed link. This is provided by ~org-roam-complete-everywhere~.
+Similarly, the completion candidates are the titles and aliases for all Org-roam
+nodes, and upon choosing a candidate a ~roam:Title~ link will be inserted
+linking to the node of choice.
 
-All of the flexibility afforded by Emacs and Org-mode are available. For
-example, if you want to encode a UTC timestamp in the filename, you can take
-advantage of org-mode's ~%(EXP)~ template expansion to call ~format-time-string~
-directly to provide its third argument to specify UTC.
+This is disable by default. To enable it, set ~org-roam-completion-everywhere~
+to ~t~:
 
-#+BEGIN_SRC emacs-lisp
-  ("d" "default" plain (function org-roam--capture-get-point)
-       "%?"
-       :file-name "%(format-time-string \"%Y-%m-%d--%H-%M-%SZ--${slug}\" (current-time) t)"
-       :head "#+title: ${title}\n"
-       :unnarrowed t)
-#+END_SRC
+#+begin_src emacs-lisp
+(setq org-roam-completion-everywhere t)
+#+end_src
 
-* Concepts and Configuration
-The number of configuration options is deliberately kept small, to keep the
-Org-roam codebase manageable. However, we attempt to accommodate as many usage
-styles as possible.
+- Variable: org-roam-completion-everywhere
 
-All of Org-roam's customization options can be viewed via ~M-x customize-group
-org-roam~.
-
-** Directories and Files
-
-This section concerns the placement and creation of files.
-
-- Variable: org-roam-directory
-
-  This is the default path to Org-roam files. All Org files, at any level of
-  nesting, are considered part of the Org-roam.
-
-- Variable: org-roam-db-location
-
-  Location of the Org-roam database. If this is non-nil, the Org-roam sqlite
-  database is saved here.
-
-  It is the user’s responsibility to set this correctly, especially when used
-  with multiple Org-roam instances.
-
-- Variable: org-roam-file-exclude-regexp
-
-  Files matching this regular expression are excluded from the Org-roam.
-
-** The Org-roam Buffer
-
-The Org-roam buffer displays backlinks for the currently active Org-roam note.
-
-- User Option: org-roam-buffer
-
-  The name of the org-roam buffer. Defaults to ~*org-roam*~.
-
-- User Option: org-roam-buffer-position
-
-  The position of the Org-roam buffer side window. Valid values are ~'left~,
-  ~'right~, ~'top~, ~'bottom~.
-
-- User Option: org-roam-buffer-width
-
-  Width of ~org-roam-buffer~. Has an effect only if ~org-roam-buffer-position~ is
-  ~'left~ or ~'right~.
-
-- User Option: org-roam-buffer-height
-
-  Height of ~org-roam-buffer~. Has an effect only if ~org-roam-buffer-position~ is
-  ~'top~ or ~'bottom~.
-
-- User Option: org-roam-buffer-window-parameters
-
-  Additional window parameters for the org-roam-buffer side window.
-
-  For example one can prevent the window from being deleted when calling
-  ~delete-other-windows~, by setting it with the following:
-
-  ~(setq org-roam-buffer-window-parameters '((no-delete-other-windows . t)))~
-  
-** Org-roam Files
-
-Org-roam files are created and prefilled using Org-roam's templating
-system. The templating system is customizable (see [[*The Templating System][The Templating System]]).
-
-** Org-roam Faces
-
-Org-roam introduces several faces to distinguish links within the same buffer.
-These faces are enabled by default in Org-roam notes.
-
-- User Option: org-roam-link-use-custom-faces
-
-  When ~t~, use custom faces only inside Org-roam notes.
-  When ~everywhere~, the custom face is applied additionally to non Org-roam notes.
-  When ~nil~, do not use Org-roam's custom faces.
-
-The ~org-roam-link~ face is the face applied to links to other Org-roam files.
-This distinguishes internal links from external links (e.g. external web links).
-
-The ~org-roam-link-current~ face corresponds to links to the same file it is in.
-
-The ~org-roam-link-invalid~ face is applied to links that are broken. These are
-links to files or IDs that cannot be found.
-** TODO The Database
-
-Org-roam is backed by a Sqlite database.
-
-- User Option: org-roam-db-update-method
-
-  Method to update the Org-roam database.
-
-  ~'immediate~: Update the database immediately upon file changes.
-
-  ~'idle-timer~: Updates the database if dirty, if Emacs idles for
-  ~org-roam-db-update-idle-seconds~.
-
-- User Option: org-roam-db-update-idle-seconds
-
-  Number of idle seconds before triggering an Org-roam database update. This is
-  only valid if ~org-roam-db-update-method~ is ~'idle-timer~.
-
-* Inserting Links
-
-The preferred mode of linking is via ~file~ links to files, and ~id~ links for
-headlines. This maintains the strongest compatibility with Org-mode, ensuring
-that the links still function without Org-roam, and work well exporting to other
-backends.
-
-~file~ links can be inserted via ~org-roam-insert~. Links to headlines can be
-inserted by navigating to the desired headline and calling ~org-store-link~.
-This will create an ID for the headline if it does not already exist, and
-populate the Org-roam database. The link can then be inserted via
-~org-insert-link~.
-
-An alternative mode of insertion is using Org-roam's ~roam~ links. Org-roam
-registers this link type, and interprets the path as follows:
-
-- ~[[roam:title]]~ :: links to an Org-roam file with title or alias "title"
-- ~[[roam:*headline]]~ :: links to the headline "headline" in the current
-  Org-roam file
-- ~[[roam:title*headline]]~ :: links to the headline "headline" in the Org-roam
-  file with title or alias "title"
-
-- User Option: org-roam-link-title-format
-
-  To distinguish between org-roam links and regular links, one may choose to use
-  special indicators for Org-roam links. Defaults to ~"%s"~.
-
-  If your version of Org is at least ~9.2~, consider styling the link differently,
-  by customizing the ~org-roam-link~, and ~org-roam-link-current~ faces.
-
-- User Option: org-roam-link-auto-replace
-
-  When non-nil, ~roam~ links will be replaced with ~file~ or ~id~ links when
-  they are navigated to, and on file save, when a match is found. This is
-  desirable to maintain compatibility with vanilla Org, but resolved links are
-  harder to edit. Defaults to ~t~.
-
-* Completions
-
-Completions for Org-roam are provided via ~completion-at-point~. Completion
-suggestions are implemented as separate functions. Org-roam installs all
-functions in ~org-roam-completion-functions~ to ~completion-at-point-functions~.
-
-- Variable: org-roam-completion-functions
-
-  The list of functions to be used with ~completion-at-point~.
-
-- User Option: org-roam-completion-ignore-case
-
-  When non-nil, the ~roam~ link completions are ignore case. For example,
-  calling ~completion-at-point~ within ~[[roam:fo]]~ will present a completion
-  for a file with title "Foo". Defaults to ~t~.
-
-To use the completions from Org-roam with ~company-mode~, prepend ~company-capf~
-to variable ~company-backends~.
-
-** Link Completion
-
-~roam~ links support auto-completion via ~completion-at-point~: simply call
-~M-x completion-at-point~ within a roam link. That is, where the ~|~ character
-represents the cursor:
-
-- ~[[|]]~: completes for a file title
-- ~[[roam:]]~: completes for a file title
-- ~[[*|]]~: completes for a headline within this file
-- ~[[foo*|]]~: completes a headline within the file with title "foo"
-- ~[[roam:foo*|]]~ completes a headline within the file with title "foo"
-
-Completions account for the current input. For example, for ~[[f|]]~, the
-completions (by default) only show for files with titles that start with "f".
-
-- Function: org-roam-link-complete-at-point
-
-  Do appropriate completion for the link at point.
-
-*** Link Completions Everywhere
-
-Org-roam is able to provide completions from the current word at point, enabling
-as-you-type link completions. However, this is disabled by default: the author
-believes that linking should be a deliberate action and linking should be
-performed with great care.
-
-Setting ~org-roam-completion-everywhere~ to ~t~ will enable word-at-point
-completions.
-
-- User Option: org-roam-completion-everywhere
-
-  If non-nil, provide completions from the current word at point. That is, in
-  the scenario ~this is a sent|~, calling ~completion-at-point~ will show
-  completions for titles that begin with "sent".
-
-** Tag Completion
-
-Org-roam facilitates the insertion of existing tags via ~completion-at-point~.
-
-That is, suppose you have notes with tags "foo", and "bar". Now, in a note, if
-you're on a line beginning with ~#+roam_tags:~, completions for these will
-appear as-you-type if they match.
-
-This functionality is implemented in ~org-roam-complete-tags-at-point~.
-
-* Navigating Around
-** Index File
-
-As your collection grows, you might want to create an index where you keep links
-to your main files.
-
-In Org-roam, you can define the path to your index file by setting
-~org-roam-index-file~.
-
-- Variable: org-roam-index-file
-
-  Path to the Org-roam index file.
-
-  The path can be a string or a function. If it is a string, it should be the
-  path (absolute or relative to ~org-roam-directory~) to the index file. If it
-  is is a function, the function should return the path to the index file.
-  Otherwise, the index is assumed to be a note in ~org-roam-index~ whose
-  title is ~"Index"~.
-
-- Function: org-roam-find-index
-
-  Opens the Index file in the current ~org-roam-directory~.
+When non-nil, provide link completion matching outside of Org links.
 
 * Encryption
 
-One may wish to keep private, encrypted files. Org-roam supports encryption (via
-GPG), which can be enabled for all new files by setting ~org-roam-encrypt-files~
-to ~t~. When enabled, new files are created with the ~.org.gpg~ extension and
-decryption are handled automatically by EasyPG.
+Emacs has support for creating and editing encrypted gpg files, and Org-roam need
+not provide additional tooling. To create encrypted files, simply add the ~.gpg~
+extension in your Org-roam capture templates. For example:
 
-Note that Emacs will prompt for a password for encrypted files during cache
-updates if it requires reading the encrypted file. To reduce the number of
-password prompts, you may wish to cache the password.
+#+begin_src emacs-lisp
+(setq org-roam-capture-templates '(("d" "default" plain "%?"
+     :if-new (file+head "${slug}.org.gpg"
+                        "#+title: ${title}\n")
+     :unnarrowed t)))
+#+end_src
 
-- User Option: org-roam-encrypt-files
+* Org-roam Protocol
 
-  Whether to encrypt new files. If true, create files with .org.gpg extension.
-
-* Graphing
-
-Org-roam provides graphing capabilities to explore interconnections between
-notes. This is done by performing SQL queries and generating images using
-[[https://graphviz.org/][Graphviz]]. The graph can also be navigated: see [[*Roam Protocol][Roam Protocol]].
-
-The entry point to graph creation is ~org-roam-graph~.
-
-- Function: org-roam-graph & optional arg file node-query
-
-  Build and possibly display a graph for FILE from NODE-QUERY.
-  If FILE is nil, default to current buffer’s file name.
-  ARG may be any of the following values:
-
-  - ~nil~       show the graph.
-  - ~C-u~       show the graph for FILE.
-  - ~C-u N~     show the graph for FILE limiting nodes to N steps.
-  - ~C-u C-u~   build the graph.
-  - ~C-u -~     build the graph for FILE.
-  - ~C-u -N~    build the graph for FILE limiting nodes to N steps.
-
-- User Option: org-roam-graph-executable
-
-  Path to the graphing executable (in this case, Graphviz). Set this if Org-roam
-  is unable to find the Graphviz executable on your system.
-
-  You may also choose to use ~neato~ in place of ~dot~, which generates a more
-  compact graph layout.
-
-- User Option: org-roam-graph-viewer
-
-  Org-roam defaults to using Firefox (located on PATH) to view the SVG, but you
-  may choose to set it to:
-
-  1. A string, which is a path to the program used
-  2. a function accepting a single argument: the graph file path.
-
-  ~nil~ uses ~view-file~ to view the graph.
-  
-  If you are using WSL2 and would like to open the graph in Windows, you can use
-  the second option to set the browser and network file path:
-  
-  #+BEGIN_SRC emacs-lisp
-  (setq org-roam-graph-viewer
-      (lambda (file)
-        (let ((org-roam-graph-viewer "/mnt/c/Program Files/Mozilla Firefox/firefox.exe"))
-          (org-roam-graph--open (concat "file://///wsl$/Ubuntu" file)))))
-  #+END_SRC
-
-** Graph Options
-
-Graphviz provides many options for customizing the graph output, and Org-roam
-supports some of them. See https://graphviz.gitlab.io/_pages/doc/info/attrs.html
-for customizable options.
-
-- User Option: org-roam-graph-extra-config
-
-  Extra options passed to graphviz for the digraph (The "G" attributes).
-  Example: ~'~(("rankdir" . "LR"))~
-
-- User Option: org-roam-graph-node-extra-config
-
-  Extra options for nodes in the graphviz output (The "N" attributes).
-  Example: ~'(("color" . "skyblue"))~
-
-- User Option: org-roam-graph-edge-extra-config
-
-  Extra options for edges in the graphviz output (The "E" attributes).
-  Example: ~'(("dir" . "back"))~
-
-- User Option: org-roam-graph-edge-cites-extra-config
-
-  Extra options for citation edges in the graphviz output.
-  Example: ~'(("color" . "red"))~
-
-** Excluding Nodes and Edges
-
-One may want to exclude certain files to declutter the graph.
-
-- User Option: org-roam-graph-exclude-matcher
-
-  Matcher for excluding nodes from the generated graph. Any nodes and links for
-  file paths matching this string is excluded from the graph.
-
-  If value is a string, the string is the only matcher.
-
-  If value is a list, all file paths matching any of the strings
-  are excluded.
-
-#+BEGIN_EXAMPLE
-    (setq org-roam-graph-exclude-matcher '("private" "dailies"))
-#+END_EXAMPLE
-
-This setting excludes all files whose path contain "private" or "dailies".
-
-* Minibuffer Completion
-
-Org-roam allows customization of which minibuffer completion system to use for
-its interactive commands. The default setting uses Emacs' standard
-~completing-read~ mechanism.
-
-#+BEGIN_SRC emacs-lisp
-  (setq org-roam-completion-system 'default)
-#+END_SRC
-
-If you have installed Helm or Ivy, and have their modes enabled, under the
-~'default~ setting they will be used.
-
-In the rare scenario where you use Ivy globally, but prefer [[https://emacs-helm.github.io/helm/][Helm]] for org-roam
-commands, set:
-
-#+BEGIN_SRC emacs-lisp
-  (setq org-roam-completion-system 'helm)
-#+END_SRC
-
-Other options include ~'ido~, and ~'ivy~.
-
-* Roam Protocol
-
-Org-roam extends ~org-protocol~ with 2 protocols: the ~roam-file~ and ~roam-ref~
-protocols.
+Org-roam provides extensions for capturing content from external applications
+such as the browser, via ~org-protocol~. Org-roam extends ~org-protocol~ with 2
+protocols: the ~roam-node~ and ~roam-ref~ protocols.
 
 ** Installation
 
-To enable Org-roam's protocol extensions, you have to add the following to your
-init file:
+To enable Org-roam's protocol extensions, simply add the following to your init
+file:
 
 #+BEGIN_SRC emacs-lisp
 (require 'org-roam-protocol)
 #+END_SRC
 
-The instructions for setting up ~org-protocol~ are reproduced below.
-
-We will also need to create a desktop application for ~emacsclient~. The
-instructions for various platforms are shown below.
+We also need to set up ~org-protocol~: the instructions for setting up
+~org-protocol~ are reproduced below.
 
+*** Linux
 For Linux users, create a desktop application in
 ~~/.local/share/applications/org-protocol.desktop~:
 
@@ -1096,7 +723,8 @@ make the new policy take effect.
 See [[https://www.chromium.org/administrators/linux-quick-start][here]] for more info on the ~/etc/opt/chrome/policies/managed~ directory and
 [[https://cloud.google.com/docs/chrome-enterprise/policies/?policy=ExternalProtocolDialogShowAlwaysOpenCheckbox][here]] for information on the ~ExternalProtocolDialogShowAlwaysOpenCheckbox~ policy.
 
-For MacOS, we need to create our own application.
+*** Mac OS
+For Mac OS, we need to create our own application.
 
 1. Launch Script Editor
 2. Use the following script, paying attention to the path to ~emacsclient~:
@@ -1139,7 +767,6 @@ without confirmation. To do this, run in a shell:
 defaults write com.google.Chrome ExternalProtocolDialogShowAlwaysOpenCheckbox -bool true
 #+END_SRC
 
-
 If you're using [[https://github.com/railwaycat/homebrew-emacsmacport][Emacs Mac Port]], it registered its `Emacs.app` as the default
 handler for the URL scheme `org-protocol`. To make ~OrgProtocol.app~
 the default handler instead, run:
@@ -1151,6 +778,7 @@ defaults write com.apple.LaunchServices/com.apple.launchservices.secure LSHandle
 
 Then restart your computer.
 
+*** Windows
 For Windows, create a temporary ~org-protocol.reg~ file:
 
 #+BEGIN_SRC text
@@ -1175,15 +803,15 @@ Windows, replace the last line with:
 After executing the .reg file, the protocol is registered and you can delete the
 file.
 
-** The roam-file protocol
+** The roam-node protocol
 
-This is a simple protocol that opens the path specified by the ~file~
-key (e.g. ~org-protocol://roam-file?file=/tmp/file.org~). This is used
-in the generated graph.
+The roam-node protocol opens the node with ID specified by the ~node~ key (e.g.
+~org-protocol://roam-node?node=node-id~). ~org-roam-graph~ uses this to make the
+graph navigable.
 
 ** The roam-ref protocol
 
-This protocol finds or creates a new note with a given ~roam_key~ (see [[id:3edec3e6-8e26-4a43-8a0a-bf204268bbb3][Files]]):
+This protocol finds or creates a new note with a given ~roam_key~:
 
 [[file:images/roam-ref.gif]]
 
@@ -1210,7 +838,139 @@ where ~template~ is the template key for a template in
 ~org-roam-capture-ref-templates~ (see [[*The Templating System][The Templating System]]). These templates
 should contain a ~#+roam_key: ${ref}~ in it.
 
-* Daily-notes
+* The Org-roam Templating System
+
+Org-roam extends the ~org-capture~ system, providing a smoother note-taking
+experience. However, these extensions mean Org-roam capture templates are
+incompatible with ~org-capture~ templates.
+
+Org-roam's templates are specified by ~org-roam-capture-templates~. Just like
+~org-capture-templates~, ~org-roam-capture-templates~ can contain multiple
+templates. If ~org-roam-capture-templates~ only contains one template, there
+will be no prompt for template selection.
+
+** Template Walkthrough
+
+To demonstrate the additions made to org-capture templates. Here, we explain
+the default template, reproduced below. You will find some most of the elements
+of the template are similar to ~org-capture~ templates.
+
+#+BEGIN_SRC emacs-lisp
+(("d" "default" plain "%?"
+  :if-new (file+head "%<%Y%m%d%H%M%S>-${slug}.org"
+                     "#+title: ${title}\n")
+  :unnarrowed t))
+#+END_SRC
+
+1. The template has short key ~"d"~. If you have only one template, org-roam
+   automatically chooses this template for you.
+2. The template is given a description of ~"default"~.
+3. ~plain~ text is inserted. Other options include Org headings via
+   ~entry~.
+4. Notice that the ~target~ that's usually in Org-capture templates is missing
+   here.
+5. ~"%?"~ is the template inserted on each call to ~org-roam-capture-~.
+   This template means don't insert any content, but place the cursor here.
+6. ~:if-new~ is a compulsory specification in the Org-roam capture template.
+   This indicates the location for the new node.
+7. ~:unnarrowed t~ tells org-capture to show the contents for the whole file,
+   rather than narrowing to just the entry. This is part of the Org-capture
+   templates.
+
+See the ~org-roam-capture-templates~ documentation for more details and
+customization options.
+
+** Org-roam Template Expansion
+
+Org-roam's template definitions also extend org-capture's template syntax, to
+allow prefilling of strings. We have seen a glimpse of this in [[*Template Walkthrough][Template
+Walkthrough]].
+
+Org-roam provides the ~${foo}~ syntax for substituting variables with known
+strings. ~${foo}~'s substitution is performed as follows:
+
+1. If ~foo~ is a function, ~foo~ is called with the current node as its
+   argument.
+2. Else if ~org-roam-node-foo~ is a function, ~foo~ is called with the current node
+   as its argument. The ~org-roam-node-~ prefix defines many of Org-roam's node
+   accessors such as ~org-roam-node-title~ and ~org-roam-node-level~.
+3. Else look up ~org-roam-capture--info~ for ~foo~. This is an internal variable
+   that is set before the capture process begins.
+4. If none of the above applies, read a string using ~completing-read~.
+
+* Graphing
+
+Org-roam provides basic graphing capabilities to explore interconnections
+between notes, in ~org-roam-graph~. This is done by performing SQL queries and
+generating images using [[https://graphviz.org/][Graphviz]]. The graph can also be navigated: see [[*Roam Protocol][Roam
+Protocol]].
+
+The entry point to graph creation is ~org-roam-graph~.
+
+- Function: org-roam-graph & optional arg node
+
+Build and display a graph for NODE.
+ARG may be any of the following values:
+
+  - ~nil~       show the full graph.
+  - ~integer~   an integer argument ~N~ will show the graph for the connected
+                components to node up to ~N~ steps away.
+
+- User Option: org-roam-graph-executable
+
+  Path to the graphing executable (in this case, Graphviz). Set this if Org-roam
+  is unable to find the Graphviz executable on your system.
+
+  You may also choose to use ~neato~ in place of ~dot~, which generates a more
+  compact graph layout.
+
+- User Option: org-roam-graph-viewer
+
+  Org-roam defaults to using Firefox (located on PATH) to view the SVG, but you
+  may choose to set it to:
+
+  1. A string, which is a path to the program used
+  2. a function accepting a single argument: the graph file path.
+
+  ~nil~ uses ~view-file~ to view the graph.
+  
+  If you are using WSL2 and would like to open the graph in Windows, you can use
+  the second option to set the browser and network file path:
+  
+  #+BEGIN_SRC emacs-lisp
+  (setq org-roam-graph-viewer
+      (lambda (file)
+        (let ((org-roam-graph-viewer "/mnt/c/Program Files/Mozilla Firefox/firefox.exe"))
+          (org-roam-graph--open (concat "file://///wsl$/Ubuntu" file)))))
+  #+END_SRC
+
+** Graph Options
+
+Graphviz provides many options for customizing the graph output, and Org-roam
+supports some of them. See https://graphviz.gitlab.io/_pages/doc/info/attrs.html
+for customizable options.
+
+- User Option: org-roam-graph-filetype
+
+  The file type to generate for graphs. This defaults to ~"svg"~.
+
+- User Option: org-roam-graph-extra-config
+
+  Extra options passed to graphviz for the digraph (The "G" attributes).
+  Example: ~'~(("rankdir" . "LR"))~
+
+- User Option: org-roam-graph-node-extra-config
+
+  An alist of options to style the nodes.
+  The car of the alist node type such as ~"id"~, or ~"http"~. The cdr of the
+  list is another alist of Graphviz node options (the "N" attributes).
+
+- User Option: org-roam-graph-edge-extra-config
+
+  Extra options for edges in the graphviz output (The "E" attributes).
+  Example: ~'(("dir" . "back"))~
+
+* Org-roam Dailies
 
 Org-roam provides journaling capabilities akin to
 [[#org-journal][Org-journal]] with ~org-roam-dailies~.
@@ -1221,7 +981,7 @@ For ~org-roam-dailies~ to work, you need to define two variables:
 
 - Variable: ~org-roam-dailies-directory~
 
-  Path to daily-notes.
+  Path to daily-notes. This path is relative to ~org-roam-directory~.
 
 - Variable: ~org-roam-dailies-capture-templates~
 
@@ -1230,52 +990,26 @@ For ~org-roam-dailies~ to work, you need to define two variables:
 Here is a sane default configuration:
 
 #+begin_src emacs-lisp
-  (setq org-roam-dailies-directory "daily/")
+(setq org-roam-dailies-directory "daily/")
 
-  (setq org-roam-dailies-capture-templates
-        '(("d" "default" entry
-           #'org-roam-capture--get-point
-           "* %?"
-           :file-name "daily/%<%Y-%m-%d>"
-           :head "#+title: %<%Y-%m-%d>\n\n")))
+(setq org-roam-dailies-capture-templates
+      '(("d" "default" entry
+         "* %?"
+         :if-new (file+head "%<%Y-%m-%d>.org"
+                            "#+title: %<%Y-%m-%d>\n"))))
 #+end_src
 
-Make sure that ~org-roam-dailies-directory~ appears in ~:file-name~ for your
-notes to be recognized as daily-notes. You can have different templates placing
-their notes in different directories, but the one in
-~org-roam-dailies-directory~ will be considered as the main one in commands.
+See [[*The Templating System][The Templating System]] for creating new templates.
 
-See [[*The Templating System][The Templating System]] for creating new
-templates. ~org-roam-dailies~ provides an extra ~:olp~ option which allows
-specifying the outline-path to a heading:
+** Usage
 
-#+begin_src emacs-lisp
-  (setq org-roam-dailies-capture-templates
-        '(("l" "lab" entry
-           #'org-roam-capture--get-point
-           "* %?"
-           :file-name "daily/%<%Y-%m-%d>"
-           :head "#+title: %<%Y-%m-%d>\n"
-           :olp ("Lab notes"))
-
-          ("j" "journal" entry
-           #'org-roam-capture--get-point
-           "* %?"
-           :file-name "daily/%<%Y-%m-%d>"
-           :head "#+title: %<%Y-%m-%d>\n"
-           :olp ("Journal"))))
-#+end_src
-
-The template ~l~ will put its notes under the heading ‘Lab notes’, and the
-template ~j~ will put its notes under the heading ‘Journal’. 
-
-** Capturing and finding daily-notes
+~org-roam-dailies~ provides these interactive functions:
 
 - Function: ~org-roam-dailies-capture-today~ &optional goto
 
   Create an entry in the daily note for today.
 
-  When ~goto~ is non-nil, go the note without creating an entry.
+  When ~goto~ is non-nil, go to the note without creating an entry.
 
 - Function: ~org-roam-dailies-find-today~
 
@@ -1310,10 +1044,6 @@ There are also commands which allow you to use Emacs’s ~calendar~ to find the
 
   Prefer past dates, unless ~prefer-future~ is non-nil.
 
-** Navigation
-  
-You can navigate between daily-notes:
-
 - Function: ~org-roam-dailies-find-directory~
 
   Find and open ~org-roam-dailies-directory~.
@@ -1325,63 +1055,7 @@ You can navigate between daily-notes:
 - Function: ~org-roam-dailies-find-next-note~
 
   When in an daily-note, find the next one.
-
-* Diagnosing and Repairing Files
-
-Org-roam provides a utility for diagnosing and repairing problematic files via
-~org-roam-doctor~. By default, ~org-roam-doctor~ runs the check on the current
-Org-roam file. To run the check only for all Org-roam files, run ~C-u M-x
-org-roam-doctor~, but note that this may take some time.
-
-- Function: org-roam-doctor &optional this-buffer
-
-  Perform a check on Org-roam files to ensure cleanliness. If THIS-BUFFER, run
-  the check only for the current buffer.
-
-The checks run are defined in ~org-roam-doctor--checkers~. By default, there are
-checkers for broken links and invalid =#+roam_*= properties.
-
-Each checker is an instance of ~org-roam-doctor-checker~. To define a checker,
-use ~make-org-roam-doctor-checker~. Here is a sample definition:
-
-#+BEGIN_SRC emacs-lisp
-(make-org-roam-doctor-checker
-    :name 'org-roam-doctor-broken-links
-    :description "Fix broken links."
-    :actions '(("d" . ("Unlink" . org-roam-doctor--remove-link))
-               ("r" . ("Replace link" . org-roam-doctor--replace-link))
-               ("R" . ("Replace link (keep label)" . org-roam-doctor--replace-link-keep-label))))
-#+END_SRC
-
-The ~:name~ property is the name of the function run. The function takes in the
-Org parse tree, and returns a list of ~(point error-message)~. ~:description~ is
-a short description of what the checker does. ~:actions~ is an alist containing
-elements of the form ~(char . (prompt . function))~. These actions are defined
-per checker, to perform autofixes for the errors. For each error detected,
-~org-roam-doctor~ will move the point to the current error, and pop-up a help
-window displaying the error message, as well as the list of actions that can be
-taken provided in ~:actions~.
-
-* Finding Unlinked References
-
-Unlinked references are occurrences of strings of text that exactly match the
-title or alias of an existing note in the Org-roam database. Org-roam provides
-facilities for discovering these unlinked references, so one may decide whether
-to convert them into links.
-
-To use this feature, simply call ~M-x org-roam-unlinked-references~ from within
-an Org-roam note. Internally, Org-roam uses [[https://github.com/BurntSushi/ripgrep][ripgrep]] and a clever PCRE regex to
-find occurrences of the title or aliases of the currently open note in all
-Org-roam files. Hence, this requires a version of ripgrep that is compiled with
-PCRE support.
-
-#+begin_quote
-NOTE: Since ripgrep cannot read encrypted files, this function cannot find
-unlinked references within encrypted files.
-#+end_quote
-
 * Performance Optimization
-** TODO Profiling Key Operations
 ** Garbage Collection
 
 During the cache-build process, Org-roam generates a lot of in-memory
@@ -1398,13 +1072,337 @@ operations. To reduce the number of garbage collection processes, one may set
   (setq org-roam-db-gc-threshold most-positive-fixnum)
 #+END_SRC
 
+* The Org-mode Ecosystem
+
+Because Org-roam is built on top of Org-mode, it benefits from the vast number
+of packages already available.
+
+** Browsing History with winner-mode
+
+~winner-mode~ is a global minor mode that allows one to undo and redo changes in
+the window configuration. It is included with GNU Emacs since version 20.
+
+~winner-mode~ can be used as a simple version of browser history for Org-roam.
+Each click through org-roam links (from both Org files and the backlinks buffer)
+causes changes in window configuration, which can be undone and redone using
+~winner-mode~. To use ~winner-mode~, simply enable it, and bind the appropriate
+interactive functions:
+
+#+BEGIN_SRC emacs-lisp
+  (winner-mode +1)
+  (define-key winner-mode-map (kbd "") #'winner-undo)
+  (define-key winner-mode-map (kbd "") #'winner-redo)
+
+#+END_SRC
+** Versioning Notes
+
+Since Org-roam notes are just plain text, it is trivial to track changes in your
+notes database using version control systems such as [[https://git-scm.com/][Git]]. Simply initialize
+~org-roam-directory~ as a Git repository, and commit your files at regular or
+appropriate intervals. [[https://magit.vc/][Magit]] is a great interface to Git within Emacs.
+
+In addition, it may be useful to observe how a particular note has evolved, by
+looking at the file history. [[https://gitlab.com/pidu/git-timemachine][Git-timemachine]] allows you to visit historic
+versions of a tracked Org-roam note.
+
+** Full-text search with Deft
+
+[[https://jblevins.org/projects/deft/][Deft]] provides a nice interface for browsing and filtering org-roam notes.
+
+#+BEGIN_SRC emacs-lisp
+  (use-package deft
+    :after org
+    :bind
+    ("C-c n d" . deft)
+    :custom
+    (deft-recursive t)
+    (deft-use-filter-string-for-filename t)
+    (deft-default-extension "org")
+    (deft-directory org-roam-directory))
+#+END_SRC
+
+The Deft interface can slow down quickly when the number of files get huge.
+[[https://github.com/hasu/notdeft][Notdeft]] is a fork of Deft that uses an external search engine and indexer.
+
+** Org-journal
+
+[[https://github.com/bastibe/org-journal][Org-journal]] provides journaling capabilities to Org-mode. A lot of its
+functionalities have been incorporated into Org-roam under the name
+[[*Daily-notes][~org-roam-dailies~]]. It remains a good tool if you want to isolate your verbose
+journal entries from the ideas you would write on a scratchpad.
+
+#+BEGIN_SRC emacs-lisp
+  (use-package org-journal
+    :bind
+    ("C-c n j" . org-journal-new-entry)
+    :custom
+    (org-journal-date-prefix "#+title: ")
+    (org-journal-file-format "%Y-%m-%d.org")
+    (org-journal-dir "/path/to/journal/files/")
+    (org-journal-date-format "%A, %d %B %Y"))
+#+END_SRC
+
+** Org-download
+
+[[https://github.com/abo-abo/org-download][Org-download]] lets you screenshot and yank images from the web into your notes:
+
+#+CAPTION: org-download
+[[file:images/org-download.gif]]
+
+#+BEGIN_SRC emacs-lisp
+  (use-package org-download
+    :after org
+    :bind
+    (:map org-mode-map
+          (("s-Y" . org-download-screenshot)
+           ("s-y" . org-download-yank))))
+#+END_SRC
+
+** mathpix.el
+
+[[https://github.com/jethrokuan/mathpix.el][mathpix.el]] uses [[https://mathpix.com/][Mathpix's]] API to convert clips into latex equations:
+
+#+CAPTION: mathpix
+[[file:images/mathpix.gif]]
+
+#+BEGIN_SRC emacs-lisp
+  (use-package mathpix.el
+    :straight (:host github :repo "jethrokuan/mathpix.el")
+    :custom ((mathpix-app-id "app-id")
+             (mathpix-app-key "app-key"))
+    :bind
+    ("C-x m" . mathpix-screenshot))
+#+END_SRC
+
+** Org-noter / Interleave
+
+[[https://github.com/weirdNox/org-noter][Org-noter]] and [[https://github.com/rudolfochrist/interleave][Interleave]] are both projects that allow synchronised annotation of
+documents (PDF, EPUB etc.) within Org-mode.
+
+** Bibliography
+
+[[https://github.com/org-roam/org-roam-bibtex][org-roam-bibtex]] offers tight integration between [[https://github.com/jkitchin/org-ref][org-ref]], [[https://github.com/tmalsburg/helm-bibtex][helm-bibtex]] and
+~org-roam~. This helps you manage your bibliographic notes under ~org-roam~.
+
+For example, though helm-bibtex provides the ability to visit notes for
+bibliographic entries, org-roam-bibtex extends it with the ability to visit the
+file with the right =#+ROAM_KEYS=.
+
+** Spaced Repetition
+
+[[https://www.leonrische.me/fc/index.html][Org-fc]] is a spaced repetition system that scales well with a large number of
+files. Other alternatives include [[https://orgmode.org/worg/org-contrib/org-drill.html][org-drill]], and [[https://github.com/abo-abo/pamparam][pamparam]].
+
+To use Anki for spaced repetition, [[https://github.com/louietan/anki-editor][anki-editor]] allows you to write your cards in
+Org-mode, and sync your cards to Anki via [[https://github.com/FooSoft/anki-connect#installation][anki-connect]].
+
+* FAQ
+** How do I have more than one Org-roam directory?
+
+Emacs supports directory-local variables, allowing the value of
+~org-roam-directory~ to be different in different directories. It does this by
+checking for a file named ~.dir-locals.el~.
+
+To add support for multiple directories, override the ~org-roam-directory~
+variable using directory-local variables. This is what ~.dir-locals.el~ may
+contain:
+
+#+BEGIN_SRC emacs-lisp
+  ((nil . ((org-roam-directory . (expand-file-name "."))
+           (org-roam-db-location . (expand-file-name "./org-roam.db")))))
+#+END_SRC
+
+All files within that directory will be treated as their own separate set of
+Org-roam files. Remember to run ~org-roam-db-sync~ from a file within
+that directory, at least once.
+
+** How do I migrate from Roam Research?
+
+Fabio has produced a command-line tool that converts markdown files exported
+from Roam Research into Org-roam compatible markdown. More instructions are
+provided [[https://github.com/fabioberger/roam-migration][in the repository]].
+
+** How do I create a note whose title already matches one of the candidates?
+
+This situation arises when, for example, one would like to create a note titled
+"bar" when "barricade" already exists.
+
+The solution is dependent on the mini-buffer completion framework in use. Here
+are the solutions:
+
+- Ivy :: call ~ivy-immediate-done~, typically bound to ~C-M-j~. Alternatively,
+  set ~ivy-use-selectable-prompt~ to ~t~, so that "bar" is now selectable.
+- Helm :: Org-roam should provide a selectable "[?] bar" candidate at the top of
+  the candidate list.
+
+* Migrating from Org-roam v1
+
+Those coming from Org-roam v1 will do well treating v2 as entirely new software.
+V2 has a smaller core and fewer moving parts, while retaining the bulk of its
+functionality. It is recommended to read the documentation above about nodes.
+
+It is still desirable to migrate notes collected in v1 to v2. To migrate your v1
+notes to v2, you may use the migration script provided in [[https://gist.github.com/jethrokuan/02f41028fb4a6f81787dc420fb99b6e4][this gist]], or [[https://gist.github.com/jethrokuan/02f41028fb4a6f81787dc420fb99b6e4#gistcomment-3737019][this
+gist]], the latter being better tested. [[https://d12frosted.io/posts/2021-06-11-path-to-org-roam-v2.html][This blog post]] provides a good overview of
+what's new in v2 and how to migrate.
+
+Simply put, to migrate notes from v1 to v2, one must:
+
+1. Add IDs to all existing notes. These are located in top-level property
+   drawers (Although note that in v2, not all files need to have IDs)
+2. Update the Org-roam database to conform to the new schema.
+3. Replace ~#+ROAM_KEY~ into the ~ROAM_REFS~ property
+4. Replace ~#+ROAM_ALIAS~ into the ~ROAM_ALIASES~ property
+5. Move ~#+ROAM_TAGS~ into the ~#+FILETAGS~ property for file-level nodes, and
+   the ~ROAM_TAGS~ property for headline nodes
+6. Replace existing file links with ID links.
+
+* Developer's Guide to Org-roam
+** Org-roam's Design Principle
+
+Org-roam is primarily motivated by the need for a dual representation. We
+(humans) love operating in a plain-text environment. The syntax rules of
+Org-mode are simple and fit snugly within our brain. This also allows us to use
+the tools and packages we love to explore and edit our notes. Org-mode is simply
+the most powerful plain-text format available, with support for images, LaTeX,
+TODO planning and much more.
+
+But this plain-text format is simply ill-suited for exploration of these notes:
+plain-text is simply not amenable for answering large-scale, complex queries
+(e.g. how many tasks do I have that are due by next week?). Interfaces such as
+Org-agenda slow to a crawl when the number of files becomes unwieldy, which can
+quickly become the case.
+
+At its core, Org-roam provides a database abstraction layer, providing a dual
+representation of what's already available in plain-text. This allows us
+(humans) to continue working with plain-text, while programs can utilize the
+database layer to perform complex queries. These capabilities include, but are
+not limited to:
+
+- link graph traversal and visualization
+- Instantaneous SQL-like queries on headlines
+  - What are my TODOs, scheduled for X, or due by Y?
+- Accessing the properties of a node, such as its tags, refs, TODO state or
+  priority
+
+All of these functionality is powered by this database abstraction layer. Hence,
+at its core Org-roam's primary goal is to provide a resilient dual
+representation that is cheap to maintain, easy to understand, and is as
+up-to-date as it possibly can. Org-roam also then exposes an API to this
+database abstraction layer for users who would like to perform programmatic
+queries on their Org files.
+
+** Building Extensions and Advanced Customization of Org-roam
+
+Because Org-roam's core functionality is small, it is possible and sometimes
+desirable to build extensions on top of it. These extensions may one or more of
+the following functionalities:
+
+- Access to Org-roam's database
+- Usage/modification of Org-roam's interactive commands
+
+Org-roam provides no guarantees that extensions will continue to function as
+Org-roam evolves, but by following these simple rules, extensions can be made
+robust to local changes in Org-roam.
+
+1. Extensions should not modify the database schema. Any extension that requires
+   the caching of additional data should make a request upstream to Org-roam.
+2. Extensions requiring access to the database should explicitly state support
+   for the database version (~org-roam-db-version~), and only conditionally
+   load when support is available.
+
+*** Accessing the Database
+
+Access to the database is provided singularly by ~org-roam-db-query~, for
+example:
+
+#+begin_src emacs-lisp
+(org-roam-db-query [:select * :from nodes])
+#+end_src
+
+One can refer to the database schema by looking up
+~org-roam-db--table-schemata~. There are multiple helper functions within
+Org-roam that call ~org-roam-db-query~, these are subject to change. To ensure
+that extensions/customizations are robust to change, extensions should only use
+~org-roam-db-query~, and perhaps replicate the SQL query if necessary.
+
+*** Accessing and Modifying Nodes
+
+The node interface is cleanly defined using ~cl-defstruct~. The primary
+method to access nodes is ~org-roam-node-at-point~ and ~org-roam-node-read~:
+
+- Function: org-roam-node-at-point &optional assert
+
+  Return the node at point. If ASSERT, throw an error if there is no node at
+  point.
+
+- Function: org-roam-node-read &optional initial-input filter-fn sort-fn
+  require-match
+
+  Read and return an `org-roam-node'.
+  INITIAL-INPUT is the initial minibuffer prompt value. FILTER-FN
+  is a function to filter out nodes: it takes a single argument (an
+  ~org-roam-node~), and when nil is returned the node will be
+  filtered out.
+  SORT-FN is a function to sort nodes. See ~org-roam-node-sort-by-file-mtime~
+  for an example sort function.
+  If REQUIRE-MATCH, the minibuffer prompt will require a match.
+
+Once you obtain the node, you can use the accessors for the node, e.g.
+~org-roam-node-id~ or ~org-roam-node-todo~.
+
+It is possible to define (or override existing) properties on nodes. This is
+simply done using a ~cl-defmethod~ on the ~org-roam-node~ struct:
+
+#+begin_src emacs-lisp
+(cl-defmethod org-roam-node-namespace ((node org-roam-node))
+  "Return the namespace for NODE.
+The namespace is the final directory of the file for the node."
+  (file-name-nondirectory
+   (directory-file-name
+    (file-name-directory (org-roam-node-file node)))))
+#+end_src
+
+The snippet above defines a new property ~namespace~ on ~org-roam-node~, which
+making it available for use in capture templates.
+
+*** Extending the Capture System
+
+Org-roam applies some patching over Org's capture system to smooth out the user
+experience, and sometimes it is desirable to use Org-roam's capturing system
+instead. The exposed function to be used in extensions is ~org-roam-capture-~:
+
+- Function: org-roam-capture- &key goto keys node info props templates
+
+  Main entry point.
+  GOTO and KEYS correspond to `org-capture' arguments.
+  INFO is an alist for filling up Org-roam's capture templates.
+  NODE is an `org-roam-node' construct containing information about the node.
+  PROPS is a plist containing additional Org-roam properties for each template.
+  TEMPLATES is a list of org-roam templates.
+
+An example of an extension using ~org-roam-capture-~ is ~org-roam-dailies~
+itself:
+
+#+begin_src emacs-lisp
+(defun org-roam-dailies--capture (time &optional goto)
+  "Capture an entry in a daily-note for TIME, creating it if necessary.
+
+When GOTO is non-nil, go the note without creating an entry."
+  (org-roam-capture- :goto (when goto '(4))
+                     :node (org-roam-node-create)
+                     :templates org-roam-dailies-capture-templates
+                     :props (list :override-default-time time))
+  (when goto (run-hooks 'org-roam-dailies-find-file-hook)))
+#+end_src
+
 * _ Copying
 :PROPERTIES:
 :COPYING:    t
 :END:
 
 #+BEGIN_QUOTE
-Copyright (C) 2020-2020 Jethro Kuan 
+Copyright (C) 2020-2021 Jethro Kuan 
 
 You can redistribute this document and/or modify it under the terms
 of the GNU General Public License as published by the Free Software
@@ -1433,225 +1431,6 @@ General Public License for more details.
   - [[https://www.youtube.com/watch?v=RvWic15iXjk][How to Use Roam to Outline a New Article in Under 20 Minutes]]
 ** Ecosystem
 
-*** Browsing History with winner-mode
-
-~winner-mode~ is a global minor mode that allows one to undo and redo changes in
-the window configuration. It is included with GNU Emacs since version 20.
-
-~winner-mode~ can be used as a simple version of browser history for Org-roam.
-Each click through org-roam links (from both Org files and the backlinks buffer)
-causes changes in window configuration, which can be undone and redone using
-~winner-mode~. To use ~winner-mode~, simply enable it, and bind the appropriate
-interactive functions:
-
-#+BEGIN_SRC emacs-lisp
-  (winner-mode +1)
-  (define-key winner-mode-map (kbd "") #'winner-undo)
-  (define-key winner-mode-map (kbd "") #'winner-redo)
-
-#+END_SRC
-*** Versioning Notes
-
-Since Org-roam notes are just plain text, it is trivial to track changes in your
-notes database using version control systems such as [[https://git-scm.com/][Git]]. Simply initialize
-~org-roam-directory~ as a Git repository, and commit your files at regular or
-appropriate intervals. [[https://magit.vc/][Magit]] is a great interface to Git within Emacs.
-
-In addition, it may be useful to observe how a particular note has evolved, by
-looking at the file history. [[https://gitlab.com/pidu/git-timemachine][Git-timemachine]] allows you to visit historic
-versions of a tracked Org-roam note.
-
-*** Full-text search interface with Deft
-   :PROPERTIES:
-   :CUSTOM_ID: deft
-   :END:
-
-[[https://jblevins.org/projects/deft/][Deft]] provides a nice interface for browsing and filtering org-roam notes.
-
-#+BEGIN_SRC emacs-lisp
-  (use-package deft
-    :after org
-    :bind
-    ("C-c n d" . deft)
-    :custom
-    (deft-recursive t)
-    (deft-use-filter-string-for-filename t)
-    (deft-default-extension "org")
-    (deft-directory "/path/to/org-roam-files/"))
-#+END_SRC
-
-If the title of the Org file is not the first line, you might not get nice
-titles. You may choose to patch this to use ~org-roam~'s functionality. Here I'm
-using [[https://github.com/raxod502/el-patch][el-patch]]:
-
-#+BEGIN_SRC emacs-lisp
-  (use-package el-patch
-    :straight (:host github
-               :repo "raxod502/el-patch"
-               :branch "develop"))
-
-  (eval-when-compile
-    (require 'el-patch))
-
-  (use-package deft
-    ;; same as above...
-    :config/el-patch
-    (defun deft-parse-title (file contents)
-      "Parse the given FILE and CONTENTS and determine the title.
-  If `deft-use-filename-as-title' is nil, the title is taken to
-  be the first non-empty line of the FILE.  Else the base name of the FILE is
-  used as title."
-      (el-patch-swap (if deft-use-filename-as-title
-                         (deft-base-filename file)
-                       (let ((begin (string-match "^.+$" contents)))
-                         (if begin
-                             (funcall deft-parse-title-function
-                                      (substring contents begin (match-end 0))))))
-                     (org-roam-db--get-title file))))
-#+END_SRC
-
-The Deft interface can slow down quickly when the number of files get huge.
-[[https://github.com/hasu/notdeft][Notdeft]] is a fork of Deft that uses an external search engine and indexer.
-
-*** Org-journal
-   :PROPERTIES:
-   :CUSTOM_ID: org-journal
-   :END:
-
-[[https://github.com/bastibe/org-journal][Org-journal]] provides journaling capabilities to Org-mode. A lot of its
-functionalities have been incorporated into Org-roam under the name
-[[*Daily-notes][~org-roam-dailies~]]. It remains a good tool if you want to isolate your verbose
-journal entries from the ideas you would write on a scratchpad.
-
-#+BEGIN_SRC emacs-lisp
-  (use-package org-journal
-    :bind
-    ("C-c n j" . org-journal-new-entry)
-    :custom
-    (org-journal-date-prefix "#+title: ")
-    (org-journal-file-format "%Y-%m-%d.org")
-    (org-journal-dir "/path/to/journal/files/")
-    (org-journal-date-format "%A, %d %B %Y"))
-#+END_SRC
-
-*** Note-taking Add-ons
-   :PROPERTIES:
-   :CUSTOM_ID: note-taking-add-ons
-   :END:
-
-These are some plugins that make note-taking in Org-mode more enjoyable.
-
-**** Org-download
-    :PROPERTIES:
-    :CUSTOM_ID: org-download
-    :END:
-
-[[https://github.com/abo-abo/org-download][Org-download]] lets you screenshot and yank images from the web into your notes:
-
-#+CAPTION: org-download
-[[file:images/org-download.gif]]
-
-#+BEGIN_SRC emacs-lisp
-  (use-package org-download
-    :after org
-    :bind
-    (:map org-mode-map
-          (("s-Y" . org-download-screenshot)
-           ("s-y" . org-download-yank))))
-#+END_SRC
-
-**** mathpix.el
-    :PROPERTIES:
-    :CUSTOM_ID: mathpix.el
-    :END:
-
-[[https://github.com/jethrokuan/mathpix.el][mathpix.el]] uses [[https://mathpix.com/][Mathpix's]] API to convert clips into latex equations:
-
-#+CAPTION: mathpix
-[[file:images/mathpix.gif]]
-
-#+BEGIN_SRC emacs-lisp
-  (use-package mathpix.el
-    :straight (:host github :repo "jethrokuan/mathpix.el")
-    :custom ((mathpix-app-id "app-id")
-             (mathpix-app-key "app-key"))
-    :bind
-    ("C-x m" . mathpix-screenshot))
-#+END_SRC
-
-**** Org-noter / Interleave
-    :PROPERTIES:
-    :CUSTOM_ID: org-noter-interleave
-    :END:
-
-[[https://github.com/weirdNox/org-noter][Org-noter]] and
-[[https://github.com/rudolfochrist/interleave][Interleave]] are both
-projects that allow synchronised annotation of documents (PDF, EPUB
-etc.) within Org-mode.
-
-**** Bibliography
-    :PROPERTIES:
-    :CUSTOM_ID: bibliography
-    :END:
-
-[[https://github.com/org-roam/org-roam-bibtex][org-roam-bibtex]] offers
-tight integration between
-[[https://github.com/jkitchin/org-ref][org-ref]],
-[[https://github.com/tmalsburg/helm-bibtex][helm-bibtex]] and
-~org-roam~. This helps you manage your bibliographic notes under
-~org-roam~.
-
-For example, though helm-bibtex provides the ability to visit notes for
-bibliographic entries, org-roam-bibtex extends it with the ability to visit the
-file with the right =#+roam_key=.
-
-**** Spaced Repetition
-    :PROPERTIES:
-    :CUSTOM_ID: spaced-repetition
-    :END:
-
-[[https://www.leonrische.me/fc/index.html][Org-fc]] is a spaced repetition system that scales well with a large number of
-files. Other alternatives include [[https://orgmode.org/worg/org-contrib/org-drill.html][org-drill]], and [[https://github.com/abo-abo/pamparam][pamparam]].
-
-* FAQ
-** How do I have more than one Org-roam directory?
-
-Emacs supports directory-local variables, allowing the value of
-~org-roam-directory~ to be different in different directories. It does this by
-checking for a file named ~.dir-locals.el~.
-
-To add support for multiple directories, override the ~org-roam-directory~
-variable using directory-local variables. This is what ~.dir-locals.el~ may
-contain:
-
-#+BEGIN_SRC emacs-lisp
-  ((nil . ((org-roam-directory . (expand-file-name "."))
-           (org-roam-db-location . (expand-file-name "./org-roam.db")))))
-#+END_SRC
-
-All files within that directory will be treated as their own separate set of
-Org-roam files. Remember to run ~org-roam-db-build-cache~ from a file within
-that directory, at least once.
-
-** How do I migrate from Roam Research?
-
-Fabio has produced a command-line tool that converts markdown files exported
-from Roam Research into Org-roam compatible markdown. More instructions are
-provided [[https://github.com/fabioberger/roam-migration][in the repository]].
-
-** How do I create a note whose title already matches one of the candidates?
-
-This situation arises when, for example, one would like to create a note titled
-"bar" when "barricade" already exists.
-
-The solution is dependent on the mini-buffer completion framework in use. Here
-are the solutions:
-
-- Ivy :: call ~ivy-immediate-done~, typically bound to ~C-M-j~. Alternatively,
-  set ~ivy-use-selectable-prompt~ to ~t~, so that "bar" is now selectable.
-- Helm :: Org-roam should provide a selectable "[?] bar" candidate at the top of
-  the candidate list.
-
 * Keystroke Index
 :PROPERTIES:
 :APPENDIX:   t
@@ -1675,16 +1454,17 @@ are the solutions:
 :END:
 
 * Footnotes
-
 [fn:1] Depending on your completion framework, you may need to press TAB to
 see the list.
+[fn:2] Two easy ways to evaluate elisp: 1) Place the cursor after the closing
+paren and run =M-x eval-last-sexp RET= or 2) Press =C-c C-c= with your cursor in
+an Org file code block (like =#+BEGIN_SRC emacs-lisp=).
 [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)
 # eval: (require 'ox-texinfo+ nil t)
 # eval: (auto-fill-mode +1)
-# before-save-hook: org-make-toc
 # after-save-hook: (lambda nil (progn (require 'ox-texinfo nil t) (org-texinfo-export-to-info)))
 # indent-tabs-mode: nil
 # org-src-preserve-indentation: nil
diff --git a/org-roam.texi b/org-roam.texi
index 3dbfaee..6a6e2af 100644
--- a/org-roam.texi
+++ b/org-roam.texi
@@ -25,13 +25,13 @@ General Public License for more details.
 
 @dircategory Emacs
 @direntry
-* Org-roam: (org-roam). Rudimentary Roam Replica for Emacs.
+* Org-roam: (org-roam). Roam Research for Emacs.
 @end direntry
 
 @finalout
 @titlepage
 @title Org-roam User Manual
-@subtitle for version 1.2.3
+@subtitle for version 2.0.0
 @author Jethro Kuan
 @page
 @vskip 0pt plus 1filll
@@ -44,10 +44,10 @@ General Public License for more details.
 
 @noindent
 
-This manual is for Org-roam version 1.2.3.
+This manual is for Org-roam version 2.0.0.
 
 @quotation
-Copyright (C) 2020-2020 Jethro Kuan 
+Copyright (C) 2020-2021 Jethro Kuan 
 
 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
@@ -67,13 +67,24 @@ General Public License for more details.
 * A Brief Introduction to the Zettelkasten Method::
 * Installation::
 * Getting Started::
-* Files::
+* Viewing the links::
+* Node Properties::
+* The Org-roam Buffer::
+* Styling Org-roam::
+* Completion::
+* Encryption::
+* Org-roam protocol::
+* Diagnosing and Repair::
+* Building Extensions::
+* The Org-mode Ecosystem::
+* Frequently Asked Questions::
+* Developer's Guide to Org-roam::
 * The Templating System::
 * Concepts and Configuration::
 * Inserting Links::
 * Completions::
 * Navigating Around::
-* Encryption::
+* Encryption: Encryption (1). 
 * Graphing::
 * Minibuffer Completion::
 * Roam Protocol::
@@ -91,31 +102,33 @@ General Public License for more details.
 @detailmenu
 --- The Detailed Node Listing ---
 
-A Brief Introduction to the Zettelkasten Method
-
-* Fleeting notes::
-* Permanent notes::
-
 Installation
 
 * Installing from MELPA::
 * Installing from Apt::
-* Installing from the Git Repository::
+* Installing from Source::
 * Post-Installation Tasks::
 
-Files
+Getting Started
 
-* File Titles::
-* File Tags::
-* File Refs::
+* The Org-roam Node::
+* Links between Nodes::
+* Setting up Org-roam::
+* Creating and Linking Nodes::
 
-File Titles
+Node Properties
 
-* Customizing Title Extraction::
+* Standard Org properties::
+* Aliases::
+* Refs::
 
-File Tags
+Building Extensions
 
-* Customizing Tag Extraction::
+* Public Interface::
+
+Developer's Guide to Org-roam
+
+* Org-roam's Design Principles::
 
 The Templating System
 
@@ -125,10 +138,9 @@ The Templating System
 Concepts and Configuration
 
 * Directories and Files::
-* The Org-roam Buffer::
+* The Org-roam Buffer: The Org-roam Buffer (1). 
 * Org-roam Files::
 * Org-roam Faces::
-* The Database::
 
 Completions
 
@@ -198,28 +210,24 @@ FAQ
 @node Introduction
 @chapter Introduction
 
-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 tool for networked 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}.} key features within @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 keeps closely to Org syntax, and will work for anyone already using
-Org-mode for their personal wiki.
+Org-roam allows for effortless non-hierarchical note-taking: with Org-roam,
+notes flow naturally, making note-taking fun and easy. Org-roam augments the
+Org-mode syntax, and will work for anyone already using Org-mode for their
+personal wiki.
 
-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 leverages 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, and is able to
+piggyback off Org's excellent @LaTeX{} and source-block evaluation capabilities.
 
-Org-roam aims to implement the core features of Roam, leveraging the
-mature ecosystem around Org-mode where possible. Eventually, we hope
-to further introduce features enabled by the Emacs ecosystem.
-
-Org-roam provides several benefits over other tooling:
+Org-roam provides these benefits over other tooling:
 
 @itemize
 @item
-@strong{Privacy and Security:} Keep your personal wiki entirely offline and in your
-control. Encrypt your notes with GPG@.
+@strong{Privacy and Security:} Your personal wiki belongs only to you, entirely
+offline and in your control. Encrypt your notes with GPG@.
 
 @item
 @strong{Longevity of Plain Text:} Unlike web solutions like Roam Research, the notes
@@ -235,13 +243,13 @@ you feel unhappy with any part of Org-roam, you may choose to extend Org-roam,
 or open a pull request.
 
 @item
-@strong{Leverage the Org-mode ecosystem:} Over the years, Emacs and Org-mode has
+@strong{Leverage the Org-mode ecosystem:} Over the decades, 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
-@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
+@strong{Built on Emacs:} Emacs is also a fantastic interface for editing text, and
+Org-roam inherits many of the powerful text-navigation and editing packages
 available to Emacs.
 @end itemize
 
@@ -249,18 +257,18 @@ available to Emacs.
 @chapter Target Audience
 
 Org-roam is a tool that will appear unfriendly to anyone unfamiliar with Emacs
-and Org-mode, but is also extremely powerful to those willing to put effort in
-mastering the intricacies of the tools. Org-roam stands on the shoulders on
-giants. Emacs was first created in 1976, and remains a top tier tool for editing
+and Org-mode, but it is also extremely powerful to those willing to put effort
+inn mastering the intricacies. Org-roam stands on the shoulders of giants. Emacs
+was first created in 1976, and remains the tool of choice for many for editing
 text and designing textual interfaces. The malleability of Emacs allowed the
 creation of Org-mode, an all-purpose plain-text system for maintaining TODO
 lists, planning projects, and authoring documents. Both of these tools are
 incredibly vast and require significant time investment to master.
 
-Org-roam assumes basic familiarity with these tools. It is not difficult to get
-up and running with basic text-editing functionality, but one will only fully
-appreciate the power of building Roam functionality into Emacs and Org-mode when
-the usage of these tools become more advanced.
+Org-roam assumes only basic familiarity with these tools. It is not difficult to
+get up and running with basic text-editing functionality, but one will only
+fully appreciate the power of building Roam functionality into Emacs and
+Org-mode when the usage of these tools become more advanced.
 
 One key advantage to Org-roam is that building on top of Emacs gives it
 malleability. This is especially important for note-taking workflows. It is our
@@ -313,13 +321,7 @@ 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::
-* Permanent notes::
-@end menu
-
-@node Fleeting notes
-@section Fleeting notes
+@strong{Fleeting notes}
 
 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
@@ -328,8 +330,7 @@ need to be processed later on, or trashed. This is typically accomplished using
 functionality (see @ref{Daily-notes}). This provides a central inbox for collecting
 thoughts, to be processed later into permanent notes.
 
-@node Permanent notes
-@section Permanent notes
+@strong{Permanent notes}
 
 Permanent notes are further split into two categories: @strong{literature notes} and
 @strong{concept notes}. Literature notes can be brief annotations on a particular
@@ -338,6 +339,9 @@ Concept notes require much more care in authoring: they need to be
 self-explanatory and detailed. Org-roam's templating system supports the
 addition of different templates to facilitate the creation of these notes.
 
+For further reading on the Zettelkasten method, ``How to Take Smart Notes'' by
+Sonke Ahrens is a decent guide.
+
 @node Installation
 @chapter Installation
 
@@ -347,7 +351,7 @@ development repository.
 @menu
 * Installing from MELPA::
 * Installing from Apt::
-* Installing from the Git Repository::
+* Installing from Source::
 * Post-Installation Tasks::
 @end menu
 
@@ -416,8 +420,8 @@ apt-get install elpa-org-roam
 
 Org-roam will then be autoloaded into Emacs.
 
-@node Installing from the Git Repository
-@section Installing from the Git Repository
+@node Installing from Source
+@section Installing from Source
 
 You may install Org-roam directly from the repository on @uref{https://github.com/org-roam/org-roam, GitHub} if you like.
 This will give you access to the latest version hours or days before it appears
@@ -520,18 +524,19 @@ install-info /path/to/my/info/files/org-roam.info /path/to/my/info/files/dir
 @node Post-Installation Tasks
 @section Post-Installation Tasks
 
-Org-roam uses @code{emacsql-sqlite3}, which requires @code{sqlite3} to be located on
-@code{exec-path}. Please ensure that @code{sqlite3} is installed appropriately on your
-operating system. You can verify that this is the case by executing:
+Org-roam requires @code{sqlite3} to be locatable by Emacs (i.e. on @code{exec-path}).
+Please ensure that @code{sqlite3} is installed appropriately on your operating
+system. You can verify that this is the case by executing @footnote{Two easy ways to evaluate elisp: 1) Place the cursor after the closing
+paren and run @samp{M-x eval-last-sexp RET} or 2) Press @samp{C-c C-c} with your cursor in
+an Org file code block (like @samp{#+BEGIN_SRC emacs-lisp}).}:
 
 @lisp
 (executable-find "sqlite3")
 @end lisp
 
 If you have @code{sqlite3} installed, and @code{executable-find} still reports @code{nil}, then
-it is likely that the path to the executable is not a member of the Emacs
-variable @code{exec-path}. You may rectify this by manually adding the path within
-your Emacs configuration:
+the path to the executable is not a member of the Emacs variable @code{exec-path}.
+Rectify this by manually adding the path within your Emacs configuration:
 
 @lisp
 (add-to-list 'exec-path "path/to/sqlite3")
@@ -540,283 +545,145 @@ your Emacs configuration:
 @node Getting Started
 @chapter Getting Started
 
-This short tutorial describes the essential commands used in Org-roam, to help
-you get started.
+@menu
+* The Org-roam Node::
+* Links between Nodes::
+* Setting up Org-roam::
+* Creating and Linking Nodes::
+@end menu
 
-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 @uref{https://zettelkasten.de/, Zettelkasten Method}, and many of @uref{https://roamresearch.com, Roam Research's}
-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 @ref{Note-taking Workflows}.
+@node The Org-roam Node
+@section The Org-roam Node
+
+We first begin with some terminology we'll use throughout the manual. We term
+the basic denomination in Org-roam a node. We define a node as follows:
+
+@quotation
+A node is any headline or top level file with an ID@.
+
+@end quotation
+
+For example, with this example file content:
+
+@example
+:PROPERTIES:
+:ID:       foo
+:END:
+#+title: Foo
+
+* Bar
+:PROPERTIES:
+:ID:       bar
+:END:
+@end example
+
+We create two nodes:
+
+@itemize
+@item
+A file node ``Foo'' with id @code{foo}.
+
+@item
+A headline node ``Bar'' with id @code{bar}.
+@end itemize
+
+Headlines without IDs will not be considered Org-roam nodes. Org IDs can be
+added to files or headlines via the interactive command @code{M-x org-id-get-create}.
+
+@node Links between Nodes
+@section Links between Nodes
+
+We link between nodes using Org's standard ID link (e.g. @code{id:foo}). While only
+ID links will be considered during the computation of links between nodes,
+Org-roam caches all other links in the documents for external use.
+
+@node Setting up Org-roam
+@section Setting up Org-roam
+
+Org-roam's capabilities stem from its aggressive caching: it crawls all files
+within @code{org-roam-directory}, keeping a cache of all its links and nodes, while
+making sure that the cache is consistent.
 
 To first start using Org-roam, one needs to pick a location to store the
 Org-roam files. The directory that will contain your notes is specified by the
-variable @code{org-roam-directory}. 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}:
+variable @code{org-roam-directory}. Org-roam searches recursively within
+@code{org-roam-directory} for notes. This variable needs to be set before any calls
+to Org-roam functions. For this tutorial, create an empty directory, and set
+@code{org-roam-directory}:
 
 @lisp
 (make-directory "~/org-roam")
 (setq org-roam-directory "~/org-roam")
 @end lisp
 
-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 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, building a cache that is kept consistent as your
-slip-box grows. We recommend starting @code{org-roam-mode} on startup:
+Next, we need to setup Org-roam to maintain cache consistency. This is achieved
+by running @code{M-x org-roam-setup}. To ensure that Org-roam is available on
+startup, one can place this in their Emacs configuration:
 
 @lisp
-(add-hook 'after-init-hook 'org-roam-mode)
+(require 'org-roam)
+(org-roam-setup)
 @end lisp
 
 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
+@node Creating and Linking Nodes
+@section @strong{TODO} Creating and Linking Nodes
+
+Org-roam makes it easy to create notes and link them together. There are 2 main
+functions for creating nodes:
+
+@itemize
+@item
+@code{org-roam-node-insert}: creates a node if it does not exist, and inserts a
+link to the node at point.
+
+@item
+@code{org-roam-node-find}: creates a node if it does not exist, and visits the
+node.
+@end itemize
+
+Let's first try @code{org-roam-node-find}. Calling @code{M-x org-roam-node-find} will
+show a list of titles for nodes that reside in @code{org-roam-directory}. It should
+show nothing right now, since there are no notes in the directory. Enter the
+title of the note you wish to create, and press @code{RET}. This begins 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.
 
-By default, Org-roam updates the cache asynchronously in the background to
-avoid getting in the way of writing. Org-roam queues updates to the files,
-waits for you to be idle for 2 seconds, and then automatically triggers
-updating the cache. After the cache has been updated, running @code{M-x
-org-roam-find-file} again should show the note you have created, and selecting
-that entry will bring you to that note @footnote{Depending on your completion framework, you may need to press TAB to
-see the list.}. One can customize the waiting
-time by setting @code{org-roam-db-update-idle-seconds}; or change the cache update
-to be triggered immediately after buffer save by setting
-@code{org-roam-db-update-method} to @code{'immediate}.
+Now that we have a node, we can try inserting a link to the node using @code{M-x
+org-roam-node-insert}. This brings up the list of nodes, which should contain
+the node you just created. Selecting the node will insert an @code{id:} link to the
+node. If you instead entered a title that does not exist, you will once again be
+brought through the node creation process. To enable link auto-completion,
+see @ref{Completion}.
 
-For experienced @code{org-capture} users, the behavior of @code{M-x org-roam-find-file} 
-may seem unfamiliar: after finishing a capture with @code{C-c C-c}, you are returned  
-not to the original buffer from which you called @code{M-x org-roam-find-file}, but 
-to a buffer pointing to the note you just created. For the usual @code{org-capture} 
-behavior you can call @code{M-x org-roam-capture} instead of @code{M-x org-roam-find-file}. 
+@node Viewing the links
+@chapter @strong{TODO} Viewing the links
 
-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 relationships with other notes
+(backlinks, reference links, unlinked references etc.). To pop up this info
+buffer, call @code{M-x org-roam-buffer}.
 
-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}.
-
-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}).
-
-@node Files
-@chapter Files
-
-In Org-roam, notes typically consist of multiple files, where each file is a
-zettel.
-
-While the bulk of Org-roam's functionality is built on top of vanilla Org-mode,
-Org-roam adds several Org-roam-specific keywords to support additional
-functionality.
-
-This section explains the important components of a file, and the extensions to
-Org-mode.
+@node Node Properties
+@chapter @strong{TODO} Node Properties
 
 @menu
-* File Titles::
-* File Tags::
-* File Refs::
+* Standard Org properties::
+* Aliases::
+* Refs::
 @end menu
 
-@node File Titles
-@section File Titles
+@node Standard Org properties
+@section @strong{TODO} Standard Org properties
 
-To easily find a note, a title needs to be prescribed to a note.
+@node Aliases
+@section @strong{TODO} Aliases
 
-A note can have many titles: this allows a note to be referred to by different
-names, which is especially useful for topics or concepts with acronyms. For
-example, for a note like ``World War 2'', it may be desirable to also refer to it
-using the acronym ``WWII''.
-
-Org-roam calls @code{org-roam--extract-titles} to extract titles. It uses the
-variable @code{org-roam-title-sources}, to control how the titles are extracted. The
-title extraction methods supported are:
-
-@itemize
-@item
-@code{'title}: This extracts the title using the file @code{#+title} property
-
-@item
-@code{'headline}: This extracts the title from the first headline in the Org file
-
-@item
-@code{'alias}: This extracts a list of titles using the @code{#+roam_alias} property.
-The aliases are space-delimited, and can be multi-worded using quotes.
-@end itemize
-
-Take for example the following org file:
-
-@example
-#+title: World War 2
-#+roam_alias: "WWII" "World War II"
-
-* Headline
-@end example
-
-@multitable {aaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaa}
-@headitem Method
-@tab Titles
-@item @code{'title}
-@tab '(``World War 2'')
-@item @code{'headline}
-@tab '(``Headline'')
-@item @code{'alias}
-@tab '(``WWII'' ``World War II'')
-@end multitable
-
-If no title is provided, Org-roam defaults to using the file-path.
-
-@menu
-* Customizing Title Extraction::
-@end menu
-
-@node Customizing Title Extraction
-@subsection Customizing Title Extraction
-
-To control how Org-roam extracts titles, customize @code{org-roam-title-sources}. If
-all methods of title extraction return no results, the file-name is used as the
-note's title.
-
-@defopt org-roam-title-sources
-
-The list of sources from which to retrieve a note title.
-Each element in the list is either:
-@end defopt
-
-@itemize
-@item
-a symbol -- this symbol corresponds to a title retrieval function, which
-returns the list of titles for the current buffer
-@itemize
-@item
-a list of symbols -- symbols in the list are treated as with (1). The
-return value of this list is the first symbol in the list returning a
-non-nil value.
-@end itemize
-
-The return results of the root list are concatenated.
-
-For example the setting: '((title headline) alias) means the following:
-
-@itemize
-@item
-Return the 'title + 'alias, if the title of current buffer is non-empty;
-
-@item
-Or return 'headline + 'alias otherwise.
-@end itemize
-
-The currently supported symbols are:
-
-@code{'title}
-The @code{#+title} property of org file.
-
-@code{'alias}
-The @code{#+roam_alias} property of the org file, using
-space-delimited strings.
-
-@code{'headline}
-The first headline in the org file.
-@end itemize
-
-Adding your own title extraction method requires two steps. First, define a
-method @code{(defun org-roam--extract-titles-foo () ...)}, where @code{foo} a
-self-prescribed name for the title extraction method. This method takes no
-arguments, and returns a list of strings (titles). Finally, push the symbol
-@code{foo} into @code{org-roam-title-sources}. You may need to rebuild the cache from
-scratch to re-process all files to pick up the new titles.
-
-@node File Tags
-@section File Tags
-
-Tags are used as meta-data for files: they facilitate interactions with notes
-where titles are insufficient. For example, tags allow for categorization of
-notes: differentiating between bibliographical and structure notes during
-interactive commands.
-
-By default, tags are extracted from the @code{#+roam_tags} property. To add
-additional extraction methods, see @ref{Customizing Tag Extraction}.
-
-@menu
-* Customizing Tag Extraction::
-@end menu
-
-@node Customizing Tag Extraction
-@subsection Customizing Tag Extraction
-
-Org-roam calls @code{org-roam--extract-tags} to extract tags from files. The variable
-@code{org-roam-tag-sources}, to control how tags are extracted.
-
-@defopt org-roam-tag-sources
-@end defopt
-
-Sources to obtain tags from.
-
-It should be a list of symbols representing any of the following extraction
-methods:
-
-@code{'prop}
-  Extract tags from the @code{#+roam_tags} property.
-  Tags are space delimited.
-  Tags may contain spaces if they are double-quoted.
-  e.g. @code{#+roam_tags: TAG "tag with spaces"}
-
-@code{'vanilla}
-  Extract vanilla org-mode tags, including @code{#+FILETAGS} and
-  inherited tags.
-
-@code{'all-directories}
-  Extract sub-directories relative to @code{org-roam-directory}.
-  That is, if a file is located at relative path foo/bar/file.org,
-  the file will have tags ``foo'' and ``bar''.
-
-@code{'last-directory}
-  Extract the last directory relative to `org-roam-directory'.
-  That is, if a file is located at relative path foo/bar/file.org,
-  the file will have tag \``bar\''.
-
-@code{'first-directory}
-  Extract the first directory relative to @code{org-roam-directory}.
-  That is, if a file is located at relative path foo/bar/file.org,
-  the file will have tag ``foo''
-
-By default, only the @code{'prop} extraction method is enabled. To enable the other
-extraction methods, you may modify @code{org-roam-tag-sources}, for example:
-
-@lisp
-(setq org-roam-tag-sources '(prop last-directory))
-@end lisp
-
-Adding your own tag extraction method requires two steps. First, define a method
-@code{(defun org-roam--extract-tags-foo (file) ...)}, where @code{foo} a self-prescribed
-name for the tag extraction method. This method takes the file path as an
-argument, and returns a list of strings (titles). Finally, push the symbol @code{foo}
-into @code{org-roam-tag-sources}. You may need to rebuild the cache from scratch to
-re-process all files to pick up the new tags.
-
-@node File Refs
-@section File Refs
+@node Refs
+@section @strong{TODO} Refs
 
 Refs are unique identifiers for files. For example, a note for a website may
 contain a ref:
@@ -849,6 +716,159 @@ You may assign multiple refs to a single file, for example when you want
 multiple papers in a series to share the same note, or an article has a citation
 key and a URL at the same time.
 
+@node The Org-roam Buffer
+@chapter @strong{TODO} The Org-roam Buffer
+
+@node Styling Org-roam
+@chapter @strong{TODO} Styling Org-roam
+
+@node Completion
+@chapter @strong{TODO} Completion
+
+@node Encryption
+@chapter @strong{TODO} Encryption
+
+@node Org-roam protocol
+@chapter @strong{TODO} Org-roam protocol
+
+@node Diagnosing and Repair
+@chapter @strong{TODO} Diagnosing and Repair
+
+@node Building Extensions
+@chapter @strong{TODO} Building Extensions
+
+@menu
+* Public Interface::
+@end menu
+
+@node Public Interface
+@section @strong{TODO} Public Interface
+
+Database (for developers)
+@itemize
+@item
+querying: (org-roam-db-query)
+
+@item
+updating full database: (org-roam-db-sync)
+
+@item
+update current file: (org-roam-db-update-file)
+
+@item
+remove file from database: (org-roam-db-clear-file)
+@end itemize
+
+Nodes:
+@itemize
+@item
+List all nodes
+
+@item
+Read a node in from completion
+
+@item
+Get node at point
+@end itemize
+
+Links:
+@itemize
+@item
+Get backlinks for node
+@end itemize
+
+Tags:
+@itemize
+@item
+Add tag to node
+
+@item
+delete tag for node
+
+@item
+Get tags for node
+@end itemize
+
+Aliases:
+@itemize
+@item
+Add alias to node
+
+@item
+Delete alias for node
+
+@item
+Get aliases for node
+@end itemize
+
+Ref:
+@itemize
+@item
+Add ref to node
+@end itemize
+
+Capture:
+
+Navigation:
+@itemize
+@item
+Find or create a node
+@end itemize
+
+@node The Org-mode Ecosystem
+@chapter @strong{TODO} The Org-mode Ecosystem
+
+@node Frequently Asked Questions
+@chapter @strong{TODO} Frequently Asked Questions
+
+@node Developer's Guide to Org-roam
+@chapter @strong{TODO} Developer's Guide to Org-roam
+
+@menu
+* Org-roam's Design Principles::
+@end menu
+
+@node Org-roam's Design Principles
+@section Org-roam's Design Principles
+
+Org-roam is primarily motivated by the need for a dual representation. We
+(humans) love operating in a plain-text environment. The syntax rules of
+Org-mode are simple and fit snugly within our brain. This also allows us to use
+the tools and packages we love to explore and edit our notes. Org-mode is simply
+the most powerful plain-text format available, with support for images, @LaTeX{},
+TODO planning and much more.
+
+But this plain-text format is simply ill-suited for exploration of these notes:
+plain-text is simply not amenable for answering large-scale, complex queries
+(e.g. how many tasks do I have that are due by next week?). Interfaces such as
+Org-agenda slow to a crawl when the number of files becomes unwieldy, which
+can quickly become the case.
+
+At its core, Org-roam provides a database abstraction layer, providing a dual
+representation of what's already available in plain-text. This allows us
+(humans) to continue working with plain-text, while programs can utilize the
+database layer to perform complex queries. These capabilities include, but are
+not limited to:
+
+@itemize
+@item
+link graph traversal and visualization
+
+@item
+Instantaneous SQL-like queries on headlines
+@itemize
+@item
+What are my TODOs, scheduled for X, or due by Y@?
+@end itemize
+@end itemize
+
+All of these functionality is powered by this database abstraction layer. Hence,
+at its core Org-roam's primary goal is to provide a resilient dual
+representation that is cheap to maintain, easy to understand, and is as
+up-to-date as it possibly can. Org-roam also then exposes an API to this
+database abstraction layer for users who would like to perform programmatic
+queries on their Org files.
+
 @node The Templating System
 @chapter The Templating System
 
@@ -918,7 +938,7 @@ The template is given a description of @code{"default"}.
 @code{(function org-roam--capture-get-point)} should not be changed.
 
 @item
-@code{"%?"} is the template inserted on each call to @code{org-roam-capture--capture}.
+@code{"%?"} is the template inserted on each call to @code{org-roam-capture-}.
 This template means don't insert any content, but place the cursor here.
 
 @item
@@ -990,10 +1010,9 @@ org-roam}.
 
 @menu
 * Directories and Files::
-* The Org-roam Buffer::
+* The Org-roam Buffer: The Org-roam Buffer (1). 
 * Org-roam Files::
 * Org-roam Faces::
-* The Database::
 @end menu
 
 @node Directories and Files
@@ -1021,7 +1040,7 @@ with multiple Org-roam instances.
 Files matching this regular expression are excluded from the Org-roam.
 @end defvar
 
-@node The Org-roam Buffer
+@node The Org-roam Buffer (1)
 @section The Org-roam Buffer
 
 The Org-roam buffer displays backlinks for the currently active Org-roam note.
@@ -1086,27 +1105,6 @@ The @code{org-roam-link-current} face corresponds to links to the same file it i
 The @code{org-roam-link-invalid} face is applied to links that are broken. These are
 links to files or IDs that cannot be found.
 
-@node The Database
-@section @strong{TODO} The Database
-
-Org-roam is backed by a Sqlite database.
-
-@defopt org-roam-db-update-method
-
-Method to update the Org-roam database.
-
-@code{'immediate}: Update the database immediately upon file changes.
-
-@code{'idle-timer}: Updates the database if dirty, if Emacs idles for
-@code{org-roam-db-update-idle-seconds}.
-@end defopt
-
-@defopt org-roam-db-update-idle-seconds
-
-Number of idle seconds before triggering an Org-roam database update. This is
-only valid if @code{org-roam-db-update-method} is @code{'idle-timer}.
-@end defopt
-
 @node Inserting Links
 @chapter Inserting Links
 
@@ -1194,7 +1192,7 @@ represents the cursor:
 @code{[[|]]}: completes for a file title
 
 @item
-@code{[[roam:]]}: completes for a file title
+@code{[[roam:|]]}: completes for a file title
 
 @item
 @code{[[*|]]}: completes for a headline within this file
@@ -1206,6 +1204,9 @@ represents the cursor:
 @code{[[roam:foo*|]]} completes a headline within the file with title ``foo''
 @end itemize
 
+If you don't see the literal display of your links like the above examples,
+call @code{M-x org-toggle-link-display}
+
 Completions account for the current input. For example, for @code{[[f|]]}, the
 completions (by default) only show for files with titles that start with ``f''.
 
@@ -1279,7 +1280,7 @@ title is @code{"Index"}.
 Opens the Index file in the current @code{org-roam-directory}.
 @end defun
 
-@node Encryption
+@node Encryption (1)
 @chapter Encryption
 
 One may wish to keep private, encrypted files. Org-roam supports encryption (via
@@ -1617,7 +1618,7 @@ in the generated graph.
 @node The roam-ref protocol
 @section The roam-ref protocol
 
-This protocol finds or creates a new note with a given @code{roam_key} (see @ref{Files}):
+This protocol finds or creates a new note with a given @code{roam_key}:
 
 @image{images/roam-ref,,,,gif}
 
@@ -1720,7 +1721,7 @@ template @code{j} will put its notes under the heading ‘Journal’.
 
 Create an entry in the daily note for today.
 
-When @code{goto} is non-nil, go the note without creating an entry.
+When @code{goto} is non-nil, go to the note without creating an entry.
 @end defun
 
 @defun @code{org-roam-dailies-find-today}
@@ -1986,22 +1987,6 @@ using @uref{https://github.com/raxod502/el-patch, el-patch}:
 
 (eval-when-compile
   (require 'el-patch))
-
-(use-package deft
-  ;; same as above...
-  :config/el-patch
-  (defun deft-parse-title (file contents)
-    "Parse the given FILE and CONTENTS and determine the title.
-If `deft-use-filename-as-title' is nil, the title is taken to
-be the first non-empty line of the FILE.  Else the base name of the FILE is
-used as title."
-    (el-patch-swap (if deft-use-filename-as-title
-                       (deft-base-filename file)
-                     (let ((begin (string-match "^.+$" contents)))
-                       (if begin
-                           (funcall deft-parse-title-function
-                                    (substring contents begin (match-end 0))))))
-                   (org-roam-db--get-title file))))
 @end lisp
 
 The Deft interface can slow down quickly when the number of files get huge.
@@ -2105,6 +2090,9 @@ file with the right @samp{#+roam_key}.
 @uref{https://www.leonrische.me/fc/index.html, Org-fc} is a spaced repetition system that scales well with a large number of
 files. Other alternatives include @uref{https://orgmode.org/worg/org-contrib/org-drill.html, org-drill}, and @uref{https://github.com/abo-abo/pamparam, pamparam}.
 
+To use Anki for spaced repetition, @uref{https://github.com/louietan/anki-editor, anki-editor} allows you to write your cards in
+Org-mode, and sync your cards to Anki via @uref{https://github.com/FooSoft/anki-connect#installation, anki-connect}.
+
 @node FAQ
 @chapter FAQ