(docs): overhaul documentation (#76)

Updated for latest Org-roam, and add all relevant information into the new documentation site.

doc/configuration.md

@@ -98,8 +98,8 @@ Org-roam commands. Setting it to `nil` will disable this behaviour.
 ## Org-roam Graph Viewer
 
 Org-roam generates an SVG image using
-[Graphviz](https://graphviz.org/). For more information about this
-functionality, see the [Usage](TODO) page.
+[Graphviz](https://graphviz.org/). To setup graph navigation, see the
+[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:

doc/ecosystem.md

@@ -1,10 +1,9 @@
-## Ecosystem
-
 A number of packages work well combined with Org-Roam:
 
-### Deft
-[Deft](https://jblevins.org/projects/deft/) provides a nice
-interface for browsing and filtering org-roam notes.
+## Deft
+
+[Deft][deft] provides a nice interface for browsing and filtering
+org-roam notes.
 
 ```
 (use-package deft
@@ -19,7 +18,12 @@ interface for browsing and filtering org-roam notes.
   (deft-use-filename-as-title t))
 ```
 
-### Org-journal
+The Deft interface can slow down quickly when the number of files get
+huge. [Notdeft][notdeft] is a fork of Deft that uses an external
+search engine and indexer.
+
+## Org-journal
+
 [Org-journal](https://github.com/bastibe/org-journal) is a more
 powerful alternative to the simple function `org-roam-today`. It
 provides better journaling capabilities, and a nice calendar interface
@@ -35,3 +39,59 @@ to see all dated entries.
   (org-journal-dir "/path/to/org-roam-files/")
   (org-journal-date-format "%A, %d %B %Y"))
 ```
+
+## Note-taking Add-ons
+
+These are some plugins that make note-taking in Org-mode more
+enjoyable.
+
+### Org-download
+
+[Org-download][org-download] lets you screenshot and yank images from
+the web into your notes:
+
+![org-download](images/org-download.gif)
+
+```emacs-lisp
+(use-package org-download
+  :after org
+  :bind
+  (:map org-mode-map
+        (("s-Y" . org-download-screenshot)
+         ("s-y" . org-download-yank))))
+```
+
+### mathpix.el
+
+[mathpix.el][mathpix-el] uses [Mathpix's](https://mathpix.com/) API to convert clips into
+latex equations:
+
+![mathpix](images/mathpix.gif)
+
+```emacs-lisp
+(use-package mathpix.el
+  :straight (:host github :repo "jethrokuan/mathpix.el")
+  :custom ((mathpix-app-id "app-id")
+           (mathpix-app-key "app-key"))
+  :bind
+  ("C-x m" . mathpix-screenshot))
+```
+
+### Org-noter / Interleave
+
+[Org-noter][org-noter] and [Interleave][interleave] are both projects
+that allow synchronised annotation of documents (PDF, EPUB etc.)
+within Org-mode.
+
+### Org-ref
+
+[Org-ref][org-ref] does citation and bibliography management in
+Org-mode, and a great tool for scientific notes.
+
+[deft]: https://jblevins.org/projects/deft/
+[notdeft]: https://github.com/hasu/notdeft
+[org-download]: https://github.com/abo-abo/org-download
+[mathpix-el]: https://github.com/jethrokuan/mathpix.el
+[org-noter]: https://github.com/weirdNox/org-noter
+[interleave]: https://github.com/rudolfochrist/interleave
+[org-ref]: https://github.com/jkitchin/org-ref

doc/graph_setup.md

@@ -0,0 +1,39 @@
+The setup is similar to that of org-protocol. Here `roam://` links are
+defined, and need to be associated with an application. 
+
+The gist of the setup is setting up a Bash script to trim off the
+`roam://` prefix from the link, causing the desktop application to
+call `emacsclient path/to/org-roam-file.org`.
+
+## Setting Up for Linux
+
+Create a desktop application. I place mine in
+`~/.local/share/applications/roam.desktop`:
+
+```
+[Desktop Entry]
+Name=Org-Roam Client
+Exec=/home/jethro/.local/bin/launch_emacs %u
+Icon=emacs-icon
+Type=Application
+Terminal=false
+MimeType=x-scheme-handler/roam
+```
+
+Note the `Exec` key is set to a bash script poorly named
+`launch_emacs`. You can set it to whatever you want.
+
+Create the corresponding bash script, and make it executable. Here's
+how it looks like:
+
+```bash
+#!/usr/bin/env bash
+emacsclient "${1#*:}"
+```
+
+Finally, associate `roam://` links with the desktop application by
+running in your shell:
+
+```bash
+xdg-mime default roam.desktop x-scheme-handler/roam
+```

doc/installation.md

@@ -6,12 +6,15 @@ The recommended method is using [use-package][use-package] and
 ```
 (use-package org-roam
       :after org
-      :hook (org-mode . org-roam-mode)
-      :straight (:host github :repo "jethrokuan/org-roam")
+      :hook 
+      ((org-mode . org-roam-mode)
+       (after-init . org-roam--build-cache-async) ;; optional!
+       )
+      :straight (:host github :repo "jethrokuan/org-roam" :branch "develop")
       :custom
       (org-roam-directory "/path/to/org-files/")
       :bind
-      ("C-c n l" . org-roam)      
+      ("C-c n l" . org-roam)
       ("C-c n t" . org-roam-today)
       ("C-c n f" . org-roam-find-file)
       ("C-c n i" . org-roam-insert)
@@ -25,6 +28,26 @@ directory and add it to your load path:
 git clone https://github.com/jethrokuan/org-roam/ ~/.emacs.d/elisp/org-roam
 ```
 
+```
+(use-package org-roam
+      :after org
+      :load-path "elisp/"
+      :hook 
+      ((org-mode . org-roam-mode)
+       (after-init . org-roam--build-cache-async) ;; optional!
+       )
+      :custom
+      (org-roam-directory "/path/to/org-files/")
+      :bind
+      ("C-c n l" . org-roam)
+      ("C-c n t" . org-roam-today)
+      ("C-c n f" . org-roam-find-file)
+      ("C-c n i" . org-roam-insert)
+      ("C-c n g" . org-roam-show-graph))
+```
+
+Or without use-package:
+
 ```
 (add-to-list 'load-path "./elisp")
 (require 'org-roam)

doc/notetaking_workflow.md

@@ -0,0 +1,20 @@
+## Recommended Books
+- [How to Take Smart Notes][1]
+
+## Articles
+- [How to Take Smart Notes in Org-mode - Jethro Kuan][7]
+- [The Zettelkasten Method - LessWrong 2.0][3]
+- [Building a second brain in Roam][4]
+- [Roam: Why I Love It and How I Use It][5]
+- [Adam Keesling's Twitter Thread][6]
+
+## What to Do With Your Notes
+- [How to Use Roam to Outline a New Article in Under 20 Minutes][2]
+
+[1]: https://www.goodreads.com/book/show/34507927-how-to-take-smart-notes?ac=1&from_search=true&qid=6L8iEE1FIA&rank=1
+[2]: https://www.youtube.com/watch?v=RvWic15iXjk
+[3]: https://www.lesswrong.com/posts/NfdHG6oHBJ8Qxc26s/the-zettelkasten-method-1
+[4]: https://reddit.com/r/RoamResearch/comments/eho7de/building_a_second_brain_in_roamand_why_you_might
+[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/

doc/tour.md

@@ -1,20 +1,69 @@
-### A Tour of Org-Roam
+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
+make your note-taking better -- it's changing the note-taking workflow
+that does.
 
-All of this starts from the note. A note is just a simple `.org` file
-in the directory. Any org file in the directory is considered part of
-the org-roam ecosystem. Notes are quickly linked together (and created
-if necessary) using `org-roam-insert`.
+To understand more the methods and madness, the [Note-Taking
+Workflow][appendix:ntw] page contains a page of useful references.
+I've also written [a post][jethro-blog-post] about how I use Org-roam.
 
-![org-roam-insert](images/org-roam-insert.gif)
+Without further ado, let's begin!
 
-Org-roam tracks all of these file links, and builds a cache
-asynchronously in the background. This cache is used to populate the
-backlinks buffer, which shows files that link to the current file, as
-well as some preview contents:
+## Building the Cache
+
+Assuming you've set `org-roam-directory` appropriately, running `M-x
+org-roam--build-cache-async` should build up the caches that will
+allow you to begin using Org-roam. I do this on startup:
+
+```emacs-lisp
+(add-hook 'after-init-hook 'org-roam--build-cache-async)
+```
+
+## Finding a Note
+
+`org-roam-find-file` shows you the list of notes you currently have in
+Org-roam. Selecting the title will bring you to the corresponding
+note. Entering a title of a note that does not yet exist 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
+links to existing (or new) Org-roam notes with `org-roam-insert`.
+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,
+where you want them the notes to resurface!
+
+## The Org-roam Buffer
+
+All of Org-roam's operations are designed such that the built cache is
+a consistent view of the inter-connectivity between your notes. The
+Org-roam buffer shows backlinks: i.e. the files that link to the
+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)
 
-These file links also form a graph. The generated graph is navigable
-in Emacs.
+## Exporting the Graph
+
+It's also possible to export the links as a graph, using graphviz. The
+generated graph is navigable in Emacs, but requires some additional
+setup, which I describe in the [Graph Appendix][appendix:graph-setup]
+page.
 
 ![org-roam-graph](images/org-roam-graph.gif)
+
+[zettelkasten]: https://zettelkasten.de/
+[appendix:ntw]: notetaking_workflow.md
+[appendix:graph-setup]: graph_setup.md
+[roam]: https://www.roamresearch.com/
+[jethro-blog-post]: https://blog.jethro.dev/posts/how_to_take_smart_notes_org/

mkdocs.yml

@@ -10,6 +10,8 @@ nav:
 - Configuration: configuration.md
 - Ecosystem: ecosystem.md
 - Similar Packages: comparison.md
+- "Appendix: Note-taking Workflow": notetaking_workflow.md
+- "Appendix: Graph Setup": graph_setup.md
 markdown_extensions:
   - admonition
   - pymdownx.betterem:

shell.nix

@@ -5,6 +5,5 @@ pkgs.mkShell {
   name = "docs";
   buildInput = with pkgs; [
     mkdocs
-    python3Packages.alabaster
   ];
 }