(docs): update docs (#229)

README.md

@@ -57,7 +57,7 @@ For more detailed installation instructions (including instructions for
 Spacemacs users), please see [the installation
 documentation](https://org-roam.readthedocs.io/en/develop/installation/).
 
-## Knowledge Bases using Org-Roam
+## Knowledge Bases using Org-roam
 
 - [Jethro Kuan](https://braindump.jethro.dev/)
   ([Source](https://github.com/jethrokuan/braindump/tree/master/org))

doc/anatomy.md

@@ -1,12 +1,12 @@
 The bulk of Org-roam's functionality is built on top of vanilla
-Org-mode features. However, to support additional functionality,
+Org-mode. However, to support additional functionality, Org-roam adds
-Org-roam adds several Org-roam-specific keywords. This functionality
+several Org-roam-specific keywords. These functionality are not
-is not crucial to effective use of Org-roam.
+crucial to effective use of Org-roam.
 
 ## File Aliases
 
 Suppose you want a note to be referred to by different names (e.g.
-"World War 2", "WWII"). You may specify such aliases using the file
+"World War 2", "WWII"). You may specify such aliases using the
 `#+ROAM_ALIAS` attribute:
 
 ```org
@@ -14,3 +14,27 @@ Suppose you want a note to be referred to by different names (e.g.
 #+ROAM_ALIAS: "WWII" "World War II"
 ```
 
+
+## File Refs
+
+Refs are unique identifiers for files. Each note can only have 1 ref.
+For example, a note for a website may contain a ref:
+
+```org
+#+TITLE: Google
+#+ROAM_KEY: https://www.google.com/
+```
+
+These keys come in useful for when taking website notes, using the
+`roam-ref` protocol (see [Roam Protocol](roam_protocol.md)).
+
+Alternatively, add a ref for notes for a specific paper, using its
+[org-ref](https://github.com/jkitchin/org-ref) citation key:
+
+```org
+#+TITLE: Neural Ordinary Differential Equations
+#+ROAM_KEY: cite:chen18_neural_ordin_differ_equat
+```
+
+In future, the backlinks buffer will also show notes with that
+citation key.

doc/comparison.md

@@ -1,7 +1,7 @@
 ---
-title: "Comparing Org-Roam With Other Packages"
+title: "Comparing Org-roam With Other Packages"
-metaTitle: "Comparing Org-Roam With Other Packages"
+metaTitle: "Comparing Org-roam With Other Packages"
-metaDescription: "Comparing Org-Roam With Other Packages"
+metaDescription: "Comparing Org-roam With Other Packages"
 ---
 
 # Org-brain

doc/configuration.md

@@ -1,19 +1,13 @@
-To ensure that Org-roam remains manageable, the number of
+The number of configuration options is deliberately kept small, to
-configuration options is deliberately kept small. However, we have
+keep the Org-roam codebase manageable. However, we attempt to
-attempted to accommodate as many usage styles as possible.
+accommodate as many usage styles as possible.
-
-In this section, we'll go over the main customization options
-available to Org-Roam. This section is *crucial*. We need to exploit
-the flexibility of Emacs, and mould our tools exactly to our liking.
 
 All of Org-roam's customization options can be viewed via `M-x
 customize-group org-roam`.
 
 ## Setting the Org-roam Directory
 
-Perhaps the single most important variable to set is
+Set `org-roam-directory` to the folder containing all your Org files:
-`org-roam-directory`. Set `org-roam-directory` to the folder
-containing all your Org files:
 
 ```emacs-lisp
 (setq org-roam-directory "/path/to/org/")
@@ -24,22 +18,21 @@ considered part of the Org-roam ecosystem.
 
 ### Having More Than One Org-roam Directory
 
-Emacs supports customizing variables by directory, so that all files
+Emacs supports directory-local variables, allowing the value of
-in a directory and subdirectories will have the same custom
+`org-roam-directory` to be different in different directories. It does
-settings. It does this by checking for a file named `.dir-locals.el`
+this by checking for a file named `.dir-locals.el`. 
-in that directory. This file can override the `org-roam-directory`
-variable and all files within that directory will be treated as
-their own separate set of Org-roam files.
 
-Here is an example `.dir-locals.el` file that would be placed in a
+To add support for multiple directories, override the
-second Org-roam directory.
+`org-roam-directory` variable using directory-local variables. This is
+what `.dir-locals.el` may contain:
 
 ```emacs-lisp
 ((nil . ((org-roam-directory . "/path/to/here/"))))
 ```
 
-Remember to run `org-roam-build-cache` from a file within that
+All files within that directory will be treated as their own separate
-directory, at least once.
+set of Org-roam files. Remember to run `org-roam-build-cache` from a
+file within that directory, at least once.
 
 ## Org-roam Buffer
 
@@ -59,14 +52,13 @@ frame width. For example:
 ```
 
 Will result in the Org-roam buffer taking up 40% of the screen width.
-I have found this to be a good number.
 
 ## Org-roam Links
 
 By default, links are inserted with the title as the link description.
-This can make them hard to distinguish from external links. If you
+This can make them hard to distinguish from external links. You may
-wish, you may choose add special indicators for Org-roam links by
+choose add special indicators for Org-roam links by tweaking
-tweaking `org-roam-link-title-format`, for example:
+`org-roam-link-title-format`, for example:
 
 ```emacs-lisp
 (setq org-roam-link-title-format "R:%s")
@@ -78,90 +70,20 @@ simply style the link differently, by customizing `org-roam-link-face`
 
 ## Org-roam Files
 
-These customization options revolve around the Org files created and
+Org-roam files are created and prefilled using Org-roam's templating
-managed by Org-roam.
+system. The templating system is customizable, and the system is
-
+described in detail in the [Org-roam Template](templating.md) page.
-### Automatically Creating Files Using Timestamp
-
-A common hassle is ensuring that files are uniquely named within the
-Org-roam directory. Org-roam's default workflow utilizes the title of
-Org files in all of its main commands (`org-roam-insert`,
-`org-roam-find-file`). Hence, having any unique file name is a decent
-option, and the default workflow uses the timestamp as the filename.
-
-Org-roam provides templating functionality via `org-roam-templates`.
-`org-roam-templates` maps a template string key to a template. Each
-template consists of two parts: (1) a function that takes the title,
-and generates a filename. (2) the template content. The templated
-content accepts two special fields: `${title}` and `${slug}`, which
-are substituted with the title and slug respectively. Org-roam ships
-with the default template, which inserts the title of the note. 
-
-Here's an example of customizing templates:
-
-```emacs-lisp
-(defun jethro/org-roam-title-private (title)
-    (let ((timestamp (format-time-string "%Y%m%d%H%M%S" (current-time)))
-          (slug (org-roam--title-to-slug title)))
-      (format "private-%s_%s" timestamp slug)))
-      
-(setq org-roam-templates
-    (list (list "default" (list :file #'org-roam--file-name-timestamp-title
-                                :content "#+SETUPFILE:./hugo_setup.org
-#+HUGO_SECTION: zettels
-#+HUGO_SLUG: ${slug}
-#+TITLE: ${title}"))
-          (list "private" (list :file #'jethro/org-roam-title-private
-                                :content "#+TITLE: ${title}"))))
-```
-
-Here, I define a file-name function `jethro/org-roam-title-private`,
-which forms titles like `private-20200202000000-note_name`. The
-content string is simply the title. For the default template, I have
-extended it to include more boilerplate content for publishing
-purposes.
-
-If you wish to be prompted to change the file name on creation, set
-`org-roam-filename-noconfirm` to `nil`:
-
-```emacs-lisp
-(setq org-roam-filename-noconfirm nil)
-```
-
-It is then the user's responsibility to ensure that the file names are
-unique.
-
-If you prefer just the title slug as the filename (with no timestamp),
-you can use the following template:
-
-```emacs-lisp
-(defun my-org-roam-no-timestamp-in-title (title)
-    (let ((slug (org-roam--title-to-slug title)))
-      (format "%s" slug)))
-
-(setq org-roam-templates
-    (list (list "default" (list :file #'my-org-roam-no-timestamp-in-title
-:content "#+TITLE: ${title}"))))
-```
-
-### Autopopulating Titles
-
-The default workflow uses the title of the Org file in several
-commands. The title is specified via the `#+TITLE:` attribute,
-typically near the top of the file. The option
-`org-roam-autopopulate-title` defaults to `t`. When true, the title
-attribute is automatically inserted into the files created via
-Org-roam commands. Setting it to `nil` will disable this behaviour.
 
 ### Encryption
 
 Encryption (via GPG) can be enabled for all new files by setting
 `org-roam-encrypt-files` to `t`. When enabled, new files are created
-with the .org.gpg extension and decryption are handled automatically
+with the `.org.gpg` extension and decryption are handled automatically
-by EasyPG. Note that this causes Emacs to ask for password when the
+by EasyPG. 
-cache is built (if you have an encrypted file in `org-roam-directory`)
+
-as well as each time a new file is created. It might be a good idea to
+Note that Emacs will prompt for a password for encrypted files during
-cache the password in order to make this more managable.
+cache updates if it requires reading the encrypted file. To reduce the
+number of password prompts, you may wish to cache the password.
 
 ## Org-roam Graph Viewer
 
@@ -170,13 +92,13 @@ Org-roam generates an SVG image using
 [Graph Setup](graph_setup.md) page.
 
 Org-roam tries its best to locate the Graphviz executable from your
-PATH, but if it fails to do so, you may set it manually:
+`PATH`, but if it fails to do so, you may set it manually:
 
 ```
 (setq org-roam-graphviz-executable "/path/to/dot")
 ```
 
-Org-roam also attempts to use Firefox (located on PATH) to view the
+Org-roam also attempts to use Firefox (located on `PATH`) to view the
 SVG, you may choose to set it to any compatible program:
 
 ```

doc/ecosystem.md

@@ -117,6 +117,12 @@ within Org-mode.
 [Org-ref][org-ref] does citation and bibliography management in
 Org-mode, and a great tool for scientific notes.
 
+### Spaced Repetition
+
+[Org-fc][org-fc] is a spaced repetition system that scales well with a
+large number of files. Other alternatives include
+[org-drill][org-drill], and [pamparam][pamparam].
+
 [deft]: https://jblevins.org/projects/deft/
 [notdeft]: https://github.com/hasu/notdeft
 [org-download]: https://github.com/abo-abo/org-download
@@ -124,3 +130,6 @@ Org-mode, and a great tool for scientific notes.
 [org-noter]: https://github.com/weirdNox/org-noter
 [interleave]: https://github.com/rudolfochrist/interleave
 [org-ref]: https://github.com/jkitchin/org-ref
+[org-fc]: https://github.com/l3kn/org-fc/
+[org-drill]: https://orgmode.org/worg/org-contrib/org-drill.html
+[pamparam]: https://github.com/abo-abo/pamparam

doc/index.md

@@ -1,40 +1,62 @@
 ![org-roam][org-roam-intro-image]
 
-## What is Org-Roam?
+## What is Org-roam?
 
-Org-roam is a rudimentary [Roam][roamresearch] replica built around
+Org-roam is a [Roam][roamresearch] replica built around the
-the all-powerful [Org-mode][org]. 
+all-powerful [Org-mode][org].
 
-Like Roam, Org-roam offers a powerful and effortless non-hierarchical
+Org-roam is a solution for effortless non-hierarchical note-taking,
-note-taking approach. With Org-roam, notes flow naturally, making
+building upon Org-mode. This solution is heavily inspired by [Roam
-note-taking fun and easy. To understand more about Roam, I recommend
+Research][roamresearch]. With Org-roam, notes flow naturally, making
-the following links:
+note-taking fun and easy. Org-roam should also work as a plug-and-play
+solution for anyone already using Org-mode for their personal wiki.
 
--   [Building a second brain in
+To understand more about Roam, a collection of links are available in
-    Roam](https://reddit.com/r/RoamResearch/comments/eho7de/building_a_second_brain_in_roamand_why_you_might)
+[the appendix](notetaking_workflow.md).
--   [Roam: Why I Love It and How I Use
-    It](https://www.nateliason.com/blog/roam)
 
-The goal of the project is to implement core features of Roam around
+Org-roam aims to implement the core features of Roam, leveraging the
-Org-mode, and eventually introduce features enabled by the Emacs
+mature ecosystem around Org-mode where possible. Eventually, we hope
-ecosystem. 
+to further introduce features enabled by the Emacs ecosystem.
 
-## Why build Org-Roam?
+## Why use Org-roam?
 
-With Org-roam, you:
+##### Private and Secure
 
-1. Never have to leave Emacs.
+Edit your personal wiki completely offline, entirely in your control.
-2. Can leverage all the powerful features of Org-mode: LaTeX, tables,
+Encrypt your notes with GPG.
-   and the whole to-do ecosystem (org-agenda etc.)
+
-3. Be in full control your second brain, and access it offline. Never
+##### Longevity
-   share your data with anyone
+
+Unlike web solutions like Roam research, the notes are first and
+foremost plain Org-mode files -- Org-roam simply builds up an
+auxilliary database to give the personal wiki superpowers. Having your
+notes in plain-text is crucial for the longevity of your wiki. Never
+have to worry about proprietary web solutions being taken down. Edit
+your plain-text notes in notepad if all other editors cease to exist.
+
+##### Free and Open-source
+
+Org-roam is free and open-source, which means that if you feel unhappy
+with any part of Org-roam, you may choose to extend Org-roam, or open
+a PR.
+
+##### Leverage the Org-mode Ecosystem
+
+Over the years, 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.
+
+Emacs is also a fantastic interface for editing text, and we can
+inherit many of the powerful text-navigation and editing packages
+available to Emacs.
 
 There are several packages that are similar to Org-roam, see the
 [Comparison](comparison.md) page for a detailed comparison.
 
 ## Project Status
 
-As of February 2020, it is in a very early stage of development. 
+As of March 2020, most of the core functionality and interfaces have
+stabilized, and a stable release is near.
 
 [org-roam-intro-image]: images/org-roam-intro.png
 [roamresearch]: https://www.roamresearch.com/

doc/installation.md

@@ -3,7 +3,7 @@
 The recommended method is using [use-package][use-package] and
 [straight][straight], or a similar package manager.
 
-```
+```emacs-lisp
 (use-package org-roam
       :hook 
       (after-init . org-roam-mode)
@@ -13,6 +13,7 @@ The recommended method is using [use-package][use-package] and
       :bind (:map org-roam-mode-map
               (("C-c n l" . org-roam)
                ("C-c n f" . org-roam-find-file)
+               ("C-c n b" . org-roam-switch-to-buffer)
                ("C-c n g" . org-roam-show-graph))
               :map org-mode-map
               (("C-c n i" . org-roam-insert))))
@@ -25,39 +26,48 @@ directory and add it to your load path:
 git clone https://github.com/jethrokuan/org-roam/ ~/.emacs.d/elisp/org-roam
 ```
 
-```
+```emacs-lisp
 (use-package org-roam
-      :load-path "elisp/"
+  :load-path "elisp/"
-      :hook 
+  :hook
-      (after-init . org-roam-mode)
+  (after-init . org-roam-mode)
-      :straight (:host github :repo "jethrokuan/org-roam" :branch "develop")
+  :straight (:host github :repo "jethrokuan/org-roam" :branch "develop")
-      :custom
+  :custom
-      (org-roam-directory "/path/to/org-files/")
+  (org-roam-directory "/path/to/org-files/")
-      :bind (:map org-roam-mode-map
+  :bind (:map org-roam-mode-map
               (("C-c n l" . org-roam)
                ("C-c n f" . org-roam-find-file)
+               ("C-c n b" . org-roam-switch-to-buffer)
                ("C-c n g" . org-roam-show-graph))
               :map org-mode-map
               (("C-c n i" . org-roam-insert))))
 ```
 
-Or without use-package:
+Or without `use-package`:
 
-```
+```emacs-lisp
 (add-to-list 'load-path "./elisp")
 (require 'org-roam)
+(define-key 'org-roam-mode-map (kbd "C-c n l") #'org-roam)
+(define-key 'org-roam-mode-map (kbd "C-c n f") #'org-roam-find-file)
+(define-key 'org-roam-mode-map (kbd "C-c n b") #'org-roam-switch-to-buffer)
+(define-key 'org-roam-mode-map (kbd "C-c n g") #'org-roam-switch-to-buffer)
+(define-key 'org-mode-map (kbd "C-c n i") #'org-roam-insert)
+(org-roam-mode +1)
 ```
 
-There are a number of important configuration options, that greatly
+The [Configuration](configuration.md) page details some of the common
-affect the Roam workflow. Do look through them at the
+configuration options available.
-[Configuration](configuration.md) page.
 
 [use-package]: https://github.com/jwiegley/use-package
 [straight]: https://github.com/raxod502/straight.el
 
 ## Spacemacs
-If you are using Spacemacs, you can easily install org-roam by creating a simple layer that wraps org-roam. Paste the following into a new file `/.emacs.d/private/org-roam/packages.el`.
+If you are using Spacemacs, install org-roam by creating a simple
-```
+layer that wraps Org-roam. Paste the following into a new file
+`~/.emacs.d/private/org-roam/packages.el`.
+
+```emacs-lisp
 (defconst org-roam-packages
   '((org-roam :location
         (recipe :fetcher github :repo "jethrokuan/org-roam" :branch "develop"))))
@@ -87,13 +97,16 @@ If you are using Spacemacs, you can easily install org-roam by creating a simple
             "rg" 'org-roam-show-graph))))
 ```
 
-Next, append `org-roam` to the `dotspacemacs-configuration-layers` list in your `.spacemacs` configuration file. Reload (`SPC f e R`) or restart Emacs to load `org-roam`. It's functions are available under the prefix `SPC a r` and `, r` when visiting an org-mode buffer. 
+Next, append `org-roam` to the `dotspacemacs-configuration-layers`
+list in your `.spacemacs` configuration file. Reload (`SPC f e R`) or
+restart Emacs to load `org-roam`. It's functions are available under
+the prefix `SPC a r` and `, r` when visiting an org-mode buffer.
 
 ## Doom Emacs
 
 If you are using [Doom Emacs](https://github.com/hlissner/doom-emacs), configure packages as explained in the [getting started](https://github.com/hlissner/doom-emacs/blob/develop/docs/getting_started.org#configuring-packages) guide. 
 
-Declare org-roam as a package in your `~/.doom.d/packages.el`:
+Declare Org-roam as a package in your `~/.doom.d/packages.el`:
 
 ```elisp
 ;; ~/.doom.d/packages.el
@@ -102,7 +115,7 @@ Declare org-roam as a package in your `~/.doom.d/packages.el`:
   :recipe (:host github :repo "jethrokuan/org-roam" :branch "develop"))
 ```
 
-Subsequently, in your `~/.doom.d/config.el` file, configure org-roam:
+Subsequently, in your `~/.doom.d/config.el` file, configure Org-roam:
 
 ```elisp
 ;; ~/.doom.d/config.el

doc/notetaking_workflow.md

@@ -8,6 +8,9 @@
 - [Roam: Why I Love It and How I Use It][5]
 - [Adam Keesling's Twitter Thread][6]
 
+## Threads
+- [Ask HN: How to Take Good Notes][8]
+
 ## What to Do With Your Notes
 - [How to Use Roam to Outline a New Article in Under 20 Minutes][2]
 
@@ -18,3 +21,4 @@
 [5]: https://www.nateliason.com/blog/roam
 [6]: https://twitter.com/adam_keesling/status/1196864424725774336?s=20
 [7]: https://blog.jethro.dev/posts/how_to_take_smart_notes_org/
+[8]: https://news.ycombinator.com/item?id=22473209

doc/roam_protocol.md

@@ -1,7 +1,7 @@
 ## What is Roam protocol?
 
-Org-roam defines two protocols that help boost productivity, by
+Org-roam extending `org-protocol` with 2 protocols: the `roam-file`
-extending `org-protocol`: the `roam-file` and `roam-ref` protocol.
+and `roam-ref` protocol.
 
 ## The `roam-file` protocol
 
@@ -30,22 +30,22 @@ where `template` is the template key for a template in
 `org-roam-ref-capture-templates`. More documentation on the templating
 system can be found [here](templating.md).
 
-These templates should contain a `#+ROAM_KEY: {ref}` in it.
+These templates should contain a `#+ROAM_KEY: ${ref}` in it.
 
-## Org-protocol Setup
+## Setting up Org-roam protocol
 
-The instructions for setting up org-protocol can be found
+To enable org-roam's protocol extensions, you have to add the
-[here][org-protocol-inst], but they are reproduced below.
+following to your init file:
-
-Across all platforms, to enable `org-roam-protocol`, you have to add
-the following to your init file:
 
 ```emacs-lisp
 (require 'org-roam-protocol)
 ```
 
-We also need to create a desktop application for emacsclient. The
+The instructions for setting up `org-protocol` can be found
-instructions for various platforms are shown below:
+[here][org-protocol-inst], but they are reproduced below.
+
+We will also need to create a desktop application for `emacsclient`.
+The instructions for various platforms are shown below:
 
 ## Linux
 

doc/tour.md

@@ -1,67 +1,65 @@
 Org-roam was built to support a workflow that was not possible with
 vanilla Org-mode. This flow is modelled after the [Zettelkasten
 method][zettelkasten], and many of [Roam Research][roam]'s workflows.
-Understanding this flow is crucial! Org-roam doesn't auto-magically
+It is crucial to understand that Org-roam does not auto-magically make
-make your note-taking better -- it's changing the note-taking workflow
+note-taking better -- it's changing the note-taking workflow that
-that does.
+does.
 
-To understand more the methods and madness, the [Note-Taking
+To understand more about the methods and madness, the [Note-Taking
-Workflow][appendix:ntw] page contains a page of useful references.
+Workflow][appendix:ntw] page contains a page of useful references. The
-I've also written [a post][jethro-blog-post] about how I use Org-roam.
+author has also written [a post][jethro-blog-post] about how he uses
+Org-roam.
 
-Without further ado, let's begin!
+## Activating Org-roam
 
-## Building the Cache
+Org-roam's entry point is the global minor `org-roam-mode`. This sets
+up Emacs with several hooks, for keeping the org-roam cache
+consistently updated, as well as showing the backlinks buffer. 
 
 The cache is a sqlite database named `org-roam.db`, which resides at
-the root of your `org-roam-directory`. To begin, we need to do a first
+the root of the `org-roam-directory`. Activating `org-roam-mode`
-build of this cache. To do so, run `M-x org-roam-build-cache`. This
+builds the cache, which may take a while the first time, but is
-may take a while the first time, but is generally instantaneous in
+generally instantaneous in subsequent runs. To build the cache
-subsequent runs.
+manually again, run `M-x org-roam-build-cache`.
 
 ## Finding a Note
 
-`org-roam-find-file` shows you the list of notes you currently have in
+`org-roam-find-file` shows the list of titles for notes that reside in
-Org-roam. Selecting the title will bring you to the corresponding
+`org-roam-directory`. Selecting a note title will bring you to the
-note. Entering a title of a note that does not yet exist will create a
+corresponding note. Entering a title of a note that does not yet exist
-new note with that title.
+will create a new note with that title.
 
 ![org-roam-find-file](images/org-roam-find-file.gif)
 
 ## Inserting Links
 
-Within your Org-roam notes, you are encouraged to liberally insert
+`org-roam-insert` insert links to existing (or new) notes. Entering a
-links to existing (or new) Org-roam notes with `org-roam-insert`.
+non-existent title will also create a new note with that title.
-Entering a non-existent title will also create a new note with that
-title.
 
 ![org-roam-insert](images/org-roam-insert-filetag.gif)
 
-It is crucial for good usage of Org-roam to insert links liberally
+Good usage of Org-roam requires liberally linking files. This allows
-where you want the notes to resurface!
+the build-up of a dense knowledge graph.
 
 ## The Org-roam Buffer
 
-All of Org-roam's operations are designed such that the built cache is
+The Org-roam buffer is often displayed in the side window. It shows
-a consistent view of the inter-connectivity between your notes. The
+backlinks for the currently active Org-roam note, along with some
-Org-roam buffer shows backlinks: i.e. the files that link to the
+surrounding context.
-currently viewed file, along with some surrounding context. The
-Org-roam buffer will always show the backlinks for the current
-Org-roam file in view.
 
 ![org-roam-buffer](images/org-roam-buffer.gif)
 
 ## Exporting the Graph
 
-It's also possible to export the links as a graph, using graphviz. The
+Org-roam also uses Graphviz to generate a graph, with notes as nodes,
-generated graph is navigable in Emacs, but requires some additional
+and links between them as edges. The generated graph can be used to
-setup, which I describe in the [Graph Appendix][appendix:graph-setup]
+navigate to the files, but this requires some additional setup
-page.
+described in the [Roam Protocol][appendix:roam-protocol] page.
 
 ![org-roam-graph](images/org-roam-graph.gif)
 
 [zettelkasten]: https://zettelkasten.de/
 [appendix:ntw]: notetaking_workflow.md
-[appendix:graph-setup]: graph_setup.md
+[appendix:roam-protocol]: roam_protocol.md
 [roam]: https://www.roamresearch.com/
 [jethro-blog-post]: https://blog.jethro.dev/posts/how_to_take_smart_notes_org/

mkdocs.yml

@@ -1,14 +1,14 @@
-site_name: "Org-Roam: Roam + Org-Mode = ♥"
+site_name: "Org-roam"
 repo_url: https://github.com/jethrokuan/org-roam/
 edit_uri: edit/master/doc/
 copyright: "Copyright (C) 2020 Jethro Kuan and contributors"
 docs_dir: doc
 nav:
 - Home: index.md
-- A Tour of Org-Roam: tour.md
+- A Tour of Org-roam: tour.md
 - Installation: installation.md
 - Configuration: configuration.md
-- Anatomy of a Roam file: anatomy.md
+- Anatomy of an Org-roam file: anatomy.md
 - The Templating System: templating.md
 - Ecosystem: ecosystem.md
 - Similar Packages: comparison.md

org-roam-protocol.el

@@ -25,6 +25,11 @@
 ;; We extend org-protocol, adding custom Org-roam handlers. The setup
 ;; instructions for `org-protocol' can be found in org-protocol.el.
 ;;
+;; We define 2 protocols:
+;;
+;; 1. "roam-file": This protocol simply opens the file given by the FILE key
+;; 2. "roam-ref": This protocol creates or opens a note with the given REF
+;;
 ;;; Code:
 
 (require 'org-protocol)
@@ -39,15 +44,14 @@
      :file-name "${slug}"
      :head "#+TITLE: ${title}
 #+ROAM_KEY: ${ref}\n"
-     :unnarrowed t)))
+     :unnarrowed t))
+  "The Org-roam templates used during a capture from the roam-ref protocol.
+Details on how to specify for the template is given in `org-roam-capture-templates'.")
 
 (defun org-roam-protocol-open-ref (info)
   "Process an org-protocol://roam-ref?ref= style url with INFO.
 
-The sub-protocol used to reach this function is set in
+It opens or creates a note with the given ref.
-`org-protocol-protocol-alist'.
-
-This function decodes a ref.
 
   javascript:location.href = \\='org-protocol://roam-ref?template=r&ref=\\='+ \\
         encodeURIComponent(location.href) + \\='&title=\\=' \\

org-roam.el

@@ -59,7 +59,7 @@
   :link '(url-link :tag "Online Manual" "https://org-roam.readthedocs.io/"))
 
 (defgroup org-roam-faces nil
-  "Faces used by Org-Roam."
+  "Faces used by Org-roam."
   :group 'org-roam
   :group 'faces)
 
@@ -574,7 +574,8 @@ specified via the #+ROAM_ALIAS property."
 ;;;; Org-roam capture
 (defun org-roam--new-file-path (id)
   "The file path for a new Org-roam file, with identifier ID.
-If ABSOLUTE, return an absolute file-path. Else, return a relative file-path."
+If ABSOLUTE, return an absolute file-path. Else, return a
+relative file-path."
   (let ((absolute-file-path (file-truename
                              (expand-file-name
                               (if org-roam-encrypt-files
@@ -587,7 +588,7 @@ If ABSOLUTE, return an absolute file-path. Else, return a relative file-path."
   "The default file name format for org-roam templates.")
 
 (defvar org-roam--capture-header-default "#+TITLE: ${title}\n"
-  "The default file name format for org-roam templates.")
+  "The default capture header for org-roam templates.")
 
 (defvar org-roam--capture-file-path nil
   "The file path for the Org-roam capture. This variable is set
@@ -599,11 +600,17 @@ template. This variable is populated dynamically, and is only
 non-nil during the org-roam capture process.")
 
 (defvar org-roam--capture-context nil
-  "A cons cell containing the context (search term) to get the
+  "A symbol, that reflects the context for obtaining the exact point in a file.
-exact point in a file. This variable is populated dynamically,
+This variable is populated dynamically, and is only active during
-and is only active during an org-roam capture process.
+an org-roam capture process.
 
-E.g. ('title . \"New Title\")")
+The `title' context is used in `org-roam-insert' and
+`org-roam-find-file', where the capture process is triggered upon
+trying to create a new file without that `title'.
+
+The `ref' context is used by `org-roam-protocol', where the
+capture process is triggered upon trying to find or create a new
+note with the given `ref'.")
 
 (defvar org-roam-capture-templates
   '(("d" "default" plain (function org-roam--capture-get-point)
@@ -611,10 +618,30 @@ E.g. ('title . \"New Title\")")
      :file-name "%<%Y%m%d%H%M%S>-${slug}"
      :head "#+TITLE: ${title}\n"
      :unnarrowed t))
-  "Capture templates for org-roam.")
+  "Capture templates for Org-roam. The capture templates are an extension of
+`org-capture-templates', and the documentation there also applies.
+
+`org-capture-templates' are extended in 3 ways:
+
+1. Template expansion capabilities are extended with additional custom syntax.
+   See `org-roam--fill-template' for more details.
+2. The `:file-name' key is added, which expands to the file-name of the note
+   if it creates a new file. This file-name is relative to `org-roam-directory',
+   and is without the file-extension.
+3. The `:head' key is added, which contains the template that is inserted on
+   initial creation (added only once). This is where insertion of any note
+   metadata should go.")
 
 (defun org-roam--fill-template (str &optional info)
-  "Return a file name from template STR."
+  "Expands the template STR, returning the string.
+This is an extension of org-capture's template expansion.
+
+First, it expands ${var} occurences in STR, using the INFO alist.
+If there is a ${var} with no matching var in the alist, the value
+of var is prompted for via completing-read.
+
+Next, it expands the remaining template string using
+`org-capture-fill-template'."
   (-> str
       (s-format (lambda (key)
                   (or (s--aget info key)
@@ -647,7 +674,10 @@ If the search is via title, it is assumed that the file does not
 yet exist, and org-roam will attempt to create new file.
 
 If the search is via ref, it is matched against the Org-roam database.
-If there is no file with that ref, a file with that ref is created."
+If there is no file with that ref, a file with that ref is created.
+
+This function is used solely in Org-roam's capture templates: see
+`org-roam-capture-templates'."
   (pcase org-roam--capture-context
     ('title
      (let ((file-path (org-roam--capture-new-file)))
@@ -726,6 +756,7 @@ If PREFIX, downcase the title before insertion."
 
 (defun org-roam--capture-advance-point ()
   "Advances the point if it is updated.
+
 We need this function because typically org-capture prevents the
 point from being advanced, whereas when a link is inserted, the
 point moves some characters forward. This is added as a hook to
@@ -1115,7 +1146,7 @@ it.
 When called from Lisp, enable `org-roam-mode' if ARG is omitted,
 nil, or positive. If ARG is `toggle', toggle `org-roam-mode'.
 Otherwise, behave as if called interactively."
-  :lighter " Org-Roam"
+  :lighter " Org-roam"
   :keymap  org-roam-mode-map
   :group 'org-roam
   :require 'org-roam