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.
— The Detailed Node Listing — -A Brief Introduction to the Zettelkasten Method - -
- Installation
-Files +Getting Started -
-File Titles +Node Properties -
-File Tags +Building Extensions -
+ +Developer’s Guide to Org-roam + +
@@ -185,14 +211,12 @@ Concepts and Configuration
Completions @@ -306,27 +330,23 @@ Next: Target Audience, P1 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.
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: Permanent notes, 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: Fleeting notes, 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.
-Next: Installing from the Git Repository, Previous: Installing from MELPA, Up: Installation [Index]
+Next: Installing from Source, Previous: Installing from MELPA, Up: Installation [Index]4.2 Installing from Apt
@@ -552,11 +558,11 @@ using Apt:Org-roam will then be autoloaded into Emacs.
-
+
-
+
+
+
+
+
+
-
+
-
-
-Next: Post-Installation Tasks, Previous: Installing from Apt, 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: Installing from the Git Repository, Up: Installation [Index]
+Previous: Installing from Source, 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: Files, Previous: Installation, Up: Top [Index]
+Next: Viewing the links, Previous: Installation, 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: Links between Nodes, 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: Setting up Org-roam, Previous: The Org-roam Node, 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: Creating and Linking Nodes, Previous: Links between Nodes, 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: Setting up Org-roam, 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: The Templating System, Previous: Getting Started, Up: Top [Index]
+Next: Node Properties, Previous: Getting Started, 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: The Org-roam Buffer, Previous: Viewing the links, Up: Top [Index]
+7 TODO Node Properties
+| • File Titles | + | |
| • Standard Org properties | ||
| • File Tags | + | |
| • Aliases | ||
| • File Refs | + | |
| • Refs |
-
+
-
-
-
-
-
+
-
-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#+titleproperty - - -
'headline: This extracts the title from the first headline in the Org file - - -
'alias: This extracts a list of titles using the#+roam_aliasproperty. -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 -
| Method | Titles |
|---|---|
'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: Refs, Previous: Standard Org properties, 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#+titleproperty of org file. -
-'alias-The#+roam_aliasproperty 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: File Refs, Previous: File Titles, 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
-
+
-
- -
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-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.
-
- -
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: Styling Org-roam, Previous: Node Properties, Up: Top [Index]
+8 TODO The Org-roam Buffer
+ ++
+
++Next: Completion, Previous: The Org-roam Buffer, Up: Top [Index]
+9 TODO Styling Org-roam
+ ++
+
++Next: Encryption, Previous: Styling Org-roam, Up: Top [Index]
+10 TODO Completion
+ ++
+
++Next: Org-roam protocol, Previous: Completion, Up: Top [Index]
+11 TODO Encryption
+ ++
+
++Next: Diagnosing and Repair, Previous: Encryption, Up: Top [Index]
+12 TODO Org-roam protocol
+ ++
+
++Next: Building Extensions, Previous: Org-roam protocol, Up: Top [Index]
+13 TODO Diagnosing and Repair
+ ++
+
++Next: The Org-mode Ecosystem, Previous: Diagnosing and Repair, 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: Frequently Asked Questions, Previous: Building Extensions, Up: Top [Index]
+15 TODO The Org-mode Ecosystem
+ ++
+
++Next: Developer's Guide to Org-roam, Previous: The Org-mode Ecosystem, Up: Top [Index]
+16 TODO Frequently Asked Questions
+ ++
+
++Next: The Templating System, Previous: Frequently Asked Questions, Up: Top [Index]
+17 TODO Developer’s Guide to Org-roam
+ +| • Org-roam's Design Principles | + |
+
+
+
+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: Concepts and Configuration, Previous: Files, Up: Top [Index]
+Next: Concepts and Configuration, Previous: Developer's Guide to Org-roam, 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: Org-roam Template Expansion, 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: Template Walkthrough, 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: Inserting Links, Previous: The Templating System, 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: The Org-roam Buffer, Up: Concepts and Configuration [Index]
+Next: The Org-roam Buffer (1), 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: Org-roam Files, Previous: Directories and Files, 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: Org-roam Files,-Next: Org-roam Faces, Previous: The Org-roam Buffer, Up: Concepts and Configuration [Index]
+Next: Org-roam Faces, Previous: The Org-roam Buffer (1), 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: The Database, Previous: Org-roam Files, Up: Concepts and Configuration [Index] 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
-Previous: Org-roam Faces, Up: Concepts and Configuration [Index] Org-roam is backed by a Sqlite database.
- Method to update the Org-roam database.
- Number of idle seconds before triggering an Org-roam database update. This is
-only valid if
Next: Completions, Previous: Concepts and Configuration, Up: Top [Index] The preferred mode of linking is via
Next: Navigating Around, Previous: Inserting Links, Up: Top [Index]
-8.4 Org-roam Faces
+19.4 Org-roam Faces
org-roam-link-invalid face is applied to links that are broken. These are
links to files or IDs that cannot be found.
-
-
-8.5 TODO The 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.
-
-
-
org-roam-db-update-method is 'idle-timer.
-
-9 Inserting Links
+20 Inserting Links
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.
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: Tag Completion, 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”.
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: Link Completion, Up: Completions [Index]
10.2 Tag Completion
+21.2 Tag Completion
Org-roam facilitates the insertion of existing tags via completion-at-point.
-Next: Encryption, Previous: Completions, Up: Top [Index]
+Next: Encryption (1), Previous: Completions, Up: Top [Index]11 Navigating Around
+22 Navigating Around
| • Index File |
@@ -1483,7 +1528,7 @@ Next: Encryption, Previous: <
Up: Navigating Around [Index] -11.1 Index File+22.1 Index FileAs your collection grows, you might want to create an index where you keep links
to your main files.
@@ -1510,11 +1555,11 @@ title is -
+
-Next: Graphing, Previous: Navigating Around, Up: Top [Index] 12 Encryption+23 EncryptionOne may wish to keep private, encrypted files. Org-roam supports encryption (via
GPG), which can be enabled for all new files by setting -Next: Minibuffer Completion, Previous: Encryption, Up: Top [Index] +Next: Minibuffer Completion, Previous: Encryption (1), Up: Top [Index]13 Graphing+24 GraphingOrg-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: Excluding Nodes and Edges, Up: Graphing [Index] 13.1 Graph Options+24.1 Graph OptionsGraphviz 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: Previous: Graph Options, Up: Graphing [Index] -13.2 Excluding Nodes and Edges+24.2 Excluding Nodes and EdgesOne may want to exclude certain files to declutter the graph. @@ -1679,7 +1724,7 @@ are excluded.Next: Roam Protocol, Previous: Graphing, Up: Top [Index] -14 Minibuffer Completion+25 Minibuffer CompletionOrg-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: Daily-notes, Previous: Minibuffer Completion, Up: Top [Index] -15 Roam Protocol+26 Roam ProtocolOrg-roam extends Next: The roam-file protocol, Up: Roam Protocol [Index] -15.1 Installation+26.1 InstallationTo enable Org-roam’s protocol extensions, you have to add the following to your init file: @@ -1871,7 +1916,7 @@ file. Next: The roam-ref protocol, Previous: Installation (1), Up: Roam Protocol [Index] -15.2 The roam-file protocol+26.2 The roam-file protocolThis is a simple protocol that opens the path specified by the Previous: The roam-file protocol, 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 This protocol finds or creates a new note with a given 
@@ -1916,7 +1961,7 @@ should contain a #+roam_key: ${ref} in it.
Next: Diagnosing and Repairing Files, Previous: Roam Protocol, Up: Top [Index] -16 Daily-notes+27 Daily-notesOrg-roam provides journaling capabilities akin to
Org-journal with
Next: Capturing and finding daily-notes, Up: Daily-notes [Index] For
Next: Navigation, Previous: Configuration, Up: Daily-notes [Index] Create an entry in the daily note for today.
When When
Previous: Capturing and finding daily-notes, Up: Daily-notes [Index] You can navigate between daily-notes:
17 Diagnosing and Repairing Files+28 Diagnosing and Repairing FilesOrg-roam provides a utility for diagnosing and repairing problematic files via
Next: Performance Optimization, Previous: Diagnosing and Repairing Files, Up: Top [Index] -18 Finding Unlinked References+29 Finding Unlinked ReferencesUnlinked 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: Appendix, Previous: Finding Unlinked References, Up: Top [Index] -19 Performance Optimization+30 Performance Optimization
|