dotfiles/modules/roam.org

#+TITLE: Roam
#+AUTHOR: Christopher James Hayward
#+EMAIL: chris@chrishayward.xyz

#+PROPERTY: header-args:emacs-lisp :tangle roam.el :comments org
#+PROPERTY: header-args            :results silent :eval no-export :comments org

#+OPTIONS: num:nil toc:nil todo:nil tasks:nil tags:nil
#+OPTIONS: skip:nil author:nil email:nil creator:nil timestamp:nil

Plain-text knowledge management system.

* Setup

Make sure ~sqlite~ is available on your system:

#+begin_src shell
RUN apt install sqlite
#+end_src

* Config

Configure ~org-roam~[fn:1], a plain-text knowledge management system for Emacs built on top of ~org-mode~. Here's a quick recap of the main principles:

+ Notes can be arbitrarily referened
+ Contexts created by linking topics and notes

#+begin_src emacs-lisp
(use-package org-roam
  :hook (after-init . org-roam-mode) ;; Lauch roam at startup, big performance cost.
  :custom (org-roam-encrypt-files t) ;; Encrypt all roam captures.
          (org-roam-directory org-directory)
          (org-roam-capture-templates '())
          (org-roam-dailies-capture-templates '()))
#+end_src

** Files

The default behaviour of ~org-roam~[fn:1] when creating a title slug is to replace any non alpha numerical (whitespace) to ~_~. I wanted to change this to use ~_~ and have done so here in my own definition. The only substantial difference from the original definition is the character used.

+ Define a new ~title-to-slug~ function
+ Override ~org-roam-title-to-slug-function~

#+begin_src emacs-lisp
(with-eval-after-load 'org-roam
  (require 'cl-lib)
  (defun dotfiles/title-to-slug (title)
    "Convert TITLE to a filename-suitable slug."
    (cl-flet* ((nonspacing-mark-p (char)
                                  (eq 'Mn (get-char-code-property char 'general-category)))
               (strip-nonspacing-marks (s)
                                       (apply #'string (seq-remove #'nonspacing-mark-p
                                                                   (ucs-normalize-NFD-string s))))
               (cl-replace (title pair)
                           (replace-regexp-in-string (car pair) (cdr pair) title)))
      (let* ((pairs `(("[^[:alnum:][:digit:]]" . "-") ;; Convert anything not alphanumeric.
                      ("--*" . "-")                   ;; Remove sequential dashes.
                      ("^-" . "")                     ;; Remove starting dashes.
                      ("-$" . "")))                   ;; Remove ending dashes.
             (slug (-reduce-from #'cl-replace (strip-nonspacing-marks title) pairs)))
        (downcase slug))))
  (setq org-roam-title-to-slug-function #'dotfiles/title-to-slug))
#+end_src

** Visualizer

Use the ~org-roam-server~[fn:2] web application to visualize the ~org-roam~[fn:1] database. It's available whenever the editor is running at http://localhost:8080.

#+begin_src emacs-lisp
(use-package org-roam-server
  :after org-roam
  :hook (org-roam-mode . org-roam-server-mode))
#+end_src

** Dailies

Use the ~daily~ note feature of ~org-roam~[fn:1] to capture daily notes. Create the default capture template with some preconfigured headers.

#+begin_src emacs-lisp
(with-eval-after-load 'org-roam
  (add-to-list 'org-roam-dailies-capture-templates
    '("d" "Default" entry (function org-roam-capture--get-point)
             "* %?"
             :file-name "docs/daily/%<%Y-%m-%d>"
             :head
"
,#+TITLE: %<%Y-%m-%d>
,#+AUTHOR: Christopher James Hayward

,#+OPTIONS: num:nil toc:nil todo:nil tasks:nil tags:nil
,#+OPTIONS: skip:nil author:nil email:nil creator:nil timestamp:nil
")))
#+end_src

* Templates

Collection of capture templates for various contexts. Here is one for a generic document.

#+begin_src emacs-lisp
(with-eval-after-load 'org-roam
  (add-to-list 'org-roam-capture-templates
    '("d" "Default" entry (function org-roam-capture--get-point)
          "%?"
          :file-name "docs/${slug}"
          :unnarrowed t
          :head 
"
,#+TITLE: ${title}
,#+AUTHOR: Christopher James Hayward
,#+EMAIL: chris@chrishayward.xyz
")))
#+end_src

** Course

Capture template for a new course. Capture with =SPC r c c=.

#+begin_src emacs-lisp
(with-eval-after-load 'org-roam
  (add-to-list 'org-roam-capture-templates
    '("c" "Course" plain (function org-roam-capture--get-point)
          "%?"
          :file-name "docs/courses/${slug}"
          :unnarrowed t
          :head
"
,#+TITLE: ${title}
,#+SUBTITLE:
,#+AUTHOR: Christopher James Hayward
,#+EMAIL: chris@chrishayward.xyz

,#+OPTIONS: num:nil toc:nil todo:nil tasks:nil tags:nil
,#+OPTIONS: skip:nil author:nil email:nil creator:nil timestamp:nil
")))
#+end_src

* Shortcuts

Configure custom keybindings for ~org-roam~[fn:1] behind =SPC r=:

+ Find with =f=
+ Insert with =i=
+ Buffer with =b=
+ Capture with =c=

#+begin_src emacs-lisp
(dotfiles/leader
  "r"  '(:ignore t :which-key "Roam")
  "ri" '(org-roam-insert :which-key "Insert")
  "rf" '(org-roam-find-file :which-key "Find")
  "rc" '(org-roam-capture :which-key "Capture")
  "rb" '(org-roam-buffer-toggle-display :which-key "Buffer"))
#+end_src

Place keybindings for daily notes behind =SPC r d=:

+ Date with =d=
+ Today with =t=
+ Tomorrow with =m=
+ Yesterday with =y=

#+begin_src emacs-lisp
(dotfiles/leader
  "rd" '(:ignore t :which-key "Dailies")
  "rdd" '(org-roam-dailies-find-date :which-key "Date")
  "rdt" '(org-roam-dailies-find-today :which-key "Today")
  "rdm" '(org-roam-dailies-find-tomorrow :which-key "Tomorrow")
  "rdy" '(org-roam-dailies-find-yesterday :which-key "Yesterday"))
#+end_src

* Footnotes

[fn:1] https://github.com/org-roam/org-roam

[fn:2] https://github.com/org-roam/org-roam-server