awesome-emacs/org-roam
1
0
Fork 0
mirror of https://github.com/org-roam/org-roam synced 2025-08-01 12:17:21 -05:00
Code Issues Packages Projects Releases Wiki Activity

update docs

Browse Source
This commit is contained in:
Jethro Kuan
2021-03-24 23:48:35 +08:00
parent 6bcf164036
commit e19c3d6273
3 changed files with 117 additions and 113 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
doc/org-roam.org
View File

@ -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 Org-roam makes it easy to create new zettels, pre-filling boilerplate content
using a powerful templating system. using a powerful templating system.
** Fleeting notes *Fleeting notes*
A slip-box requires a method for quickly capturing ideas. These are called 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 *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 functionality (see [[*Daily-notes][Daily-notes]]). This provides a central inbox for collecting
thoughts, to be processed later into permanent notes. thoughts, to be processed later into permanent notes.
** Permanent notes *Permanent notes*
Permanent notes are further split into two categories: *literature notes* and Permanent notes are further split into two categories: *literature notes* and
*concept notes*. Literature notes can be brief annotations on a particular *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 self-explanatory and detailed. Org-roam's templating system supports the
addition of different templates to facilitate the creation of these notes. 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 * Installation
Org-roam can be installed using Emacs' package manager or manually from its 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. 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. 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 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 ** Post-Installation Tasks
Org-roam requires ~sqlite3~ to be located on ~exec-path~. Please ensure that Org-roam requires ~sqlite3~ to be locatable by Emacs (i.e. on ~exec-path~).
~sqlite3~ is installed appropriately on your operating system. You can verify [fn:2] Please ensure that ~sqlite3~ is installed appropriately on your operating
that this is the case by executing: system. You can verify that this is the case by executing [fn:2]:
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(executable-find "sqlite3") (executable-find "sqlite3")
#+END_SRC #+END_SRC
If you have ~sqlite3~ installed, and ~executable-find~ still reports ~nil~, then 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 the path to the executable is not a member of the Emacs variable ~exec-path~.
variable ~exec-path~. You may rectify this by manually adding the path within Rectify this by manually adding the path within your Emacs configuration:
your Emacs configuration:
#+BEGIN_SRC emacs-lisp #+BEGIN_SRC emacs-lisp
(add-to-list 'exec-path "path/to/sqlite3") (add-to-list 'exec-path "path/to/sqlite3")
#+END_SRC #+END_SRC
* Getting Started * Getting Started
** The Org-roam Node ** The Org-roam Node
We first begin with some terminology we'll use throughout the manual. We term 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 ** Setting up Org-roam
Org-roam's primary capability comes from its aggressive caching: it crawls all Org-roam's capabilities stem from its aggressive caching: it crawls all files
files within ~org-roam-directory~, keeping a cache of all its links and nodes, within ~org-roam-directory~, keeping a cache of all its links and nodes, while
and making sure that the cache is consistent. making sure that the cache is consistent.
To first start using Org-roam, one needs to pick a location to store the 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 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 builds may take a while the first time, but is often instantaneous in subsequent
runs because it only reprocesses modified files. 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 Org-roam makes it easy to create notes and link them together. There are 2 main
list of titles for nodes that reside in ~org-roam-directory~. It should show functions for creating nodes:
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-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 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 be customized (see [[*The Templating System][The Templating System]]). Using the default template, pressing
~C-c C-c~ finishes the note capture. ~C-c C-c~ finishes the note capture.
For experienced ~org-capture~ users, the behavior 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
may seem unfamiliar: after finishing a capture with ~C-c C-c~, you are returned org-roam-node-insert~. This brings up the list of nodes, which should contain
not to the original buffer from which you called ~M-x org-roam-find-file~, but the node you just created. Selecting the node will insert an ~id:~ link to the
to a buffer pointing to the note you just created. For the usual ~org-capture~ node. If you instead entered a title that does not exist, you will once again be
behavior you can call ~M-x org-roam-capture~ instead of ~M-x org-roam-find-file~. 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 # For experienced ~org-capture~ users, the behavior of ~M-x org-roam-find-file~
together, we call ~M-x org-roam-insert~. This brings up a prompt with a list of # may seem unfamiliar: after finishing a capture with ~C-c C-c~, you are returned
title for existing notes. Selecting an existing entry will create and insert a # not to the original buffer from which you called ~M-x org-roam-find-file~, but
link to the current file. Entering a non-existent title will create a new note # to a buffer pointing to the note you just created. For the usual ~org-capture~
with that title. Good usage of Org-roam requires liberally linking files: this # behavior you can call ~M-x org-roam-capture~ instead of ~M-x org-roam-find-file~.
facilitates building up a dense graph of inter-connected notes.
Org-roam provides an interface to view backlinks. It shows backlinks for the * TODO Viewing the links
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 Org-roam provides an interface to view relationships with other notes
provides graphing capabilities, using Graphviz. It generates graphs with notes (backlinks, reference links, unlinked references etc.). To pop up this info
as nodes, and links between them as edges. The generated graph can be used to buffer, call ~M-x org-roam-buffer~.
navigate to the files, but this requires some additional setup (see [[*Roam
Protocol][Roam Protocol]]).
* TODO Node Properties * TODO Node Properties
** TODO Standard Org properties ** TODO Standard Org properties
@ -446,6 +451,9 @@ key and a URL at the same time.
* TODO The Org-roam Buffer * TODO The Org-roam Buffer
* TODO Styling Org-roam * TODO Styling Org-roam
* TODO Completion * TODO Completion
:PROPERTIES:
:ID: 70083bfd-d1e3-42b9-bf83-5b05708791c0
:END:
* TODO Encryption * TODO Encryption
* TODO Org-roam protocol * TODO Org-roam protocol
* TODO Diagnosing and Repair * TODO Diagnosing and Repair

