mirror of
https://github.com/org-roam/org-roam
synced 2025-08-01 12:17:21 -05:00
update docs
This commit is contained in:
Jethro Kuan
@ -128,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
|
||||
@ -137,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
|
||||
@ -146,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
|
||||
@ -208,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
|
||||
@ -290,25 +293,23 @@ install-info /path/to/my/info/files/org-roam.info /path/to/my/info/files/dir
|
||||
|
||||
** Post-Installation Tasks
|
||||
|
||||
Org-roam requires ~sqlite3~ to be located on ~exec-path~. Please ensure that
|
||||
~sqlite3~ is installed appropriately on your operating system. You can verify [fn:2]
|
||||
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
|
||||
|
||||
We first begin with some terminology we'll use throughout the manual. We term
|
||||
@ -348,9 +349,9 @@ Org-roam caches all other links in the documents for external use.
|
||||
|
||||
** Setting up Org-roam
|
||||
|
||||
Org-roam's primary capability comes from its aggressive caching: it crawls all
|
||||
files within ~org-roam-directory~, keeping a cache of all its links and nodes,
|
||||
and making sure that the cache is consistent.
|
||||
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
|
||||
@ -377,38 +378,42 @@ 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.
|
||||
|
||||
** TODO Creating New Notes
|
||||
** TODO Creating and Linking Nodes
|
||||
|
||||
Let us now create our first node. Call ~M-x org-roam-find-file~. This shows 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. Entering the title
|
||||
of the note you wish to create, and pressing ~RET~ should begin the note
|
||||
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][The Templating System]]). Using the default template, pressing
|
||||
~C-c C-c~ finishes the note capture.
|
||||
|
||||
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~.
|
||||
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 [[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.
|
||||
# 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 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~.
|
||||
* TODO Viewing the links
|
||||
|
||||
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 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~.
|
||||
|
||||
* TODO Node Properties
|
||||
** TODO Standard Org properties
|
||||
@ -446,6 +451,9 @@ key and a URL at the same time.
|
||||
* TODO The Org-roam Buffer
|
||||
* TODO Styling Org-roam
|
||||
* TODO Completion
|
||||
:PROPERTIES:
|
||||
:ID: 70083bfd-d1e3-42b9-bf83-5b05708791c0
|
||||
:END:
|
||||
* TODO Encryption
|
||||
* TODO Org-roam protocol
|
||||
* TODO Diagnosing and Repair
|
||||
|
||||
@ -67,6 +67,7 @@ General Public License for more details.
|
||||
* A Brief Introduction to the Zettelkasten Method::
|
||||
* Installation::
|
||||
* Getting Started::
|
||||
* Viewing the links::
|
||||
* Node Properties::
|
||||
* The Org-roam Buffer::
|
||||
* Styling Org-roam::
|
||||
@ -83,7 +84,7 @@ General Public License for more details.
|
||||
* Inserting Links::
|
||||
* Completions::
|
||||
* Navigating Around::
|
||||
* Encryption: Encryption (1).
|
||||
* Encryption: Encryption (1).
|
||||
* Graphing::
|
||||
* Minibuffer Completion::
|
||||
* Roam Protocol::
|
||||
@ -101,16 +102,11 @@ 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::
|
||||
|
||||
Getting Started
|
||||
@ -118,7 +114,7 @@ Getting Started
|
||||
* The Org-roam Node::
|
||||
* Links between Nodes::
|
||||
* Setting up Org-roam::
|
||||
* Creating New Notes::
|
||||
* Creating and Linking Nodes::
|
||||
|
||||
Node Properties
|
||||
|
||||
@ -142,7 +138,7 @@ The Templating System
|
||||
Concepts and Configuration
|
||||
|
||||
* Directories and Files::
|
||||
* The Org-roam Buffer: The Org-roam Buffer (1).
|
||||
* The Org-roam Buffer: The Org-roam Buffer (1).
|
||||
* Org-roam Files::
|
||||
* Org-roam Faces::
|
||||
|
||||
@ -325,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
|
||||
@ -340,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
|
||||
@ -350,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
|
||||
|
||||
@ -359,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
|
||||
|
||||
@ -428,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
|
||||
@ -532,20 +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 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 @footnote{Two easy ways to evaluate elisp: 1) Place the cursor after the closing
|
||||
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}).}
|
||||
that this is the case by executing:
|
||||
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")
|
||||
@ -558,7 +549,7 @@ your Emacs configuration:
|
||||
* The Org-roam Node::
|
||||
* Links between Nodes::
|
||||
* Setting up Org-roam::
|
||||
* Creating New Notes::
|
||||
* Creating and Linking Nodes::
|
||||
@end menu
|
||||
|
||||
@node The Org-roam Node
|
||||
@ -609,9 +600,9 @@ 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 primary capability comes from its aggressive caching: it crawls all
|
||||
files within @code{org-roam-directory}, keeping a cache of all its links and nodes,
|
||||
and making sure that the cache is consistent.
|
||||
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
|
||||
@ -638,38 +629,43 @@ To build the cache manually, one can run @code{M-x org-roam-db-build-cache}. Cac
|
||||
builds may take a while the first time, but is often instantaneous in subsequent
|
||||
runs because it only reprocesses modified files.
|
||||
|
||||
@node Creating New Notes
|
||||
@section @strong{TODO} Creating New Notes
|
||||
@node Creating and Linking Nodes
|
||||
@section @strong{TODO} Creating and Linking Nodes
|
||||
|
||||
Let us now create our first node. Call @code{M-x org-roam-find-file}. This shows 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. Entering the title
|
||||
of the note you wish to create, and pressing @code{RET} should begin the note
|
||||
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.
|
||||
|
||||
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}.
|
||||
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}.
|
||||
|
||||
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.
|
||||
@node Viewing the links
|
||||
@chapter @strong{TODO} Viewing the links
|
||||
|
||||
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}).
|
||||
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}.
|
||||
|
||||
@node Node Properties
|
||||
@chapter @strong{TODO} Node Properties
|
||||
@ -1014,7 +1010,7 @@ org-roam}.
|
||||
|
||||
@menu
|
||||
* Directories and Files::
|
||||
* The Org-roam Buffer: The Org-roam Buffer (1).
|
||||
* The Org-roam Buffer: The Org-roam Buffer (1).
|
||||
* Org-roam Files::
|
||||
* Org-roam Faces::
|
||||
@end menu
|
||||
|
||||
@ -152,24 +152,24 @@ which visits the thing at point."
|
||||
(defun org-roam-buffer ()
|
||||
"Launch an Org-roam buffer for the current node at point."
|
||||
(interactive)
|
||||
(unless (org-roam--org-file-p (buffer-file-name (buffer-base-buffer)))
|
||||
(user-error "Not in Org-roam file"))
|
||||
(let ((file (buffer-file-name))
|
||||
(buffer (get-buffer-create
|
||||
(concat "org-roam: "
|
||||
(file-relative-name (buffer-file-name) org-roam-directory))))
|
||||
(node (org-roam-node-at-point)))
|
||||
(with-current-buffer buffer
|
||||
(let ((inhibit-read-only t))
|
||||
(erase-buffer)
|
||||
(org-roam-mode)
|
||||
(org-roam-set-header-line-format
|
||||
(org-roam-node-title node))
|
||||
(magit-insert-section (demo-buffer)
|
||||
(magit-insert-heading)
|
||||
(dolist (fn org-roam-mode-sections)
|
||||
(funcall fn :node node :file file)))))
|
||||
(switch-to-buffer-other-window buffer)))
|
||||
(if-let ((node (org-roam-node-at-point)))
|
||||
(progn
|
||||
(let ((file (buffer-file-name (buffer-base-buffer)))
|
||||
(buffer (get-buffer-create
|
||||
(concat "org-roam: "
|
||||
(file-relative-name (buffer-file-name) org-roam-directory)))))
|
||||
(with-current-buffer buffer
|
||||
(let ((inhibit-read-only t))
|
||||
(erase-buffer)
|
||||
(org-roam-mode)
|
||||
(org-roam-set-header-line-format
|
||||
(org-roam-node-title node))
|
||||
(magit-insert-section (demo-buffer)
|
||||
(magit-insert-heading)
|
||||
(dolist (fn org-roam-mode-sections)
|
||||
(funcall fn :node node :file file)))))
|
||||
(switch-to-buffer-other-window buffer)))
|
||||
(user-error "No node at point")))
|
||||
|
||||
(provide 'org-roam-mode)
|
||||
;;; org-roam-mode.el ends here
|
||||
|
||||
Reference in New Issue
Block a user