diff --git a/doc/org-roam.org b/doc/org-roam.org index ff8263c..c44199b 100644 --- a/doc/org-roam.org +++ b/doc/org-roam.org @@ -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 diff --git a/doc/org-roam.texi b/doc/org-roam.texi index 2e916c6..fda8907 100644 --- a/doc/org-roam.texi +++ b/doc/org-roam.texi @@ -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 diff --git a/org-roam-mode.el b/org-roam-mode.el index 5bb2e55..d4b0e54 100644 --- a/org-roam-mode.el +++ b/org-roam-mode.el @@ -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