106
doc/org-roam.texi
View File

@ -67,6 +67,7 @@ General Public License for more details.
* A Brief Introduction to the Zettelkasten Method:: * A Brief Introduction to the Zettelkasten Method::
* Installation:: * Installation::
* Getting Started:: * Getting Started::
* Viewing the links::
* Node Properties:: * Node Properties::
* The Org-roam Buffer:: * The Org-roam Buffer::
* Styling Org-roam:: * Styling Org-roam::
@ -101,16 +102,11 @@ General Public License for more details.
@detailmenu @detailmenu
--- The Detailed Node Listing --- --- The Detailed Node Listing ---
A Brief Introduction to the Zettelkasten Method
* Fleeting notes::
* Permanent notes::
Installation Installation
* Installing from MELPA:: * Installing from MELPA::
* Installing from Apt:: * Installing from Apt::
* Installing from the Git Repository:: * Installing from Source::
* Post-Installation Tasks:: * Post-Installation Tasks::
Getting Started Getting Started
@ -118,7 +114,7 @@ Getting Started
* The Org-roam Node:: * The Org-roam Node::
* Links between Nodes:: * Links between Nodes::
* Setting up Org-roam:: * Setting up Org-roam::
* Creating New Notes:: * Creating and Linking Nodes::
Node Properties Node Properties
@ -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 Org-roam makes it easy to create new zettels, pre-filling boilerplate content
using a powerful templating system. using a powerful templating system.
@menu @strong{Fleeting notes}
* Fleeting notes::
* Permanent notes::
@end menu
@node Fleeting notes
@section Fleeting notes
A slip-box requires a method for quickly capturing ideas. These are called 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 @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 functionality (see @ref{Daily-notes}). This provides a central inbox for collecting
thoughts, to be processed later into permanent notes. thoughts, to be processed later into permanent notes.
@node Permanent notes @strong{Permanent notes}
@section Permanent notes
Permanent notes are further split into two categories: @strong{literature notes} and Permanent notes are further split into two categories: @strong{literature notes} and
@strong{concept notes}. Literature notes can be brief annotations on a particular @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 self-explanatory and detailed. Org-roam's templating system supports the
addition of different templates to facilitate the creation of these notes. 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 @node Installation
@chapter Installation @chapter Installation
@ -359,7 +351,7 @@ development repository.
@menu @menu
* Installing from MELPA:: * Installing from MELPA::
* Installing from Apt:: * Installing from Apt::
* Installing from the Git Repository:: * Installing from Source::
* Post-Installation Tasks:: * Post-Installation Tasks::
@end menu @end menu
@ -428,8 +420,8 @@ apt-get install elpa-org-roam
Org-roam will then be autoloaded into Emacs. Org-roam will then be autoloaded into Emacs.
@node Installing from the Git Repository @node Installing from Source
@section Installing from the Git Repository @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. 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 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 @node Post-Installation Tasks
@section Post-Installation Tasks @section Post-Installation Tasks
Org-roam requires @code{sqlite3} to be located on @code{exec-path}. Please ensure that Org-roam requires @code{sqlite3} to be locatable by Emacs (i.e. on @code{exec-path}).
@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 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 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}).} an Org file code block (like @samp{#+BEGIN_SRC emacs-lisp}).}:
that this is the case by executing:
@lisp @lisp
(executable-find "sqlite3") (executable-find "sqlite3")
@end lisp @end lisp
If you have @code{sqlite3} installed, and @code{executable-find} still reports @code{nil}, then 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 the path to the executable is not a member of the Emacs variable @code{exec-path}.
variable @code{exec-path}. You may rectify this by manually adding the path within Rectify this by manually adding the path within your Emacs configuration:
your Emacs configuration:
@lisp @lisp
(add-to-list 'exec-path "path/to/sqlite3") (add-to-list 'exec-path "path/to/sqlite3")
@ -558,7 +549,7 @@ your Emacs configuration:
* The Org-roam Node:: * The Org-roam Node::
* Links between Nodes:: * Links between Nodes::
* Setting up Org-roam:: * Setting up Org-roam::
* Creating New Notes:: * Creating and Linking Nodes::
@end menu @end menu
@node The Org-roam Node @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 @node Setting up Org-roam
@section Setting up Org-roam @section Setting up Org-roam
Org-roam's primary capability comes from its aggressive caching: it crawls all Org-roam's capabilities stem from its aggressive caching: it crawls all files
files within @code{org-roam-directory}, keeping a cache of all its links and nodes, within @code{org-roam-directory}, keeping a cache of all its links and nodes, while
and making sure that the cache is consistent. making sure that the cache is consistent.
To first start using Org-roam, one needs to pick a location to store the 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 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 builds may take a while the first time, but is often instantaneous in subsequent
runs because it only reprocesses modified files. runs because it only reprocesses modified files.
@node Creating New Notes @node Creating and Linking Nodes
@section @strong{TODO} Creating New Notes @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 Org-roam makes it easy to create notes and link them together. There are 2 main
list of titles for nodes that reside in @code{org-roam-directory}. It should show functions for creating nodes:
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 @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 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 be customized (see @ref{The Templating System}). Using the default template, pressing
@code{C-c C-c} finishes the note capture. @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} Now that we have a node, we can try inserting a link to the node using @code{M-x
may seem unfamiliar: after finishing a capture with @code{C-c C-c}, you are returned org-roam-node-insert}. This brings up the list of nodes, which should contain
not to the original buffer from which you called @code{M-x org-roam-find-file}, but the node you just created. Selecting the node will insert an @code{id:} link to the
to a buffer pointing to the note you just created. For the usual @code{org-capture} node. If you instead entered a title that does not exist, you will once again be
behavior you can call @code{M-x org-roam-capture} instead of @code{M-x org-roam-find-file}. 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 @node Viewing the links
together, we call @code{M-x org-roam-insert}. This brings up a prompt with a list of @chapter @strong{TODO} Viewing the links
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 Org-roam provides an interface to view relationships with other notes
currently active Org-roam note, along with some surrounding context. To toggle (backlinks, reference links, unlinked references etc.). To pop up this info
the visibility of this buffer, call @code{M-x org-roam}. buffer, call @code{M-x org-roam-buffer}.
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 Node Properties @node Node Properties
@chapter @strong{TODO} Node Properties @chapter @strong{TODO} Node Properties

10
org-roam-mode.el
View File

@ -152,13 +152,12 @@ which visits the thing at point."
(defun org-roam-buffer () (defun org-roam-buffer ()
"Launch an Org-roam buffer for the current node at point." "Launch an Org-roam buffer for the current node at point."
(interactive) (interactive)
(unless (org-roam--org-file-p (buffer-file-name (buffer-base-buffer))) (if-let ((node (org-roam-node-at-point)))
(user-error "Not in Org-roam file")) (progn
(let ((file (buffer-file-name)) (let ((file (buffer-file-name (buffer-base-buffer)))
(buffer (get-buffer-create (buffer (get-buffer-create
(concat "org-roam: " (concat "org-roam: "
(file-relative-name (buffer-file-name) org-roam-directory)))) (file-relative-name (buffer-file-name) org-roam-directory)))))
(node (org-roam-node-at-point)))
(with-current-buffer buffer (with-current-buffer buffer
(let ((inhibit-read-only t)) (let ((inhibit-read-only t))
(erase-buffer) (erase-buffer)
@ -170,6 +169,7 @@ which visits the thing at point."
(dolist (fn org-roam-mode-sections) (dolist (fn org-roam-mode-sections)
(funcall fn :node node :file file))))) (funcall fn :node node :file file)))))
(switch-to-buffer-other-window buffer))) (switch-to-buffer-other-window buffer)))
(user-error "No node at point")))
(provide 'org-roam-mode) (provide 'org-roam-mode)
;;; org-roam-mode.el ends here ;;; org-roam-mode.el ends here