(release): Org-roam v1.2.2 (#1168 )

(internal): remove compat functions (#1167 )
* remove org-roam-link-make-string * remove org-roam-link-store-props and org-roam-link-decode
2025-08-01 12:17:21 -05:00 · 2020-10-06 03:02:41 +08:00 · 2020-10-06 02:45:59 +08:00 · 2020-10-05 23:24:32 +08:00 · 2020-10-05 18:56:28 +08:00 · 2020-10-05 16:57:54 +08:00
28 changed files with 3659 additions and 1216 deletions
--- a/.dir-locals.el
+++ b/.dir-locals.el
@ -3,4 +3,4 @@

 ((emacs-lisp-mode
  (eval . (require 'org-roam-dev))
-  (sentence-end-double-space . nil)))
+  (eval . (org-roam-dev-mode))))
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@ -1,8 +0,0 @@
-version: 2
-mkdocs:
- configuration: mkdocs.yml
-formats: all
-python:
-  version: 3.7
-  install:
-    - requirements: doc/requirements.txt
--- a/BACKERS.md
+++ b/BACKERS.md
@ -3,3 +3,6 @@
 Many thanks to the following backers, your contributions are greatly appreciated!

 - Nathan Tran
+- Burke Libbey
+- forkrul
+- Andreas Stuhlmüller
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -1,5 +1,76 @@
 # Changelog

+## 1.2.2 (06-10-2020)
+
+In this release we support fuzzy links of the form `[[roam:Title]]`, `[[roam:*Headline]]` and `[[roam:Title*Headline]]`. Completion for these fuzzy links is supported via `completion-at-point`.
+
+Org-roam now does not resolve symlinks. This significantly speeds up cache builds, but may result in some workflows breaking. In particular, Org-roam now cannot figure out if two distinct file paths in the Org-roam directory are the same file, and both files will be processed as if they were different files. This error seems to be unavoidable now that symlinks are not resolved, but this workflow is rare and should not affect most users.
+
+This change requires you to set `org-roam-directory` to the resolved path of a folder. That is:
+
+```elisp
+(setq org-roam-directory (file-truename "/path/to/directory/"))
+```
+
+### Breaking Changes
+
+- [#1164](https://github.com/org-roam/org-roam/pull/1164) Org-roam now stores the database in the user's Emacs directory by default
+- [#910](https://github.com/org-roam/org-roam/pull/910) Deprecate `company-org-roam`, using `completion-at-point` instead. To use this with company, add the `company-capf` backend instead.
+- [#1109](https://github.com/org-roam/org-roam/pull/1109) Org-roam now does not resolve symlinks.
+
+### Features
+
+- [#1163](https://github.com/org-roam/org-roam/pull/1163) Support file-level IDs introduced in Org 9.4
+- [#1093](https://github.com/org-roam/org-roam/pull/1093) Add `vanilla` org-roam-tag-source to extract buffer Org tags
+- [#1079](https://github.com/org-roam/org-roam/pull/1079) Add `org-roam-tag-face` to customize appearance of tags in interactive commands
+- [#1073](https://github.com/org-roam/org-roam/pull/1073) Rename file on title change, when `org-roam-rename-file-on-title-change` is non-nil.
+- [#1071](https://github.com/org-roam/org-roam/pull/1071) Update link descriptions on title changes, and clean-up rename file advice
+- [#1061](https://github.com/org-roam/org-roam/pull/1061) Speed up the extraction of file properties, headlines, and titles
+- [#1046](https://github.com/org-roam/org-roam/pull/1046) New user option to exclude files from Org-roam
+- [#1032](https://github.com/org-roam/org-roam/pull/1032) File changes are now propagated to the database on idle timer. This prevents large wait times during file saves.
+- [#974](https://github.com/org-roam/org-roam/pull/974) Protect region targeted by `org-roam-insert`
+- [#994](https://github.com/org-roam/org-roam/pull/994) Simplify org-roam-store-link
+- [#1062](https://github.com/org-roam/org-roam/pull/1062) Variable `org-roam-completions-everywhere` allows for completions everywhere from word at point
+- [#910](https://github.com/org-roam/org-roam/pull/910), [#1105](https://github.com/org-roam/org-roam/pull/1105) Support fuzzy links of the form [[roam:Title]], [[roam:*Headline]] and [[roam:Title*Headline]]
+
+### Bugfixes
+
+- [#1057](https://github.com/org-roam/org-roam/pull/1057) Improve performance of database builds by preventing generation of LaTeX and image previews.
+- [#1103](https://github.com/org-roam/org-roam/pull/1103) Fix long build-times for Windows on files with URL links
+
+## 1.2.1 (27-07-2020)
+
+This release consisted of a big deal of refactoring and bug fixes. Notably, we fixed several catastrophic failures on db builds with bad setups (#854), and modularized tag and title extractions.
+
+We also added some new features that had been a long time coming:
+
+1. We made the backlinks more outline-friendly by also showing the outline hierarchy for a backlink (#863)
+2. We now support nested captures, which is crucial for `org-roam-protocol` (#966)
+
+### Breaking Changes
+
+- [#908](https://github.com/org-roam/org-roam/pull/908) Normalized titles in database. May break external packages that rely on unnormalized titles.
+
+### Features
+
+- [#814](https://github.com/org-roam/org-roam/pull/814) Implement `org-roam-insert-immediate`
+- [#833](https://github.com/org-roam/org-roam/pull/833) Add customization of file titles with `org-roam-title-to-slug-function`.
+- [#839](https://github.com/org-roam/org-roam/pull/839) Return selected file from `org-roam-insert`
+- [#847](https://github.com/org-roam/org-roam/pull/847) Add GC threshold `org-roam-db-gc-threshold` to temporarily change the threshold on expensive operations.
+- [#847](https://github.com/org-roam/org-roam/pull/847) Use sqlite3 transactions instead of storing the values to be inserted.
+- [#851](https://github.com/org-roam/org-roam/pull/851) Add `'first-directory'` option for `org-roam-tag-sources`
+- [#863](https://github.com/org-roam/org-roam/pull/863) Display outline hierarchy in backlinks buffer
+- [#898](https://github.com/org-roam/org-roam/pull/898) Add `org-roam-random-note` to browse a random note.
+- [#900](https://github.com/org-roam/org-roam/pull/900) Support and index all valid org links
+- [#966](https://github.com/org-roam/org-roam/pull/966) Enable nested captures
+
+### Bugfixes
+
+- [#854](https://github.com/org-roam/org-roam/pull/854) Warn instead of fail when duplicate refs and IDs exist.
+- [#857](https://github.com/org-roam/org-roam/pull/857) Fix tag extraction for symlinked directories.
+- [#894](https://github.com/org-roam/org-roam/pull/894) Perform link fixes on all Org-roam files
+- [#952](https://github.com/org-roam/org-roam/pull/952) Cache `${foo}` template variables so they do not need to be re-entered twice
+
 ## 1.2.0 (12-06-2020)

 In this release, we improved the linking process by achieving feature parity between links to files and links to headlines. Before, we used the `file:foo::*bar` format to link to the headline `bar` in file `foo`, but this was prone to breakage upon renaming the file or modifying the headline. This is not the case anymore. Now, we use `org-id` to create IDs for those headlines, which are then stored in our database to compute the relationships and jump around. Note that this will work even if you’re not using `org-id` in your global configuration for Org-mode.
@ -23,6 +94,7 @@ We also add `org-roam-unlinked-references`, which naively finds text that could
 - [#679](https://github.com/org-roam/org-roam/pull/679), [#683](https://github.com/org-roam/org-roam/pull/683) Building of the graph now happens in a separate process

 ### Bugfixes
+
 - [#714](https://github.com/org-roam/org-roam/pull/714) No longer print citelinks in backlinks buffer if there is no `ROAM_KEY` property or `org-ref` is not installed
 - [#759](https://github.com/org-roam/org-roam/pull/759), [#760](https://github.com/org-roam/org-roam/pull/760) Tags are only added to the tags table if there are actually tags present
 - [#700](https://github.com/org-roam/org-roam/pull/700), [#733](https://github.com/org-roam/org-roam/pull/733) Allow symlinks within the `org-roam` directory
@ -32,7 +104,7 @@ We also add `org-roam-unlinked-references`, which naively finds text that could
 In this release, we added two new features:

 1. `org-roam-doctor`: a linting system that helps you discover possible problems with your Org-roam files. This is in the spirit of keeping notes in top quality.
-2. A tagging system: one can now use sub-directories, and the `#+roam_tags` key add additional meta data to notes. For more information, see [here](https://org-roam.github.io/org-roam/manual/Tags.html#Tags).
+2. A tagging system: one can now use sub-directories, and the `#+roam_tags` key add additional meta data to notes. For more information, see [here](https://www.orgroam.com/manual/Tags.html#Tags).

 As usual, this release comes with a multitude of bug-fixes and refactorings.

--- a/README.md
+++ b/README.md
@ -4,6 +4,11 @@

 ## Synopsis

+> **NOTE:** Org-roam builds upon Emacs and Org-mode, both of which are intricate
+> tools that require time investment for mastery. This makes Org-roam less
+> friendly for beginners, but extremely powerful for those familiar with the
+> ecosystem, or willing to invest effort in it.
+
 Org-roam is a [Roam][roamresearch] replica built on top of the
 all-powerful [Org-mode][org].

@ -50,6 +55,7 @@ Here's a sample configuration with using `use-package`:

 ```emacs-lisp
 (use-package org-roam
+      :ensure t
      :hook
      (after-init . org-roam-mode)
      :custom
@ -57,9 +63,10 @@ Here's a sample configuration with using `use-package`:
      :bind (:map org-roam-mode-map
              (("C-c n l" . org-roam)
               ("C-c n f" . org-roam-find-file)
-               ("C-c n g" . org-roam-show-graph))
+               ("C-c n g" . org-roam-graph))
              :map org-mode-map
-              (("C-c n i" . org-roam-insert))))
+              (("C-c n i" . org-roam-insert))
+              (("C-c n I" . org-roam-insert-immediate))))
 ```

 `org-roam-graph` by default expects to find the `dot` executable
@ -72,6 +79,25 @@ For more detailed installation and configuration instructions (including for
 Doom and Spacemacs users), please see [the
 documentation][docs].

+## Frequently-asked Questions
+
+Q: How do I create a note whose title already matches one of the candidates (e.g. creating `bar` when `barricade` already exists)?
+
+A: With `ivy`, you need to press `C-M-j` to use the current input instead of the nearest candidate. (Source: [`ivy`’s
+  FAQ](https://github.com/abo-abo/swiper#frequently-asked-questions))
+
+## Getting Help
+
+Before creating a new topic/issue, please be mindful of our time and ensure
+that it has not already been addressed on
+[GitHub][issues] or on
+[Discourse][discourse].
+
+- If you are new to Emacs and have problem setting up Org-roam, please ask your question on [Slack, channel #how-do-i][slack].
+- For quick questions, please ask them on [Slack, channel #troubleshooting][slack].
+- If something is not working as it should, or if you would like to suggest a new feature, please [create a new issue][issues].
+- If you have questions about your workflow with the slip-box method, please find a relevant topic on [Discourse][discourse], or create a new one.
+
 ## Knowledge Bases using Org-roam

 - [Jethro Kuan](https://braindump.jethro.dev/)
@ -95,6 +121,7 @@ General Public License, Version 3
 [roamresearch]: https://www.roamresearch.com/
 [org]: https://orgmode.org/
 [badge-license]: https://img.shields.io/badge/license-GPL_3-green.svg
-[docs]: https://org-roam.github.io/org-roam/manual/
+[docs]: https://www.orgroam.com/manual/
 [discourse]: https://org-roam.discourse.group/
 [slack]: https://join.slack.com/t/orgroam/shared_invite/zt-deoqamys-043YQ~s5Tay3iJ5QRI~Lxg
+[issues]: https://github.com/org-roam/org-roam/issues
--- a/doc/AUTHORS.md
+++ b/doc/AUTHORS.md
@ -34,4 +34,4 @@ Contributors
 - Rafael Accácio Nogueira <raccacio@poli.ufrj.br>
 - Roland Coeurjoly <rolandcoeurjoly@gmail.com>
 - Sayan <dit7ya@users.noreply.github.com>
- Tim Quelch <tim@quelch.name>
+- Tim Quelch <tim@tquelch.com>
--- a/doc/img/logo.svg
+++ b/doc/img/logo.svg
--- a/doc/index.html
+++ b/doc/index.html
@ -93,7 +93,7 @@
        You can find us on Discourse and Slack.
        
        <ul>
-            <li>Read our documentation within Emacs, or on the <a href="https://org-roam.github.io/org-roam/manual/">Online Manual</a></li>
+            <li>Read our documentation within Emacs, or on the <a href="https://www.orgroam.com/manual/">Online Manual</a></li>
            <li>Participate in our forum discussions on <a href="https://org-roam.discourse.group">Discourse</a></li>
            <li>Chat with us on <a href="https://join.slack.com/t/orgroam/shared_invite/zt-deoqamys-043YQ~s5Tay3iJ5QRI~Lxg">Slack</a></li>
          </ul>
--- a/doc/org-roam.org
+++ b/doc/org-roam.org
--- a/doc/org-roam.texi
+++ b/doc/org-roam.texi
--- a/makem.sh
+++ b/makem.sh
@ -591,6 +591,12 @@ function debug {
        }
    fi
 }
+
+function error_nonblocking {
+    echo_color red "ERROR ($(ts)): $@" >&2
+    ((errors_nonblocking++))
+}
+
 function error {
    echo_color red "ERROR ($(ts)): $@" >&2
    ((errors++))
@ -763,7 +769,7 @@ function lint-package {
        --funcall package-lint-batch-and-exit \
        "${files_project_feature[@]}" \
        && success "Linting package finished without errors." \
-            || error "Linting package failed."
+            || error_nonblocking "Linting package failed."
 }

 function lint-regexps {
@ -832,6 +838,7 @@ test_files_regexp='^((tests?|t)/)|-test.el$|^test-'

 emacs_command=("emacs")
 errors=0
+errors_nonblocking=0
 verbose=0
 compile=true
 arg_batch="--batch"
@ -1072,9 +1079,9 @@ done

 if [[ $errors -gt 0 ]]
 then
-    log_color red "Finished with $errors errors."
+    log_color red "Finished with $errors errors and $errors_nonblocking non-blocking errors."
 else
-    success "Finished without errors."
+    success "Finished with $errors errors and $errors_nonblocking non-blocking errors."
 fi

 exit $errors
--- a/org-roam-buffer.el
+++ b/org-roam-buffer.el
@ -5,8 +5,8 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 1.2.0
-;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.0"))
+;; Version: 1.2.2
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.2"))

 ;; This file is NOT part of GNU Emacs.

@ -34,6 +34,8 @@
 (require 'cl-lib)
 (require 'dash)
 (require 's)
+(require 'f)
+(require 'ol)

 (defvar org-roam-directory)
 (defvar org-link-frame-setup)
@ -42,13 +44,18 @@
 (defvar org-roam-last-window)
 (defvar org-ref-cite-types) ;; in org-ref-core.el
 (defvar org-roam-mode)
+(defvar org-roam--org-link-bracket-typed-re)

 (declare-function org-roam-db--ensure-built   "org-roam-db")
 (declare-function org-roam--extract-ref       "org-roam")
+(declare-function org-roam--extract-titles    "org-roam")
 (declare-function org-roam--get-title-or-slug "org-roam")
 (declare-function org-roam--get-backlinks     "org-roam")
 (declare-function org-roam-backlinks-mode     "org-roam")
 (declare-function org-roam-mode               "org-roam")
+(declare-function org-roam--find-file         "org-roam")
+(declare-function org-roam-format-link        "org-roam")
+(declare-function org-roam-link-get-path      "org-roam-link")

 (defcustom org-roam-buffer-position 'right
  "Position of `org-roam' buffer.
@ -83,7 +90,7 @@ Has an effect if and only if `org-roam-buffer-position' is `top' or `bottom'."

 (defcustom org-roam-buffer-prepare-hook '(org-roam-buffer--insert-title
                                          org-roam-buffer--insert-backlinks
-                                          org-roam-buffer--insert-citelinks)
+                                          org-roam-buffer--insert-ref-links)
  "Hook run in the `org-roam-buffer' before it is displayed."
  :type 'hook
  :group 'org-roam)
@ -97,12 +104,21 @@ For example: (setq org-roam-buffer-window-parameters '((no-other-window . t)))"
 (defvar org-roam-buffer--current nil
  "Currently displayed file in `org-roam' buffer.")

+(defun org-roam-buffer--find-file (file)
+  "Open FILE in the window `org-roam' was called from."
+  (setq file (expand-file-name file))
+  (if (and org-roam-last-window (window-valid-p org-roam-last-window))
+      (progn (with-selected-window org-roam-last-window
+               (org-roam--find-file file))
+             (select-window org-roam-last-window))
+    (org-roam--find-file file)))
+
 (defun org-roam-buffer--insert-title ()
  "Insert the org-roam-buffer title."
  (insert (propertize (org-roam--get-title-or-slug
                       (buffer-file-name org-roam-buffer--current))
-                       'font-lock-face
-                       'org-document-title)))
+                      'font-lock-face
+                      'org-document-title)))

 (defun org-roam-buffer--pluralize (string number)
  "Conditionally pluralize STRING if NUMBER is above 1."
@ -114,39 +130,55 @@ For example: (setq org-roam-buffer-window-parameters '((no-other-window . t)))"
                                   ,wrong-type))))))
    (concat string (when (> l 1) "s"))))

-(defun org-roam-buffer--insert-citelinks ()
-  "Insert citation backlinks for the current buffer."
-  (when-let ((org-ref-p (require 'org-ref nil t)) ;; Ensure that org-ref is present
-             (ref (cdr (with-temp-buffer
-                        (insert-buffer-substring org-roam-buffer--current)
-                        (org-roam--extract-ref)))))
-    (if-let* ((key-backlinks (org-roam--get-backlinks ref))
+(defun org-roam-buffer-expand-links (content orig-path)
+  "Crawl CONTENT for relative links and corrects them to be correctly displayed.
+ORIG-PATH is the path where the CONTENT originated."
+  (with-temp-buffer
+    (insert content)
+    (goto-char (point-min))
+    (let (link link-type)
+      (while (re-search-forward org-roam--org-link-bracket-typed-re (point-max) t)
+        (setq link-type (match-string 1)
+              link (match-string 2))
+        (when (and (string-equal link-type "file")
+                   (f-relative-p link))
+          (replace-match (org-roam-link-get-path (expand-file-name link (file-name-directory orig-path)))
+                         nil t nil 2))))
+    (buffer-string)))
+
+(defun org-roam-buffer--insert-ref-links ()
+  "Insert ref backlinks for the current buffer."
+  (when-let ((path (cdr (with-temp-buffer
+                          (insert-buffer-substring org-roam-buffer--current)
+                          (org-roam--extract-ref)))))
+    (if-let* ((key-backlinks (org-roam--get-backlinks path))
              (grouped-backlinks (--group-by (nth 0 it) key-backlinks)))
        (progn
          (insert (let ((l (length key-backlinks)))
                    (format "\n\n* %d %s\n"
-                            l (org-roam-buffer--pluralize "Cite backlink" l))))
+                            l (org-roam-buffer--pluralize "Ref Backlink" l))))
          (dolist (group grouped-backlinks)
            (let ((file-from (car group))
                  (bls (cdr group)))
-              (insert (format "** [[file:%s][%s]]\n"
-                              file-from
-                              (org-roam--get-title-or-slug file-from)))
+              (insert (format "** %s\n"
+                              (org-roam-format-link file-from
+                                                     (org-roam--get-title-or-slug file-from)
+                                                     "file")))
              (dolist (backlink bls)
                (pcase-let ((`(,file-from _ ,props) backlink))
-                  (insert (propertize
-                           (s-trim (s-replace "\n" " "
-                                              (plist-get props :content)))
+                  (insert (propertize (org-roam-buffer-expand-links (plist-get props :content) file-from)
                           'help-echo "mouse-1: visit backlinked note"
                           'file-from file-from
                           'file-from-point (plist-get props :point)))
                  (insert "\n\n"))))))
-      (insert "\n\n* No cite backlinks!"))))
+      (insert "\n\n* No ref backlinks!"))))

 (defun org-roam-buffer--insert-backlinks ()
  "Insert the org-roam-buffer backlinks string for the current buffer."
  (if-let* ((file-path (buffer-file-name org-roam-buffer--current))
-            (backlinks (org-roam--get-backlinks file-path))
+            (titles (with-current-buffer org-roam-buffer--current
+                      (org-roam--extract-titles)))
+            (backlinks (org-roam--get-backlinks (push file-path titles)))
            (grouped-backlinks (--group-by (nth 0 it) backlinks)))
      (progn
        (insert (let ((l (length backlinks)))
@ -154,19 +186,32 @@ For example: (setq org-roam-buffer-window-parameters '((no-other-window . t)))"
                             l (org-roam-buffer--pluralize "Backlink" l))))
        (dolist (group grouped-backlinks)
          (let ((file-from (car group))
-                (bls (cdr group)))
-            (insert (format "** [[file:%s][%s]]\n"
-                            file-from
-                            (org-roam--get-title-or-slug file-from)))
-            (dolist (backlink bls)
-              (pcase-let ((`(,file-from _ ,props) backlink))
-                (insert (propertize
-                         (s-trim (s-replace "\n" " "
-                                            (plist-get props :content)))
-                         'help-echo "mouse-1: visit backlinked note"
-                         'file-from file-from
-                         'file-from-point (plist-get props :point)))
-                (insert "\n\n"))))))
+                (bls (mapcar (lambda (row)
+                                 (nth 2 row)) (cdr group))))
+            (insert (format "** %s\n"
+                            (org-roam-format-link file-from
+                                                   (org-roam--get-title-or-slug file-from)
+                                                   "file")))
+            ;; Sort backlinks according to time of occurrence in buffer
+            (setq bls (seq-sort-by (lambda (bl)
+                                     (plist-get bl :point))
+                                   #'<
+                                   bls))
+            (dolist (props bls)
+              (insert "*** "
+                      (if-let ((outline (plist-get props :outline)))
+                          (-> outline
+                              (string-join " > ")
+                              (org-roam-buffer-expand-links file-from))
+                        "Top")
+                      "\n"
+                      (propertize
+                       (s-trim (s-replace "\n" " "
+                                          (org-roam-buffer-expand-links (plist-get props :content) file-from)))
+                       'help-echo "mouse-1: visit backlinked note"
+                       'file-from file-from
+                       'file-from-point (plist-get props :point))
+                      "\n\n")))))
    (insert "\n\n* No backlinks!")))

 (defun org-roam-buffer-update ()
@ -205,7 +250,7 @@ This needs to be quick or infrequent, because this is run at
    (when (and (or redisplay
                   (not (eq org-roam-buffer--current buffer)))
               (eq 'visible (org-roam-buffer--visibility))
-               (buffer-local-value 'buffer-file-truename buffer))
+               (buffer-file-name buffer))
      (setq org-roam-buffer--current buffer)
      (org-roam-buffer-update))))

@ -266,14 +311,25 @@ Valid states are 'visible, 'exists and 'none."
         (org-roam-buffer--set-height
          (round (* (frame-height) org-roam-buffer-height))))))))

-(defun org-roam-buffer-toggle-display ()
-  "Toggle display of the `org-roam-buffer'."
+(defun org-roam-buffer-activate ()
+  "Activate display of the `org-roam-buffer'."
  (interactive)
  (unless org-roam-mode (org-roam-mode))
  (setq org-roam-last-window (get-buffer-window))
+  (org-roam-buffer--get-create))
+
+(defun org-roam-buffer-deactivate ()
+  "Deactivate display of the `org-roam-buffer'."
+  (interactive)
+  (setq org-roam-last-window (get-buffer-window))
+  (delete-window (get-buffer-window org-roam-buffer)))
+
+(defun org-roam-buffer-toggle-display ()
+  "Toggle display of the `org-roam-buffer'."
+  (interactive)
  (pcase (org-roam-buffer--visibility)
-    ('visible (delete-window (get-buffer-window org-roam-buffer)))
-    ((or 'exists 'none) (org-roam-buffer--get-create))))
+    ('visible (org-roam-buffer-deactivate))
+    ((or 'exists 'none) (org-roam-buffer-activate))))

 (provide 'org-roam-buffer)

--- a/org-roam-capture.el
+++ b/org-roam-capture.el
@ -5,8 +5,8 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 1.2.0
-;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.0"))
+;; Version: 1.2.2
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.2"))

 ;; This file is NOT part of GNU Emacs.

@ -31,6 +31,7 @@
 ;;; Code:
 ;;;; Library Requires
 (require 'org-capture)
+(require 'org-roam-macs)
 (require 'dash)
 (require 's)
 (require 'cl-lib)
@ -39,20 +40,15 @@
 (defvar org-roam-encrypt-files)
 (defvar org-roam-directory)
 (defvar org-roam-mode)
+(defvar org-roam-title-to-slug-function)
 (declare-function  org-roam--get-title-path-completions "org-roam")
 (declare-function  org-roam--get-ref-path-completions   "org-roam")
 (declare-function  org-roam--file-path-from-id          "org-roam")
-(declare-function  org-roam--format-link                "org-roam")
-(declare-function  org-roam--title-to-slug              "org-roam")
+(declare-function  org-roam--find-file                  "org-roam")
+(declare-function  org-roam-format-link                "org-roam")
 (declare-function  org-roam-mode                        "org-roam")
 (declare-function  org-roam-completion--completing-read "org-roam-completion")

-(defvar org-roam-capture--file-name-default "%<%Y%m%d%H%M%S>"
-  "The default file name format for Org-roam templates.")
-
-(defvar org-roam-capture--header-default "#+title: ${title}\n"
-  "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 during the Org-roam capture process.")
@ -81,68 +77,287 @@ note with the given `ref'.")
 (defconst org-roam-capture--template-keywords '(:file-name :head)
  "Keywords used in `org-roam-capture-templates' specific to Org-roam.")

-(defvar org-roam-capture-templates
+(defcustom org-roam-capture-templates
  '(("d" "default" plain (function org-roam-capture--get-point)
     "%?"
     :file-name "%<%Y%m%d%H%M%S>-${slug}"
     :head "#+title: ${title}\n"
     :unnarrowed t))
  "Capture templates for Org-roam.
-The capture templates are an extension of
-`org-capture-templates', and the documentation there also
-applies.
+The Org-roam capture-templates  builds on the default behaviours of
+`org-capture-templates' by expanding them in 3 areas:

-`org-capture-templates' are extended in 3 ways:
+1. Template-expansion capabilities are extended with additional
+   custom syntax. See `org-roam-capture--fill-template' for more
+   details.

-1. Template expansion capabilities are extended with additional custom syntax.
-   See `org-roam-capture--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.
+2. The `:file-name' key is added, which defines the naming format
+   to use when creating new notes. 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.")
+   inserted upon the creation of a new file. This is where you
+   your note metadata should go.

-(defvar org-roam-capture-ref-templates
+Each template should have the following structure:
+
+\(KEY DESCRIPTION `plain' `(function org-roam-capture--get-point)'
+  TEMPLATE
+  `:file-name' FILENAME-FORMAT
+  `:head' HEADER-FORMAT
+  `:unnarrowed t'
+  OPTIONS-PLIST)
+
+The elements of a template-entry and their placement are the same
+as in `org-capture-templates', except that the entry type must
+always be the symbol `plain', and that the target must always be
+the list `(function org-roam-capture--get-point)'.
+
+Org-roam requires the plist elements `:file-name' and `:head' to
+be present, and it’s recommended that `:unnarrowed' be set to t."
+  :group 'org-roam
+  ;; Adapted from `org-capture-templates'
+  :type
+  '(repeat
+    (choice :value ("d" "default" plain (function org-roam-capture--get-point)
+                    "%?"
+                    :file-name "%<%Y%m%d%H%M%S>-${slug}"
+                    :head "#+title: ${title}\n"
+                    :unnarrowed t)
+            (list :tag "Multikey description"
+                  (string :tag "Keys       ")
+                  (string :tag "Description"))
+            (list :tag "Template entry"
+                  (string :tag "Keys              ")
+                  (string :tag "Description       ")
+                  (const :format "" plain)
+                  (const :format "" (function org-roam-capture--get-point))
+                  (choice :tag "Template          "
+                          (string :tag "String"
+                                  :format "String:\n            \
+Template string   :\n%v")
+                          (list :tag "File"
+                                (const :format "" file)
+                                (file :tag "Template file     "))
+                          (list :tag "Function"
+                                (const :format "" function)
+                                (function :tag "Template function ")))
+                  (const :format "File name format  :" :file-name)
+                  (string :format " %v" :value "#+title: ${title}\n")
+                  (const :format "Header format     :" :head)
+                  (string :format "\n%v" :value "%<%Y%m%d%H%M%S>-${slug}")
+                  (const :format "" :unnarrowed) (const :format "" t)
+                  (plist :inline t
+                         :tag "Options"
+                         ;; Give the most common options as checkboxes
+                         :options
+                         (((const :format "%v " :prepend) (const t))
+                          ((const :format "%v " :immediate-finish) (const t))
+                          ((const :format "%v " :jump-to-captured) (const t))
+                          ((const :format "%v " :empty-lines) (const 1))
+                          ((const :format "%v " :empty-lines-before) (const 1))
+                          ((const :format "%v " :empty-lines-after) (const 1))
+                          ((const :format "%v " :clock-in) (const t))
+                          ((const :format "%v " :clock-keep) (const t))
+                          ((const :format "%v " :clock-resume) (const t))
+                          ((const :format "%v " :time-prompt) (const t))
+                          ((const :format "%v " :tree-type) (const week))
+                          ((const :format "%v " :table-line-pos) (string))
+                          ((const :format "%v " :kill-buffer) (const t))))))))
+
+(defcustom org-roam-capture-immediate-template
+  (append (car org-roam-capture-templates) '(:immediate-finish t))
+  "Capture template to use for immediate captures in Org-roam.
+This is a single template, so do not enclose it into a list.
+See `org-roam-capture-templates' for details on templates."
+  :group 'org-roam
+  ;; Adapted from `org-capture-templates'
+  :type
+  '(list :tag "Template entry"
+         :value ("d" "default" plain (function org-roam-capture--get-point)
+                 "%?"
+                 :file-name "%<%Y%m%d%H%M%S>-${slug}"
+                 :head "#+title: ${title}\n"
+                 :unnarrowed t
+                 :immediate-finish t)
+         (string :tag "Keys              ")
+         (string :tag "Description       ")
+         (const :format "" plain)
+         (const :format "" (function org-roam-capture--get-point))
+         (choice :tag "Template          "
+                 (string :tag "String"
+                         :format "String:\n            \
+Template string   :\n%v")
+                 (list :tag "File"
+                       (const :format "" file)
+                       (file :tag "Template file     "))
+                 (list :tag "Function"
+                       (const :format "" function)
+                       (function :tag "Template function ")))
+         (const :format "File name format  :" :file-name)
+         (string :format " %v" :value "#+title: ${title}\n")
+         (const :format "Header format     :" :head)
+         (string :format "\n%v" :value "%<%Y%m%d%H%M%S>-${slug}")
+         (const :format "" :unnarrowed) (const :format "" t)
+         (const :format "" :immediate-finish) (const :format "" t)
+         (plist :inline t
+                :tag "Options"
+                ;; Give the most common options as checkboxes
+                :options
+                (((const :format "%v " :prepend) (const t))
+                 ((const :format "%v " :jump-to-captured) (const t))
+                 ((const :format "%v " :empty-lines) (const 1))
+                 ((const :format "%v " :empty-lines-before) (const 1))
+                 ((const :format "%v " :empty-lines-after) (const 1))
+                 ((const :format "%v " :clock-in) (const t))
+                 ((const :format "%v " :clock-keep) (const t))
+                 ((const :format "%v " :clock-resume) (const t))
+                 ((const :format "%v " :time-prompt) (const t))
+                 ((const :format "%v " :tree-type) (const week))
+                 ((const :format "%v " :table-line-pos) (string))
+                 ((const :format "%v " :kill-buffer) (const t))))))
+
+(defcustom org-roam-capture-ref-templates
  '(("r" "ref" plain (function org-roam-capture--get-point)
-     ""
+     "%?"
     :file-name "${slug}"
-     :head "#+title: ${title}
-#+roam_key: ${ref}\n"
+     :head "#+title: ${title}\n#+roam_key: ${ref}\n"
     :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'.")
+Details on how to specify for the template is given in `org-roam-capture-templates'."
+  :group 'org-roam
+  ;; Adapted from `org-capture-templates'
+  :type
+  '(repeat
+    (choice :value ("d" "default" plain (function org-roam-capture--get-point)
+                    "%?"
+                    :file-name "${slug}"
+                    :head "#+title: ${title}\n#+roam_key: ${ref}\n"
+                    :unnarrowed t)
+            (list :tag "Multikey description"
+                  (string :tag "Keys       ")
+                  (string :tag "Description"))
+            (list :tag "Template entry"
+                  (string :tag "Keys              ")
+                  (string :tag "Description       ")
+                  (const :format "" plain)
+                  (const :format "" (function org-roam-capture--get-point))
+                  (choice :tag "Template          "
+                          (string :tag "String"
+                                  :format "String:\n            \
+Template string   :\n%v")
+                          (list :tag "File"
+                                (const :format "" file)
+                                (file :tag "Template file     "))
+                          (list :tag "Function"
+                                (const :format "" function)
+                                (function :tag "Template function ")))
+                  (const :format "File name format  :" :file-name)
+                  (string :format " %v" :value "#+title: ${title}\n")
+                  (const :format "Header format     :" :head)
+                  (string :format "\n%v" :value "%<%Y%m%d%H%M%S>-${slug}")
+                  (const :format "" :unnarrowed) (const :format "" t)
+                  (plist :inline t
+                         :tag "Options"
+                         ;; Give the most common options as checkboxes
+                         :options
+                         (((const :format "%v " :prepend) (const t))
+                          ((const :format "%v " :immediate-finish) (const t))
+                          ((const :format "%v " :jump-to-captured) (const t))
+                          ((const :format "%v " :empty-lines) (const 1))
+                          ((const :format "%v " :empty-lines-before) (const 1))
+                          ((const :format "%v " :empty-lines-after) (const 1))
+                          ((const :format "%v " :clock-in) (const t))
+                          ((const :format "%v " :clock-keep) (const t))
+                          ((const :format "%v " :clock-resume) (const t))
+                          ((const :format "%v " :time-prompt) (const t))
+                          ((const :format "%v " :tree-type) (const week))
+                          ((const :format "%v " :table-line-pos) (string))
+                          ((const :format "%v " :kill-buffer) (const t))))))))
+
+(defun org-roam-capture-p ()
+  "Return t if the current capture process is an Org-roam capture.
+This function is to only be called when org-capture-plist is
+valid for the capture (i.e. initialization, and finalization of
+the capture)."
+  (plist-get org-capture-plist :org-roam))

 (defun org-roam-capture--get (keyword)
-  "Gets the value for KEYWORD from the `org-roam-capture-template'."
+  "Get the value for KEYWORD from the `org-roam-capture-template'."
  (plist-get (plist-get org-capture-plist :org-roam) keyword))

 (defun org-roam-capture--put (&rest stuff)
-  "Puts properties from STUFF into the `org-roam-capture-template'."
+  "Put properties from STUFF into the `org-roam-capture-template'."
  (let ((p (plist-get org-capture-plist :org-roam)))
    (while stuff
-      (setq p (plist-put p
-                         (pop stuff) (pop stuff))))
+      (setq p (plist-put p (pop stuff) (pop stuff))))
    (setq org-capture-plist
          (plist-put org-capture-plist :org-roam p))))

-(defun org-roam-capture--in-process-p ()
-  "Return non-nil if a `org-roam-capture' buffer exists."
-  (cl-some (lambda (buffer)
-             (and (eq (buffer-local-value 'major-mode buffer)
-                      'org-mode)
-                  (plist-get (buffer-local-value 'org-capture-current-plist buffer)
-                             :org-roam)))
-           (buffer-list)))
+;; FIXME: Pending upstream patch
+;; https://orgmode.org/list/87h7tv9pkm.fsf@hidden/T/#u
+;;
+;; Org-capture's behaviour right now is that `org-capture-plist' is valid only
+;; during the initialization of the Org-capture buffer. The value of
+;; `org-capture-plist' is saved into buffer-local `org-capture-current-plist'.
+;; However, the value for that particular capture is no longer accessible for
+;; hooks in `org-capture-after-finalize-hook', since the capture buffer has been
+;; cleaned up.
+;;
+;; This advice restores the global `org-capture-plist' during finalization, so
+;; the plist is valid during both initialization and finalization of the
+;; capture.
+(defun org-roam-capture--update-plist (&optional _)
+  "Update global plist from local var."
+  (setq org-capture-plist org-capture-current-plist))

-(defun org-roam-capture--fill-template (str &optional info)
-  "Expands the template STR, returning the string.
+(advice-add 'org-capture-finalize :before #'org-roam-capture--update-plist)
+
+(defun org-roam-capture--finalize ()
+  "Finalize the `org-roam-capture' process."
+  (let* ((finalize (org-roam-capture--get :finalize))
+         ;; In case any regions were shielded before, unshield them
+         (region (when-let ((region (org-roam-capture--get :region)))
+                   (org-roam-unshield-region (car region) (cdr region))))
+         (beg (car region))
+         (end (cdr region)))
+    (unless org-note-abort
+      (pcase finalize
+        ('find-file
+         (when-let ((file-path (org-roam-capture--get :file-path)))
+           (org-roam--find-file file-path)
+           (run-hooks 'org-roam-capture-after-find-file-hook)))
+        ('insert-link
+         (when-let* ((mkr (org-roam-capture--get :insert-at))
+                     (buf (marker-buffer mkr)))
+           (with-current-buffer buf
+             (when region
+               (delete-region (car region) (cdr region)))
+             (let ((path (org-roam-capture--get :file-path))
+                   (type (org-roam-capture--get :link-type))
+                   (desc (org-roam-capture--get :link-description)))
+               (if (eq (point) (marker-position mkr))
+                   (insert (org-roam-format-link path desc type))
+                 (org-with-point-at mkr
+                   (insert (org-roam-format-link path desc type))))))))))
+    (when region
+      (set-marker beg nil)
+      (set-marker end nil))
+    (org-roam-capture--save-file-maybe)
+    (remove-hook 'org-capture-after-finalize-hook #'org-roam-capture--finalize)))
+
+(defun org-roam-capture--install-finalize ()
+  "Install `org-roam-capture--finalize' if the capture is an Org-roam capture."
+  (when (org-roam-capture-p)
+    (add-hook 'org-capture-after-finalize-hook #'org-roam-capture--finalize)))
+
+(add-hook 'org-capture-prepare-finalize-hook #'org-roam-capture--install-finalize)
+
+(defun org-roam-capture--fill-template (str)
+  "Expand the template STR, returning the string.
 This is an extension of org-capture's template expansion.

-First, it expands ${var} occurrences in STR, using the INFO alist.
+First, it expands ${var} occurrences in STR, using `org-roam-capture--info'.
 If there is a ${var} with no matching var in the alist, the value
 of var is prompted for via `completing-read'.

@ -150,23 +365,13 @@ Next, it expands the remaining template string using
 `org-capture-fill-template'."
  (-> str
      (s-format (lambda (key)
-                  (or (s--aget info key)
-                      (completing-read (format "%s: " key ) nil))) nil)
+                  (or (s--aget org-roam-capture--info key)
+                      (when-let ((val (completing-read (format "%s: " key) nil)))
+                        (push (cons key val) org-roam-capture--info)
+                        val))) nil)
      (org-capture-fill-template)))

-(defun org-roam-capture--insert-link-h ()
-  "Insert the link into the original buffer, after the capture process is done.
-This is added as a hook to `org-capture-after-finalize-hook'."
-  (when (and (not org-note-abort)
-             (eq (org-roam-capture--get :capture-fn)
-                 'org-roam-insert))
-    (when-let ((region (org-roam-capture--get :region))) ;; Remove previously selected text.
-      (delete-region (car region) (cdr region)))
-    (insert (org-roam--format-link (org-roam-capture--get :file-path)
-                                   (org-roam-capture--get :link-description))))
-  (remove-hook 'org-capture-after-finalize-hook #'org-roam-capture--insert-link-h))
-
-(defun org-roam-capture--save-file-maybe-h ()
+(defun org-roam-capture--save-file-maybe ()
  "Save the file conditionally.
 The file is saved if the original value of :no-save is not t and
 `org-note-abort' is not t. It is added to
@ -180,8 +385,7 @@ The file is saved if the original value of :no-save is not t and
   ((and (not (org-roam-capture--get :orig-no-save))
         (not org-note-abort))
    (with-current-buffer (org-capture-get :buffer)
-      (save-buffer))))
-  (remove-hook 'org-capture-after-finalize-hook #'org-roam-capture--save-file-maybe-h))
+      (save-buffer)))))

 (defun org-roam-capture--new-file ()
  "Return the path to the new file during an Org-roam capture.
@ -201,17 +405,14 @@ aborted, we do the following:

 2. Set the capture template's :no-save to t.

-3. Add a function on `org-capture-after-finalize-hook' that saves
+3. Add a function on `org-capture-before-finalize-hook' that saves
 the file if the original value of :no-save is not t and
 `org-note-abort' is not t."
-  (let* ((name-templ (or (org-roam-capture--get :file-name)
-                         org-roam-capture--file-name-default))
+  (let* ((name-templ (org-roam-capture--get :file-name))
         (new-id (s-trim (org-roam-capture--fill-template
-                          name-templ
-                          org-roam-capture--info)))
+                          name-templ)))
         (file-path (org-roam--file-path-from-id new-id))
-         (roam-head (or (org-roam-capture--get :head)
-                        org-roam-capture--header-default))
+         (roam-head (org-roam-capture--get :head))
         (org-template (org-capture-get :template))
         (roam-template (concat roam-head org-template)))
    (unless (file-exists-p file-path)
@ -229,16 +430,6 @@ the file if the original value of :no-save is not t and
                       :no-save t))
    file-path))

-(defun org-roam-capture--expand-template ()
-  "Expand capture template with information from `org-roam-capture--info'."
-  (org-capture-put :template
-                   (s-format (org-capture-get :template)
-                             (lambda (key)
-                               (or (s--aget org-roam-capture--info key)
-                                   (when-let ((v (completing-read (format "%s: " key ) nil)))
-                                     (push (cons key v) org-roam-capture--info)
-                                     v))) nil)))
-
 (defun org-roam-capture--get-point ()
  "Return exact point to file for org-capture-template.
 The file to use is dependent on the context:
@ -271,7 +462,8 @@ This function is used solely in Org-roam's capture templates: see
                            (plist-get pl :path)
                          (org-roam-capture--new-file))))
                     (_ (error "Invalid org-roam-capture-context")))))
-    (org-roam-capture--expand-template)
+    (org-capture-put :template
+                     (org-roam-capture--fill-template (org-capture-get :template)))
    (org-roam-capture--put :file-path file-path)
    (while org-roam-capture-additional-template-props
      (let ((prop (pop org-roam-capture-additional-template-props))
@ -294,47 +486,47 @@ This function is used solely in Org-roam's capture templates: see
         (let* ((key (pop rest))
                (val (pop rest))
                (custom (member key org-roam-capture--template-keywords)))
+           (when (and custom
+                      (not val))
+             (user-error "Invalid capture template format: %s\nkey %s cannot be nil" template key))
           (push val (if custom org-roam-plist options))
           (push key (if custom org-roam-plist options))))
       (append converted options `(:org-roam ,org-roam-plist))))
    (_ (user-error "Invalid capture template format: %s" template))))

-(defun org-roam-capture--find-file-h ()
-  "Opens the newly created template file.
-This is added as a hook to `org-capture-after-finalize-hook'.
-Run the hooks defined in `org-roam-capture-after-find-file-hook'."
-  (unless org-note-abort
-    (when-let ((file-path (org-roam-capture--get :file-path)))
-      (find-file file-path))
-    (run-hooks 'org-roam-capture-after-find-file-hook))
-  (remove-hook 'org-capture-after-finalize-hook #'org-roam-capture--find-file-h))
-
 (defcustom org-roam-capture-after-find-file-hook nil
  "Hook that is run right after an Org-roam capture process is finalized.
 Suitable for moving point."
  :group 'org-roam
  :type 'hook)

+(defcustom org-roam-capture-function #'org-capture
+  "Function that is invoked to start the `org-capture' process."
+  :group 'org-roam
+  :type 'function)
+
 (defun org-roam-capture--capture (&optional goto keys)
  "Create a new file, and return the path to the edited file.
 The templates are defined at `org-roam-capture-templates'.  The
 GOTO and KEYS argument have the same functionality as
 `org-capture'."
-  (let ((org-capture-templates (mapcar #'org-roam-capture--convert-template org-roam-capture-templates))
-        org-capture-templates-contexts)
-    (when (= (length org-capture-templates) 1)
+  (let* ((org-capture-templates (mapcar #'org-roam-capture--convert-template org-roam-capture-templates))
+         (one-template-p (= (length org-capture-templates) 1))
+         org-capture-templates-contexts)
+    (when one-template-p
      (setq keys (caar org-capture-templates)))
-    (add-hook 'org-capture-after-finalize-hook #'org-roam-capture--save-file-maybe-h)
-    (org-capture goto keys)))
+    (if (or one-template-p
+            (eq org-roam-capture-function 'org-capture))
+        (org-capture goto keys)
+      (funcall-interactively org-roam-capture-function))))

 ;;;###autoload
-(defun org-roam-capture ()
+(defun org-roam-capture (&optional goto keys)
  "Launches an `org-capture' process for a new or existing note.
-This uses the templates defined at `org-roam-capture-templates'."
-  (interactive)
+This uses the templates defined at `org-roam-capture-templates'.
+Arguments GOTO and KEYS see `org-capture'."
+  (interactive "P")
  (unless org-roam-mode (org-roam-mode))
-  (when (org-roam-capture--in-process-p)
-    (user-error "Nested Org-roam capture processes not supported"))
  (let* ((completions (org-roam--get-title-path-completions))
         (title-with-keys (org-roam-completion--completing-read "File: "
                                                                completions))
@ -342,12 +534,11 @@ This uses the templates defined at `org-roam-capture-templates'."
         (title (or (plist-get res :title) title-with-keys))
         (file-path (plist-get res :path)))
    (let ((org-roam-capture--info (list (cons 'title title)
-                                        (cons 'slug (org-roam--title-to-slug title))
+                                        (cons 'slug (funcall org-roam-title-to-slug-function title))
                                        (cons 'file file-path)))
          (org-roam-capture--context 'capture))
-      (setq org-roam-capture-additional-template-props (list :capture-fn 'org-roam-capture))
      (condition-case err
-          (org-roam-capture--capture)
+          (org-roam-capture--capture goto keys)
        (error (user-error "%s.  Please adjust `org-roam-capture-templates'"
                           (error-message-string err)))))))

--- a/org-roam-compat.el
+++ b/org-roam-compat.el
@ -5,8 +5,8 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 1.2.0
-;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.0"))
+;; Version: 1.2.2
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.2"))

 ;; This file is NOT part of GNU Emacs.

@ -41,8 +41,6 @@
  "org-roam 1.0.0")
 (define-obsolete-function-alias 'org-roam-sql         'org-roam-db-query
  "org-roam 1.0.0")
-(define-obsolete-function-alias 'org-roam--get-db     'org-roam-db--get
-  "org-roam 1.0.0")
 (define-obsolete-function-alias 'org-roam--db-clear   'org-roam-db--clear
  "org-roam 1.0.0")
 (define-obsolete-function-alias 'org-roam-show-graph  'org-roam-graph-show
@ -79,9 +77,8 @@
  "org-roam 1.1.0")
 (define-obsolete-function-alias 'org-roam-db--maybe-update 'org-roam-db--update-maybe
  "org-roam 1.1.0")
-
-(when (version< (org-version) "9.3")
-  (defalias 'org-link-make-string 'org-make-link-string))
+(define-obsolete-function-alias 'org-roam-db--clear 'org-roam-db-clear
+  "org-roam 1.2.0")

 ;;;; Variables
 (define-obsolete-variable-alias 'org-roam-graphviz-extra-options
--- a/org-roam-completion.el
+++ b/org-roam-completion.el
@ -5,8 +5,8 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 1.2.0
-;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.0"))
+;; Version: 1.2.2
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.2"))

 ;; This file is NOT part of GNU Emacs.

@ -47,6 +47,11 @@
          (function :tag "Custom function"))
  :group 'org-roam)

+(defcustom org-roam-completion-ignore-case t
+  "Whether to ignore case in Org-roam `completion-at-point' completions."
+  :group 'org-roam
+  :type 'boolean)
+
 (defun org-roam-completion--helm-candidate-transformer (candidates _source)
  "Transforms CANDIDATES for Helm-based completing read.
 SOURCE is not used."
--- a/org-roam-dailies.el
+++ b/org-roam-dailies.el
@ -5,8 +5,8 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 1.2.0
-;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.0"))
+;; Version: 1.2.2
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.2"))

 ;; This file is NOT part of GNU Emacs.

@ -36,13 +36,62 @@
 (require 'org-roam-capture)
 (require 'org-roam-macs)

-(defvar org-roam-dailies-capture-templates
+(defcustom org-roam-dailies-capture-templates
  '(("d" "daily" plain (function org-roam-capture--get-point)
     ""
     :immediate-finish t
     :file-name "%<%Y-%m-%d>"
     :head "#+title: %<%Y-%m-%d>"))
-  "Capture templates for daily notes in Org-roam.")
+  "Capture templates for daily notes in Org-roam."
+  :group 'org-roam
+  ;; Adapted from `org-capture-templates'
+  :type
+  '(repeat
+    (choice :value ("d" "daily" plain (function org-roam-capture--get-point)
+                    ""
+                    :immediate-finish t
+                    :file-name "%<%Y-%m-%d>"
+                    :head "#+title: %<%Y-%m-%d>")
+            (list :tag "Multikey description"
+                  (string :tag "Keys       ")
+                  (string :tag "Description"))
+            (list :tag "Template entry"
+                  (string :tag "Keys              ")
+                  (string :tag "Description       ")
+                  (const :format "" plain)
+                  (const :format "" (function org-roam-capture--get-point))
+                  (choice :tag "Template          "
+                          (string :tag "String"
+                                  :format "String:\n            \
+Template string   :\n%v")
+                          (list :tag "File"
+                                (const :format "" file)
+                                (file :tag "Template file     "))
+                          (list :tag "Function"
+                                (const :format "" function)
+                                (function :tag "Template function ")))
+                  (const :format "" :immediate-finish) (const :format "" t)
+                  (const :format "File name format  :" :file-name)
+                  (string :format " %v" :value "#+title: ${title}\n")
+                  (const :format "Header format     :" :head)
+                  (string :format "\n%v" :value "%<%Y%m%d%H%M%S>-${slug}")
+                  (plist :inline t
+                         :tag "Options"
+                         ;; Give the most common options as checkboxes
+                         :options
+                         (((const :format "%v " :prepend) (const t))
+                          ((const :format "%v " :jump-to-captured) (const t))
+                          ((const :format "%v " :empty-lines) (const 1))
+                          ((const :format "%v " :empty-lines-before) (const 1))
+                          ((const :format "%v " :empty-lines-after) (const 1))
+                          ((const :format "%v " :clock-in) (const t))
+                          ((const :format "%v " :clock-keep) (const t))
+                          ((const :format "%v " :clock-resume) (const t))
+                          ((const :format "%v " :time-prompt) (const t))
+                          ((const :format "%v " :tree-type) (const week))
+                          ((const :format "%v " :table-line-pos) (string))
+                          ((const :format "%v " :kill-buffer) (const t))
+                          ((const :format "%v " :unnarrowed) (const t))))))))

 ;; Declarations
 (defvar org-roam-mode)
@ -54,9 +103,8 @@
  (let ((org-roam-capture-templates org-roam-dailies-capture-templates)
        (org-roam-capture--info (list (cons 'time time)))
        (org-roam-capture--context 'dailies))
-    (add-hook 'org-capture-after-finalize-hook #'org-roam-capture--find-file-h)
-    (org-roam--with-template-error 'org-roam-dailies-capture-templates
-      (org-roam-capture--capture))))
+    (setq org-roam-capture-additional-template-props (list :finalize 'find-file))
+    (org-roam-capture--capture)))

 (defun org-roam-dailies-today ()
  "Create and find the daily note for today."
--- a/org-roam-db.el
+++ b/org-roam-db.el
@ -5,8 +5,8 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 1.2.0
-;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.0"))
+;; Version: 1.2.2
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.2"))

 ;; This file is NOT part of GNU Emacs.

@ -35,9 +35,11 @@
 (require 'emacsql)
 (require 'emacsql-sqlite3)
 (require 'seq)
+(require 'org-macs)
 (require 'org-roam-macs)

 (defvar org-roam-directory)
+(defvar org-roam-enable-headline-linking)
 (defvar org-roam-verbose)
 (defvar org-roam-file-name)

@ -45,13 +47,15 @@
 (declare-function org-roam--extract-titles                 "org-roam")
 (declare-function org-roam--extract-ref                    "org-roam")
 (declare-function org-roam--extract-tags                   "org-roam")
-(declare-function org-roam--extract-headlines              "org-roam")
+(declare-function org-roam--extract-ids                    "org-roam")
 (declare-function org-roam--extract-links                  "org-roam")
 (declare-function org-roam--list-all-files                 "org-roam")
+(declare-function org-roam--path-to-slug                   "org-roam")
+(declare-function org-roam--file-name-extension            "org-roam")
 (declare-function org-roam-buffer--update-maybe            "org-roam-buffer")

 ;;;; Options
-(defcustom org-roam-db-location nil
+(defcustom org-roam-db-location (expand-file-name "org-roam.db" user-emacs-directory)
  "The full path to file where the Org-roam database is stored.
 If this is non-nil, the Org-roam sqlite database is saved here.

@ -60,20 +64,31 @@ when used with multiple Org-roam instances."
  :type 'string
  :group 'org-roam)

-(defconst org-roam-db--version 6)
+(defcustom org-roam-db-gc-threshold gc-cons-threshold
+  "The value to temporarily set the `gc-cons-threshold' threshold to.
+During large, heavy operations like `org-roam-db-build-cache',
+many GC operations happen because of the large number of
+temporary structures generated (e.g. parsed ASTs). Temporarily
+increasing `gc-cons-threshold' will help reduce the number of GC
+operations, at the cost of temporary memory usage.
+
+This defaults to the original value of `gc-cons-threshold', but
+tweaking this number may lead to better overall performance. For
+example, to reduce the number of GCs, one may set it to a large
+value like `most-positive-fixnum'."
+  :type 'int
+  :group 'org-roam)
+
+(defconst org-roam-db--version 9)

 (defvar org-roam-db--connection (make-hash-table :test #'equal)
  "Database connection to Org-roam database.")

 ;;;; Core Functions
-(defun org-roam-db--get ()
-  "Return the sqlite db file."
-    (or org-roam-db-location
-      (expand-file-name "org-roam.db" org-roam-directory)))

 (defun org-roam-db--get-connection ()
  "Return the database connection, if any."
-  (gethash (file-truename org-roam-directory)
+  (gethash (expand-file-name org-roam-directory)
           org-roam-db--connection))

 (defun org-roam-db ()
@ -82,12 +97,11 @@ Initializes and stores the database, and the database connection.
 Performs a database upgrade when required."
  (unless (and (org-roam-db--get-connection)
               (emacsql-live-p (org-roam-db--get-connection)))
-    (let* ((db-file (org-roam-db--get))
-           (init-db (not (file-exists-p db-file))))
-      (make-directory (file-name-directory db-file) t)
-      (let ((conn (emacsql-sqlite3 db-file)))
+    (let ((init-db (not (file-exists-p org-roam-db-location))))
+      (make-directory (file-name-directory org-roam-db-location) t)
+      (let ((conn (emacsql-sqlite3 org-roam-db-location)))
        (set-process-query-on-exit-flag (emacsql-process conn) nil)
-        (puthash (file-truename org-roam-directory)
+        (puthash (expand-file-name org-roam-directory)
                 conn
                 org-roam-db--connection)
        (when init-db
@ -121,9 +135,10 @@ SQL can be either the emacsql vector representation, or a string."
      (hash :not-null)
      (meta :not-null)])

-    (headlines
+    (ids
     [(id :unique :primary-key)
-      (file :not-null)])
+      (file :not-null)
+      (level :not-null)])

    (links
     [(from :not-null)
@ -137,7 +152,7 @@ SQL can be either the emacsql vector representation, or a string."

    (titles
     [(file :not-null)
-      titles])
+      title])

    (refs
     [(ref :unique :not-null)
@ -179,8 +194,8 @@ the current `org-roam-directory'."
 ;;;; Database API
 ;;;;; Initialization
 (defun org-roam-db--initialized-p ()
-  "Whether the cache has been initialized."
-  (and (file-exists-p (org-roam-db--get))
+  "Whether the Org-roam cache has been initialized."
+  (and (file-exists-p org-roam-db-location)
       (> (caar (org-roam-db-query [:select (funcall count) :from titles]))
          0)))

@ -190,18 +205,18 @@ the current `org-roam-directory'."
    (error "[Org-roam] your cache isn't built yet! Please run org-roam-db-build-cache")))

 ;;;;; Clearing
-(defun org-roam-db--clear ()
-  "Clears all entries in the caches."
+(defun org-roam-db-clear ()
+  "Clears all entries in the Org-roam cache."
  (interactive)
-  (when (file-exists-p (org-roam-db--get))
+  (when (file-exists-p org-roam-db-location)
    (dolist (table (mapcar #'car org-roam-db--table-schemata))
      (org-roam-db-query `[:delete :from ,table]))))

 (defun org-roam-db--clear-file (&optional filepath)
  "Remove any related links to the file at FILEPATH.
 This is equivalent to removing the node from the graph."
-  (let ((file (file-truename (or filepath
-                                 (buffer-file-name (buffer-base-buffer))))))
+  (let ((file (expand-file-name (or filepath
+                                    (buffer-file-name (buffer-base-buffer))))))
    (dolist (table (mapcar #'car org-roam-db--table-schemata))
      (org-roam-db-query `[:delete :from ,table
                           :where (= ,(if (eq table 'links) 'from 'file) $s1)]
@ -227,14 +242,29 @@ This is equivalent to removing the node from the graph."
  (org-roam-db-query
   [:insert :into titles
    :values $v1]
-   (list (vector file titles))))
+   (mapcar (lambda (title)
+             (vector file title)) titles)))

-(defun org-roam-db--insert-headlines (headlines)
-  "Insert HEADLINES into the Org-roam cache."
-  (org-roam-db-query
-   [:insert :into headlines
-    :values $v1]
-   headlines))
+(defun org-roam-db--insert-ids (ids)
+  "Insert IDS into the Org-roam cache.
+Returns t if the insertion was successful, nil otherwise.
+Insertions can fail when there is an ID conflict."
+  (condition-case nil
+      (progn
+        (org-roam-db-query
+         [:insert :into ids
+          :values $v1]
+         ids)
+        t)
+    (error
+     (unless (listp ids)
+       (setq ids (list ids)))
+     (lwarn '(org-roam) :error
+            (format "Duplicate IDs in %s, one of:\n\n%s\n\nskipping..."
+                    (aref (car ids) 1)
+                    (string-join (mapcar (lambda (hl)
+                                           (aref hl 0)) ids) "\n")))
+     nil)))

 (defun org-roam-db--insert-tags (file tags)
  "Insert TAGS for a FILE into the Org-roam cache."
@ -244,12 +274,27 @@ This is equivalent to removing the node from the graph."
   (list (vector file tags))))

 (defun org-roam-db--insert-ref (file ref)
-  "Insert REF for FILE into the Org-roam cache."
+  "Insert REF for FILE into the Org-roam cache.
+Returns t if successful, and nil otherwise.
+Insertions can fail if the key is already in the database."
  (let ((key (cdr ref))
        (type (car ref)))
-    (org-roam-db-query
-     [:insert :into refs :values $v1]
-     (list (vector key file type)))))
+    (condition-case nil
+        (progn
+          (org-roam-db-query
+           [:insert :into refs :values $v1]
+           (list (vector key file type)))
+          t)
+      (error
+       (lwarn '(org-roam) :error
+              (format "Duplicate ref %s in:\n\nA: %s\nB: %s\n\nskipping..."
+                      key
+                      file
+                      (caar (org-roam-db-query
+                             [:select file :from refs
+                              :where (= ref $v1)]
+                             (vector key)))))
+       nil))))

 ;;;;; Fetching
 (defun org-roam-db--get-current-files ()
@ -262,17 +307,27 @@ This is equivalent to removing the node from the graph."

 (defun org-roam-db--get-titles (file)
  "Return the titles of FILE from the cache."
-  (caar (org-roam-db-query [:select [titles] :from titles
-                            :where (= file $s1)]
-                           file
-                           :limit 1)))
+  (caar (org-roam-db-query [:select [title] :from titles
+                            :where (= file $s1)
+                            :limit 1]
+                           file)))
+
+(defun org-roam-db--get-tags ()
+  "Return all distinct tags from the cache."
+  (let ((rows (org-roam-db-query [:select :distinct [tags] :from tags]))
+        acc)
+    (dolist (row rows)
+      (dolist (tag (car row))
+        (unless (member tag acc)
+          (push tag acc))))
+    acc))

 (defun org-roam-db--connected-component (file)
  "Return all files reachable from/connected to FILE, including the file itself.
 If the file does not have any connections, nil is returned."
  (let* ((query "WITH RECURSIVE
                   links_of(file, link) AS
-                     (WITH filelinks AS (SELECT * FROM links WHERE \"type\" = '\"file\"'),
+                     (WITH filelinks AS (SELECT * FROM links WHERE NOT \"type\" = '\"cite\"'),
                           citelinks AS (SELECT * FROM links
                                                  JOIN refs ON links.\"to\" = refs.\"ref\"
                                                            AND links.\"type\" = '\"cite\"')
@ -294,7 +349,7 @@ This includes the file itself. If the file does not have any
 connections, nil is returned."
  (let* ((query "WITH RECURSIVE
                   links_of(file, link) AS
-                     (WITH filelinks AS (SELECT * FROM links WHERE \"type\" = '\"file\"'),
+                     (WITH filelinks AS (SELECT * FROM links WHERE NOT \"type\" = '\"cite\"'),
                           citelinks AS (SELECT * FROM links
                                                  JOIN refs ON links.\"to\" = refs.\"ref\"
                                                            AND links.\"type\" = '\"cite\"')
@ -321,14 +376,24 @@ connections, nil is returned."
         (files (mapcar 'car-safe (emacsql (org-roam-db) query file max-distance))))
    files))

+(defun org-roam-db--file-hash (&optional file-path)
+  "Compute the hash of FILE-PATH, a file or current buffer."
+  (if file-path
+      (with-temp-buffer
+        (set-buffer-multibyte nil)
+        (insert-file-contents-literally file-path)
+        (secure-hash 'sha1 (current-buffer)))
+    (org-with-wide-buffer
+     (secure-hash 'sha1 (current-buffer)))))
+
 ;;;;; Updating
 (defun org-roam-db--update-meta ()
  "Update the metadata of the current buffer into the cache."
-  (let* ((file (file-truename (buffer-file-name)))
+  (let* ((file (or org-roam-file-name (buffer-file-name)))
         (attr (file-attributes file))
         (atime (file-attribute-access-time attr))
         (mtime (file-attribute-modification-time attr))
-         (hash (secure-hash 'sha1 (current-buffer))))
+         (hash (org-roam-db--file-hash)))
    (org-roam-db-query [:delete :from files
                        :where (= file $s1)]
                       file)
@ -336,17 +401,18 @@ connections, nil is returned."

 (defun org-roam-db--update-titles ()
  "Update the title of the current buffer into the cache."
-  (let* ((file (file-truename (buffer-file-name)))
-         (title (org-roam--extract-titles)))
+  (let* ((file (or org-roam-file-name (buffer-file-name)))
+         (titles (or (org-roam--extract-titles)
+                     (list (org-roam--path-to-slug file)))))
    (org-roam-db-query [:delete :from titles
                        :where (= file $s1)]
                       file)
-    (org-roam-db--insert-titles file title)))
+    (org-roam-db--insert-titles file titles)))

 (defun org-roam-db--update-tags ()
  "Update the tags of the current buffer into the cache."
-  (let ((file (file-truename (buffer-file-name)))
-        (tags (org-roam--extract-tags)))
+  (let* ((file (or org-roam-file-name (buffer-file-name)))
+         (tags (org-roam--extract-tags file)))
    (org-roam-db-query [:delete :from tags
                        :where (= file $s1)]
                       file)
@ -355,7 +421,7 @@ connections, nil is returned."

 (defun org-roam-db--update-refs ()
  "Update the ref of the current buffer into the cache."
-  (let ((file (file-truename (buffer-file-name))))
+  (let ((file (or org-roam-file-name (buffer-file-name))))
    (org-roam-db-query [:delete :from refs
                        :where (= file $s1)]
                       file)
@ -364,130 +430,124 @@ connections, nil is returned."

 (defun org-roam-db--update-links ()
  "Update the file links of the current buffer in the cache."
-  (let ((file (file-truename (buffer-file-name))))
+  (let ((file (or org-roam-file-name (buffer-file-name))))
    (org-roam-db-query [:delete :from links
                        :where (= from $s1)]
                       file)
    (when-let ((links (org-roam--extract-links)))
      (org-roam-db--insert-links links))))

-(defun org-roam-db--update-headlines ()
-  "Update the file headlines of the current buffer into the cache."
-  (let* ((file (file-truename (buffer-file-name))))
-    (org-roam-db-query [:delete :from headlines
+(defun org-roam-db--update-ids ()
+  "Update the ids of the current buffer into the cache."
+  (let* ((file (or org-roam-file-name (buffer-file-name))))
+    (org-roam-db-query [:delete :from ids
                        :where (= file $s1)]
                       file)
-    (when-let ((headlines (org-roam--extract-headlines)))
-      (org-roam-db--insert-headlines headlines))))
+    (when-let ((ids (org-roam--extract-ids file)))
+      (org-roam-db--insert-ids ids))))

 (defun org-roam-db--update-file (&optional file-path)
-  "Update Org-roam cache for FILE-PATH."
-  (when (org-roam--org-roam-file-p file-path)
-    (let ((buf (or (and file-path
-                        (find-file-noselect file-path t))
-                   (current-buffer))))
+  "Update Org-roam cache for FILE-PATH.
+If the file does not exist anymore, remove it from the cache.
+If the file exists, update the cache with information."
+  (setq file-path (or file-path
+                      (buffer-file-name (buffer-base-buffer))))
+  (if (not (file-exists-p file-path))
+      (org-roam-db--clear-file file-path)
+    ;; save the file before performing a database update
+    (when-let ((buf (find-buffer-visiting file-path)))
      (with-current-buffer buf
-        (save-excursion
-          (org-roam-db--update-meta)
-          (org-roam-db--update-tags)
-          (org-roam-db--update-titles)
-          (org-roam-db--update-refs)
-          (org-roam-db--update-headlines)
-          (org-roam-db--update-links)
-          (org-roam-buffer--update-maybe :redisplay t))))))
+        (save-buffer)))
+    (org-roam--with-temp-buffer file-path
+      (emacsql-with-transaction (org-roam-db)
+        (org-roam-db--update-meta)
+        (org-roam-db--update-tags)
+        (org-roam-db--update-titles)
+        (org-roam-db--update-refs)
+        (when org-roam-enable-headline-linking
+          (org-roam-db--update-ids))
+        (org-roam-db--update-links)))))

 (defun org-roam-db-build-cache (&optional force)
  "Build the cache for `org-roam-directory'.
 If FORCE, force a rebuild of the cache from scratch."
  (interactive "P")
-  (when force (delete-file (org-roam-db--get)))
+  (when force (delete-file org-roam-db-location))
  (org-roam-db--close) ;; Force a reconnect
  (org-roam-db) ;; To initialize the database, no-op if already initialized
-  (let* ((org-roam-files (org-roam--list-all-files))
+  (let* ((gc-cons-threshold org-roam-db-gc-threshold)
+	 (org-agenda-files nil)
+         (org-roam-files (org-roam--list-all-files))
         (current-files (org-roam-db--get-current-files))
-         all-files all-headlines all-links all-titles all-refs all-tags)
-    ;; Two-step building
-    ;; First step: Rebuild files and headlines
-    (dolist (file org-roam-files)
-      (let* ((attr (file-attributes file))
-             (atime (file-attribute-access-time attr))
-             (mtime (file-attribute-modification-time attr)))
-        (org-roam--with-temp-buffer file
-          (let ((contents-hash (secure-hash 'sha1 (current-buffer))))
+         (file-count 0)
+         (id-count 0)
+         (link-count 0)
+         (tag-count 0)
+         (title-count 0)
+         (ref-count 0)
+         (deleted-count 0)
+         (processed-count 0))
+    (emacsql-with-transaction (org-roam-db)
+      ;; Two-step building
+      ;; First step: Rebuild files and ids
+      (dolist (file org-roam-files)
+        (org-roam-message "Processed %s/%s files..." processed-count (length org-roam-files))
+        (let* ((attr (file-attributes file))
+               (atime (file-attribute-access-time attr))
+               (mtime (file-attribute-modification-time attr)))
+          (let ((contents-hash (org-roam-db--file-hash file)))
            (unless (string= (gethash file current-files)
                             contents-hash)
-              (org-roam-db--clear-file file)
-              (push (vector file contents-hash (list :atime atime :mtime mtime))
-                    all-files)
-              (when-let (headlines (org-roam--extract-headlines file))
-                (push headlines all-headlines)))))))
-    (when all-files
-      (org-roam-db-query
-       [:insert :into files
-        :values $v1]
-       all-files))
-    (when all-headlines
-      (org-roam-db-query
-       [:insert :into headlines
-        :values $v1]
-       all-headlines))
-    ;; Second step: Rebuild the rest
-    (dolist (file org-roam-files)
-      (org-roam--with-temp-buffer file
-        (let ((contents-hash (secure-hash 'sha1 (current-buffer))))
-          (unless (string= (gethash file current-files)
-                           contents-hash)
-            (when-let (links (org-roam--extract-links file))
-              (push links all-links))
-            (when-let (tags (org-roam--extract-tags file))
-              (push (vector file tags) all-tags))
-            (let ((titles (org-roam--extract-titles)))
-              (push (vector file titles)
-                    all-titles))
-            (when-let* ((ref (org-roam--extract-ref))
-                        (type (car ref))
-                        (key (cdr ref)))
-              (setq all-refs (cons (vector key file type) all-refs))))
-          (remhash file current-files))))
-    (dolist (file (hash-table-keys current-files))
-      ;; These files are no longer around, remove from cache...
-      (org-roam-db--clear-file file))
-    (when all-links
-      (org-roam-db-query
-       [:insert :into links
-        :values $v1]
-       all-links))
-    (when all-titles
-      (org-roam-db-query
-       [:insert :into titles
-        :values $v1]
-       all-titles))
-    (when all-tags
-      (org-roam-db-query
-       [:insert :into tags
-        :values $v1]
-       all-tags))
-    (when all-refs
-      (org-roam-db-query
-       [:insert :into refs
-        :values $v1]
-       all-refs))
-    (let ((stats (list :files (length all-files)
-                       :headlines (length all-headlines)
-                       :links (length all-links)
-                       :tags (length all-tags)
-                       :titles (length all-titles)
-                       :refs (length all-refs)
-                       :deleted (length (hash-table-keys current-files)))))
-      (org-roam-message "files: %s, headlines: %s, links: %s, tags: %s, titles: %s, refs: %s, deleted: %s"
-                        (plist-get stats :files)
-                        (plist-get stats :headlines)
-                        (plist-get stats :links)
-                        (plist-get stats :tags)
-                        (plist-get stats :titles)
-                        (plist-get stats :refs)
-                        (plist-get stats :deleted))
-      stats)))
+              (condition-case nil
+                  (org-roam--with-temp-buffer file
+                    (org-roam-db--clear-file file)
+                    (org-roam-db-query
+                     [:insert :into files
+                      :values $v1]
+                     (vector file contents-hash (list :atime atime :mtime mtime)))
+                    (setq file-count (1+ file-count))
+                    (when org-roam-enable-headline-linking
+                      (when-let ((ids (org-roam--extract-ids file)))
+                        (when (org-roam-db--insert-ids ids)
+                          (setq id-count (+ id-count (length ids))))))
+                    (when-let (links (org-roam--extract-links file))
+                      (org-roam-db-query
+                       [:insert :into links
+                        :values $v1]
+                       links)
+                      (setq link-count (1+ link-count)))
+                    (when-let (tags (org-roam--extract-tags file))
+                      (org-roam-db-query
+                       [:insert :into tags
+                        :values $v1]
+                       (vector file tags))
+                      (setq tag-count (1+ tag-count)))
+                    (let ((titles (or (org-roam--extract-titles)
+                                      (list (org-roam--path-to-slug file)))))
+                      (org-roam-db--insert-titles file titles)
+                      (setq title-count (+ title-count (length titles))))
+                    (when-let* ((ref (org-roam--extract-ref)))
+                      (when (org-roam-db--insert-ref file ref)
+                        (setq ref-count (1+ ref-count)))))
+                (file-error
+                 (setq org-roam-files (remove file org-roam-files))
+                 (org-roam-db--clear-file file)
+                 (lwarn '(org-roam) :warning
+                        "Skipping unreadable file while building cache: %s" file))))
+            (remhash file current-files)
+            (setq processed-count (+ processed-count 1)))))
+      (dolist (file (hash-table-keys current-files))
+        ;; These files are no longer around, remove from cache...
+        (org-roam-db--clear-file file)
+        (setq deleted-count (1+ deleted-count))))
+    (org-roam-message "files: Δ%s, ids: Δ%s, links: Δ%s, tags: Δ%s, titles: Δ%s, refs: Δ%s, deleted: Δ%s"
+                      file-count
+                      id-count
+                      link-count
+                      tag-count
+                      title-count
+                      ref-count
+                      deleted-count)))

 (provide 'org-roam-db)

--- a/org-roam-dev.el
+++ b/org-roam-dev.el
@ -5,8 +5,8 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 1.2.0
-;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.0"))
+;; Version: 1.2.2
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.2"))

 ;; This file is NOT part of GNU Emacs.

@ -33,7 +33,14 @@
 ;;
 ;;; Code:
 (require 'emacsql)
-(emacsql-fix-vector-indentation)
-(provide 'org-roam-dev)

+;;;###autoload
+(define-minor-mode org-roam-dev-mode
+  "Minor mode for setting the dev environment of Org-roam."
+  :lighter " ORD"
+  (when org-roam-dev-mode
+    (emacsql-fix-vector-indentation)
+    (setq-local sentence-end-double-space nil)))
+
+(provide 'org-roam-dev)
 ;;; org-roam-dev.el ends here
--- a/org-roam-doctor.el
+++ b/org-roam-doctor.el
@ -5,8 +5,8 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/jethrokuan/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 1.2.0
-;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.0"))
+;; Version: 1.2.2
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.2"))

 ;; This file is NOT part of GNU Emacs.

@ -59,6 +59,15 @@
 (defvar org-roam-verbose)
 (defvar org-roam-mode)

+(defcustom org-roam-doctor-inhibit-startup t
+  "Inhibit `org-mode' startup when processing files with `org-doctor'.
+When non-nil, images and LaTeX preview will not be generated,
+tables will not be aligned, and headlines will not respect
+startup visability. This significantly improves performance when
+processing multiple files"
+  :type 'boolean
+  :group 'org-roam)
+
 (cl-defstruct (org-roam-doctor-checker (:copier nil))
  (name 'missing-checker-name)
  (description "")
@ -294,7 +303,8 @@ If CHECKALL, run the check for all Org-roam files."
 (defun org-roam-doctor-start (files checkers)
  "Lint FILES using CHECKERS."
  (save-window-excursion
-    (let ((existing-buffers (org-roam--get-roam-buffers)))
+    (let ((existing-buffers (org-roam--get-roam-buffers))
+          (org-inhibit-startup org-roam-doctor-inhibit-startup))
      (dolist (f files)
        (let ((buf (find-file-noselect f)))
          (org-roam-doctor--check buf checkers)
--- a/org-roam-faces.el
+++ b/org-roam-faces.el
@ -0,0 +1,72 @@
+;;; org-roam-faces.el --- Face definitions -*- coding: utf-8; lexical-binding: t; -*-
+
+;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
+
+;; Author: Jethro Kuan <jethrokuan95@gmail.com>
+;; URL: https://github.com/org-roam/org-roam
+;; Keywords: org-mode, roam, convenience
+;; Version: 1.2.2
+;; Package-Requires: ((emacs "26.1"))
+
+;; This file is NOT part of GNU Emacs.
+
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation; either version 3, or (at your option)
+;; any later version.
+;;
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+;;
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs; see the file COPYING.  If not, write to the
+;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+;; Boston, MA 02110-1301, USA.
+
+;;; Commentary:
+
+;; This file contains the face definitions for Org-roam.
+
+;;; Code:
+
+(defgroup org-roam-faces nil
+  "Faces used by Org-roam."
+  :group 'org-roam
+  :group 'faces)
+
+;;; Definitions
+(defface org-roam-link
+  '((t :inherit org-link))
+  "Face for Org-roam links."
+  :group 'org-roam-faces)
+
+(defface org-roam-tag
+  '((t :weight bold))
+  "Face for Org-roam tags in minibuffer commands."
+  :group 'org-roam-faces)
+
+(defface org-roam-link-current
+  '((t :inherit org-link))
+  "Face for Org-roam links pointing to the current buffer."
+  :group 'org-roam-faces)
+
+(defface org-roam-link-invalid
+  '((t :inherit (error org-link)))
+  "Face for Org-roam links that are not valid.
+This face is used for links without a destination."
+  :group 'org-roam-faces)
+
+(defface org-roam-link-shielded
+  '((t :inherit (warning org-link)))
+  "Face for Org-roam links that are shielded.
+This face is used on the region target by `org-roam-insertion'
+during an `org-roam-capture'."
+  :group 'org-roam-faces)
+
+;;; _
+
+(provide 'org-roam-faces)
+
+;;; org-roam-faces.el ends here
--- a/org-roam-graph.el
+++ b/org-roam-graph.el
@ -5,8 +5,8 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 1.2.0
-;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.0"))
+;; Version: 1.2.2
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.2"))

 ;; This file is NOT part of GNU Emacs.

@ -192,14 +192,16 @@ into a digraph."
                                   ","))))
      (dolist (node nodes)
        (let* ((file (xml-escape-string (car node)))
-               (title (or (caadr node)
+               (title (or (cadr node)
                          (org-roam--path-to-slug file)))
               (shortened-title (pcase org-roam-graph-shorten-titles
                                  (`truncate (s-truncate org-roam-graph-max-title-length title))
                                  (`wrap (s-word-wrap org-roam-graph-max-title-length title))
                                  (_ title)))
+               (shortened-title (org-roam-string-quote shortened-title))
+               (title (org-roam-string-quote title))
               (node-properties
-                `(("label"   . ,(s-replace "\"" "\\\"" shortened-title))
+                `(("label"   . ,shortened-title)
                  ("URL"     . ,(concat "org-protocol://roam-file?file=" (url-hexify-string file)))
                  ("tooltip" . ,(xml-escape-string title)))))
          (insert
@ -230,8 +232,9 @@ CALLBACK is passed the graph file as its sole argument."
                        "Please adjust `org-roam-graph-executable'")
                org-roam-graph-executable))
  (let* ((node-query (or node-query
-                         `[:select [file titles] :from titles
-                           ,@(org-roam-graph--expand-matcher 'file t)]))
+                         `[:select [file title] :from titles
+                           ,@(org-roam-graph--expand-matcher 'file t)
+                           :group :by file]))
         (graph      (org-roam-graph--dot node-query))
         (temp-dot   (make-temp-file "graph." nil ".dot" graph))
         (temp-graph (make-temp-file "graph." nil ".svg")))
@ -262,12 +265,12 @@ CALLBACK is passed the graph file as its sole argument."
  "Build a graph of nodes connected to FILE.
 If MAX-DISTANCE is non-nil, limit nodes to MAX-DISTANCE steps.
 CALLBACK is passed to `org-roam-graph--build'."
-  (let* ((file (file-truename file))
+  (let* ((file (expand-file-name file))
         (files (or (if (and max-distance (>= max-distance 0))
                        (org-roam-db--links-with-max-distance file max-distance)
                      (org-roam-db--connected-component file))
                    (list file)))
-         (query `[:select [file titles]
+         (query `[:select [file title]
                  :from titles
                  :where (in file [,@files])]))
    (org-roam-graph--build query callback)))
--- a/org-roam-link.el
+++ b/org-roam-link.el
@ -0,0 +1,310 @@
+;;; org-roam-link.el --- Custom links for Org-roam -*- coding: utf-8; lexical-binding: t; -*-
+
+;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
+;;                  Alan Carroll
+
+;; Author: Jethro Kuan <jethrokuan95@gmail.com>
+;; URL: https://github.com/org-roam/org-roam
+;; Keywords: org-mode, roam, convenience
+;; Version: 1.2.2
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.2"))
+
+;; This file is NOT part of GNU Emacs.
+
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation; either version 3, or (at your option)
+;; any later version.
+;;
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+;;
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs; see the file COPYING.  If not, write to the
+;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+;; Boston, MA 02110-1301, USA.
+
+;;; Commentary:
+;;
+;; This adds the custom `roam:' link to Org-roam. `roam:' links allow linking to
+;; Org-roam files via their titles and headlines.
+;;
+;;; Code:
+;;;; Dependencies
+
+(require 'ol)
+(require 'org-roam-compat)
+
+(defvar org-roam-completion-ignore-case)
+(defvar org-roam-directory)
+(declare-function  org-roam--find-file                  "org-roam")
+(declare-function  org-roam-find-file                   "org-roam")
+(declare-function org-roam-format-link                  "org-roam")
+
+(defcustom org-roam-link-auto-replace t
+  "When non-nil, replace Org-roam's roam links with file or id links whenever possible."
+  :group 'org-roam
+  :type 'boolean)
+
+(defcustom org-roam-link-file-path-type 'relative
+  "How the path name in file links should be stored.
+Valid values are:
+
+relative  Relative to the current directory, i.e. the directory of the file
+          into which the link is being inserted.
+absolute  Absolute path, if possible with ~ for home directory.
+noabbrev  Absolute path, no abbreviation of home directory."
+  :group 'org-roam
+  :type '(choice
+          (const relative)
+          (const absolute)
+          (const noabbrev))
+  :safe #'symbolp)
+
+;;; the roam: link
+(org-link-set-parameters "roam"
+                         :follow #'org-roam-link-follow-link)
+
+(defun org-roam-link-follow-link (path)
+  "Navigates to location specified by PATH."
+  (pcase-let ((`(,link-type ,loc ,desc ,mkr) (org-roam-link--get-location path)))
+    (when (and org-roam-link-auto-replace loc desc)
+      (org-roam-link--replace-link link-type loc desc))
+    (pcase link-type
+          ("file"
+           (if loc
+               (org-roam--find-file loc)
+             (org-roam-find-file desc nil nil t)))
+          ("id"
+           (org-goto-marker-or-bmk mkr)))))
+
+;;; Retrieval Functions
+(defun org-roam-link--get-titles ()
+  "Return all titles within Org-roam."
+  (mapcar #'car (org-roam-db-query [:select [titles:title] :from titles])))
+
+(defun org-roam-link--get-headlines (&optional file with-marker use-stack)
+  "Return all outline headings for the current buffer.
+If FILE, return outline headings for passed FILE instead.
+If WITH-MARKER, return a cons cell of (headline . marker).
+If USE-STACK, include the parent paths as well."
+  (let* ((buf (or (and file
+                       (or (find-buffer-visiting file)
+                           (find-file-noselect file)))
+                  (current-buffer)))
+         (outline-level-fn outline-level)
+         (path-separator "/")
+         (stack-level 0)
+         stack cands name level marker)
+    (with-current-buffer buf
+      (save-excursion
+        (goto-char (point-min))
+        (while (re-search-forward org-complex-heading-regexp nil t)
+          (save-excursion
+            (setq name (substring-no-properties (or (match-string 4) "")))
+            (setq marker (point-marker))
+            (when use-stack
+              (goto-char (match-beginning 0))
+              (setq level (funcall outline-level-fn))
+              ;; Update stack.  The empty entry guards against incorrect
+              ;; headline hierarchies, e.g. a level 3 headline
+              ;; immediately following a level 1 entry.
+              (while (<= level stack-level)
+                (pop stack)
+                (cl-decf stack-level))
+              (while (> level stack-level)
+                (push name stack)
+                (cl-incf stack-level))
+              (setq name (mapconcat #'identity
+                                    (reverse stack)
+                                    path-separator)))
+            (push (if with-marker
+                      (cons name marker)
+                    name) cands)))))
+    (nreverse cands)))
+
+(defun org-roam-link--get-file-from-title (title &optional no-interactive)
+  "Return the file path corresponding to TITLE.
+When NO-INTERACTIVE, return nil if there are multiple options."
+  (let ((files (mapcar #'car (org-roam-db-query [:select [titles:file] :from titles
+                                                 :where (= titles:title $v1)]
+                                                (vector title)))))
+    (pcase files
+      ('nil nil)
+      (`(,file) file)
+      (_
+       (unless no-interactive
+         (completing-read "Select file: " files))))))
+
+(defun org-roam-link--get-id-from-headline (headline &optional file)
+  "Return (marker . id) correspondng to HEADLINE.
+If FILE, get headline from FILE instead.
+If there is no corresponding headline, return nil."
+  (save-excursion
+    (with-current-buffer (or (and file
+                                  (or (find-buffer-visiting file)
+                                      (find-file-noselect file)))
+                             (current-buffer))
+      (let ((headlines (org-roam-link--get-headlines file 'with-markers)))
+        (when-let ((marker (cdr (assoc-string headline headlines))))
+          (goto-char marker)
+          (cons marker
+                (when org-roam-link-auto-replace
+                  (org-id-get-create))))))))
+
+;;; Path-related functions
+(defun org-roam-link-get-path (path)
+  "Return the PATH of the link to use.
+Respect `org-link-file-path-type', see the variable documentation for details.
+If DIR is passed, use DIR as the default directory."
+  (pcase org-roam-link-file-path-type
+      ('absolute
+       (abbreviate-file-name (expand-file-name path)))
+      ('noabbrev
+       (expand-file-name path))
+      ('relative
+       (file-relative-name path))))
+
+(defun org-roam-link--split-path (path)
+  "Splits PATH into title and headline.
+Return a list of the form (type title has-headline-p headline star-idx).
+type is one of `title', `headline', `title+headline'.
+title is the title component of the path.
+headline is the headline component of the path.
+star-idx is the index of the asterisk, if any."
+  (save-match-data
+    (let* ((star-index (string-match-p "\\*" path))
+           (title (substring-no-properties path 0 star-index))
+           (headline (if star-index
+                         (substring-no-properties path (+ 1 star-index))
+                       ""))
+           (type (cond ((not star-index)
+                        'title)
+                       ((= 0 star-index)
+                        'headline)
+                       (t 'title+headline))))
+      (list type title headline star-index))))
+
+(defun org-roam-link--get-location (link)
+  "Return the location of Org-roam fuzzy LINK.
+The location is returned as a list containing (link-type loc desc marker).
+nil is returned if there is no matching location.
+
+link-type is either \"file\" or \"id\".
+loc is the target location: e.g. a file path, or an id.
+marker is a marker to the headline, if applicable."
+  (let (mkr link-type desc loc)
+    (pcase-let ((`(,type ,title ,headline _) (org-roam-link--split-path link)))
+      (pcase type
+        ('title+headline
+         (let ((file (org-roam-link--get-file-from-title title)))
+           (if (not file)
+               (org-roam-message "Cannot find matching file")
+             (setq mkr (org-roam-link--get-id-from-headline headline file))
+             (pcase mkr
+               (`(,marker . ,target-id)
+                (setq mkr marker
+                      loc target-id
+                      link-type "id"
+                      desc headline))
+               (_ (org-roam-message "cannot find matching id"))))))
+        ('title
+         (setq loc (org-roam-link--get-file-from-title title)
+               desc title
+               link-type "file"))
+        ('headline
+         (setq mkr (org-roam-link--get-id-from-headline headline))
+         (pcase mkr
+           (`(,marker . ,target-id)
+            (setq mkr marker
+                  loc target-id
+                  desc headline
+                  link-type "id"))
+           (_ (org-roam-message "Cannot find matching headline")))))
+      (list link-type loc desc mkr))))
+
+;;; Conversion Functions
+(defun org-roam-link--replace-link (link-type loc &optional desc)
+  "Replace link at point with a vanilla Org link.
+LINK-TYPE is the Org link type, typically \"file\" or \"id\".
+LOC is path for the Org link.
+DESC is the link description."
+  (save-excursion
+    (save-match-data
+      (unless (org-in-regexp org-link-bracket-re 1)
+        (user-error "No link at point"))
+      (replace-match "")
+      (insert (org-roam-format-link loc desc link-type)))))
+
+(defun org-roam-link-replace-all ()
+  "Replace all roam links in the current buffer."
+  (interactive)
+  (save-excursion
+    (goto-char (point-min))
+    (while (re-search-forward org-link-bracket-re nil t)
+      (let ((context (org-element-context)))
+          (pcase (org-element-lineage context '(link) t)
+            (`nil nil)
+            (link
+             (when (string-equal "roam" (org-element-property :type link))
+               (pcase-let ((`(,link-type ,loc ,desc _) (org-roam-link--get-location (org-element-property :path link))))
+                 (when (and link-type loc)
+                   (org-roam-link--replace-link link-type loc desc))))))))))
+
+(defun org-roam-link--replace-link-on-save ()
+  "Hook to replace all roam links on save."
+  (when org-roam-link-auto-replace
+    (org-roam-link-replace-all)))
+
+;;; Completion
+(defun org-roam-link-complete-at-point ()
+  "Do appropriate completion for the link at point."
+  (let ((end (point))
+        (start (point))
+        collection link-type headline-only-p)
+    (when (org-in-regexp org-link-bracket-re 1)
+      (setq start (match-beginning 1)
+            end (match-end 1))
+      (let ((context (org-element-context)))
+        (pcase (org-element-lineage context '(link) t)
+          (`nil nil)
+          (link
+           (setq link-type (org-element-property :type link))
+           (when (member link-type '("roam" "fuzzy"))
+             (when (string= link-type "roam") (setq start (+ start (length "roam:"))))
+             (pcase-let ((`(,type ,title _ ,star-idx)
+                          (org-roam-link--split-path (org-element-property :path link))))
+               (pcase type
+                 ('title+headline
+                  (when-let ((file (org-roam-link--get-file-from-title title t)))
+                    (setq collection (apply-partially #'org-roam-link--get-headlines file))
+                    (setq start (+ start star-idx 1))))
+                 ('title
+                  (setq collection #'org-roam-link--get-titles))
+                 ('headline
+                  (setq collection #'org-roam-link--get-headlines)
+                  (setq start (+ start star-idx 1))
+                  (setq headline-only-p t)))))))))
+    (when collection
+      (let ((prefix (buffer-substring-no-properties start end)))
+        (list start end
+              (if (functionp collection)
+                  (completion-table-case-fold
+                   (completion-table-dynamic
+                    (lambda (_)
+                      (cl-remove-if (apply-partially #'string= prefix)
+                                    (funcall collection))))
+                   (not org-roam-completion-ignore-case))
+                collection)
+              :exit-function
+              (lambda (str &rest _)
+                (delete-char (- 0 (length str)
+                                (if headline-only-p 1 0)))
+                (insert (concat (unless (string= link-type "roam") "roam:")
+                                (when headline-only-p "*")
+                                str))))))))
+
+(provide 'org-roam-link)
+;;; org-roam-link.el ends here
--- a/org-roam-macs.el
+++ b/org-roam-macs.el
@ -5,8 +5,8 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 1.2.0
-;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.0"))
+;; Version: 1.2.2
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.2"))

 ;; This file is NOT part of GNU Emacs.

@ -33,9 +33,19 @@
 ;;
 ;;; Code:
 ;;;; Library Requires
+(require 'dash)

 (defvar org-roam-verbose)

+;;;; Utility Functions
+(defun org-roam--list-interleave (lst separator)
+  "Interleaves elements in LST with SEPARATOR."
+  (when lst
+    (let ((new-lst (list (pop lst))))
+      (dolist (it lst)
+        (nconc new-lst (list separator it)))
+      new-lst)))
+
 (defmacro org-roam--with-temp-buffer (file &rest body)
  "Execute BODY within a temp buffer.
 Like `with-temp-buffer', but propagates `org-roam-directory'.
@ -44,30 +54,48 @@ If FILE, set `org-roam-temp-file-name' to file and insert its contents."
  (let ((current-org-roam-directory (make-symbol "current-org-roam-directory")))
    `(let ((,current-org-roam-directory org-roam-directory))
       (with-temp-buffer
-         (let ((org-roam-directory ,current-org-roam-directory))
+         (let ((org-roam-directory ,current-org-roam-directory)
+               (org-mode-hook nil)
+               (org-inhibit-startup t))
+           (org-mode)
           (when ,file
             (insert-file-contents ,file)
             (setq-local org-roam-file-name ,file))
           ,@body)))))

-(defmacro org-roam--with-template-error (templates &rest body)
-  "Eval BODY, and point to TEMPLATES on error.
-Provides more informative error messages so that users know where
-to look.
-
-\(fn TEMPLATES BODY...)"
-  (declare (debug (form body)) (indent 1))
-  `(condition-case err
-       ,@body
-     (error (user-error "%s.  Please adjust `%s'"
-                        (error-message-string err)
-                        ,templates))))
-
 (defun org-roam-message (format-string &rest args)
  "Pass FORMAT-STRING and ARGS to `message' when `org-roam-verbose' is t."
  (when org-roam-verbose
    (apply #'message `(,(concat "(org-roam) " format-string) ,@args))))

+(defun org-roam-string-quote (str)
+  "Quote STR."
+  (->> str
+       (s-replace "\\" "\\\\")
+       (s-replace "\"" "\\\"")))
+
+;;; Shielding regions
+(defun org-roam-shield-region (beg end)
+  "Shield REGION against modifications.
+REGION must be a cons-cell containing the marker to the region
+beginning and maximum values."
+  (when (and beg end)
+    (add-text-properties beg end
+                           '(font-lock-face org-roam-link-shielded
+                                            read-only t)
+                           (marker-buffer beg))
+    (cons beg end)))
+
+(defun org-roam-unshield-region (beg end)
+  "Unshield the shielded REGION."
+  (when (and beg end)
+    (let ((inhibit-read-only t))
+      (remove-text-properties beg end
+                              '(font-lock-face org-roam-link-shielded
+                                               read-only t)
+                              (marker-buffer beg)))
+    (cons beg end)))
+
 (provide 'org-roam-macs)

 ;;; org-roam-macs.el ends here
--- a/org-roam-protocol.el
+++ b/org-roam-protocol.el
@ -4,7 +4,7 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 1.2.0
+;; Version: 1.2.2
 ;; Package-Requires: ((emacs "26.1") (org "9.3"))

 ;; This file is NOT part of GNU Emacs.
@ -37,6 +37,7 @@
 ;;; Code:
 (require 'org-protocol)
 (require 'org-roam)
+(require 'ol) ;; for org-link-decode

 ;;;; Functions
 (defun org-roam-protocol-open-ref (info)
@ -56,14 +57,13 @@ It opens or creates a note with the given ref.
    (unless (assoc 'ref decoded-alist)
      (error "No ref key provided"))
    (when-let ((title (cdr (assoc 'title decoded-alist))))
-      (push (cons 'slug (org-roam--title-to-slug title)) decoded-alist))
+      (push (cons 'slug (funcall org-roam-title-to-slug-function title)) decoded-alist))
    (let* ((org-roam-capture-templates org-roam-capture-ref-templates)
           (org-roam-capture--context 'ref)
           (org-roam-capture--info decoded-alist)
           (template (cdr (assoc 'template decoded-alist))))
      (raise-frame)
-      (org-roam--with-template-error 'org-roam-capture-ref-templates
-        (org-roam-capture--capture nil template))
+      (org-roam-capture--capture nil template)
      (org-roam-message "Item captured.")))
  nil)

@ -78,7 +78,7 @@ It should contain the FILE key, pointing to the path of the file to open.
 org-protocol://roam-file?file=/path/to/file.org"
  (when-let ((file (plist-get info :file)))
    (raise-frame)
-    (find-file file))
+    (org-roam--find-file file))
  nil)

 (push '("org-roam-ref"  :protocol "roam-ref"   :function org-roam-protocol-open-ref)
--- a/org-roam.el
+++ b/org-roam.el
--- a/tests/roam-files/headlines/headline.org
+++ b/tests/roam-files/headlines/headline.org
@ -0,0 +1,14 @@
+#+TITLE: Headline
+
+* Headline 1
+:PROPERTIES:
+:ID:       e84d0630-efad-4017-9059-5ef917908823
+:END:
+
+* No headline here
+Oops.
+
+* Headline 2
+:PROPERTIES:
+:ID:       801b58eb-97e2-435f-a33e-ff59a2f0c213
+:END:
--- a/tests/test-org-roam-perf.el
+++ b/tests/test-org-roam-perf.el
@ -0,0 +1,53 @@
+;;; test-org-roam-perf.el --- Performance Tests for Org-roam -*- lexical-binding: t; -*-
+
+;; Copyright (C) 2020 Jethro Kuan
+
+;; Author: Jethro Kuan <jethrokuan95@gmail.com>
+;; Package-Requires: ((buttercup))
+
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+;;; Code:
+
+(require 'buttercup)
+(require 'org-roam)
+
+(defconst test-org-roam-perf-zip-url "https://github.com/org-roam/test-org-files/archive/master.zip"
+  "Path to zip for test org-roam files.")
+
+(defun test-org-roam-perf--abs-path (file-path)
+  "Get absolute FILE-PATH from `org-roam-directory'."
+  (expand-file-name file-path org-roam-directory))
+
+(defun test-org-roam-perf--init ()
+  "."
+  (let* ((temp-loc (expand-file-name (make-temp-name "test-org-files-") temporary-file-directory))
+         (zip-file-loc (concat temp-loc ".zip"))
+         (_ (url-copy-file test-org-roam-perf-zip-url zip-file-loc))
+         (_ (shell-command (format "mkdir -p %s && unzip -j -qq %s -d %s" temp-loc zip-file-loc temp-loc))))
+    (setq org-roam-directory temp-loc)))
+
+(describe "Cache Build"
+  (it "cache build from scratch time to be acceptable"
+    (test-org-roam-perf--init)
+    (pcase (benchmark-run 1 (org-roam-db-build-cache t))
+      (`(,time ,gcs ,time-in-gc)
+       (message "Elapsed time: %fs (%fs in %d GCs)" time time-in-gc gcs)
+       (expect time :to-be-less-than 90))))
+  (it "builds quickly without change"
+    (pcase (benchmark-run 1 (org-roam-db-build-cache))
+      (`(,time ,gcs ,time-in-gc)
+       (message "Elapsed time: %fs (%fs in %d GCs)" time time-in-gc gcs)
+       (expect time :to-be-less-than 5)))))
--- a/tests/test-org-roam.el
+++ b/tests/test-org-roam.el
@ -3,7 +3,7 @@
 ;; Copyright (C) 2020 Jethro Kuan

 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
-;; Package-Requires: ((buttercup) (with-simulated-input))
+;; Package-Requires: ((buttercup))

 ;; This program is free software; you can redistribute it and/or modify
 ;; it under the terms of the GNU General Public License as published by
@ -27,7 +27,7 @@

 (defun test-org-roam--abs-path (file-path)
  "Get absolute FILE-PATH from `org-roam-directory'."
-  (file-truename (expand-file-name file-path org-roam-directory)))
+  (expand-file-name file-path org-roam-directory))

 (defun test-org-roam--find-file (path)
  "PATH."
@ -35,7 +35,7 @@
    (make-directory (file-name-directory path) t)
    (find-file path)))

-(defvar test-org-roam-directory (file-truename (concat default-directory "tests/roam-files"))
+(defvar test-org-roam-directory (expand-file-name "tests/roam-files")
  "Directory containing org-roam test org files.")

 (defun test-org-roam--init ()
@ -49,7 +49,7 @@

 (defun test-org-roam--teardown ()
  (org-roam-mode -1)
-  (delete-file (org-roam-db--get))
+  (delete-file org-roam-db-location)
  (org-roam-db--close))

 (describe "org-roam--str-to-list"
@ -211,6 +211,20 @@
              :to-equal
              '("deeply")))

+    (it "extracts from first directory"
+      (expect (test #'org-roam--extract-tags-first-directory
+                    "base.org")
+              :to-equal
+              nil)
+      (expect (test #'org-roam--extract-tags-first-directory
+                    "tags/tag.org")
+              :to-equal
+              '("tags"))
+      (expect (test #'org-roam--extract-tags-first-directory
+                    "nested/deeply/deeply_nested_file.org")
+              :to-equal
+              '("nested")))
+
    (describe "uses org-roam-tag-sources correctly"
      (it "'(prop)"
        (expect (let ((org-roam-tag-sources '(prop)))
@ -225,6 +239,48 @@
                :to-equal
                '("t1" "t2 with space" "t3" "tags"))))))

+(describe "ID extraction"
+  (before-all
+    (test-org-roam--init))
+
+  (after-all
+    (test-org-roam--teardown))
+
+  (cl-flet
+      ((test (fn file)
+             (let* ((fname (test-org-roam--abs-path file))
+                    (buf (find-file-noselect fname)))
+               (with-current-buffer buf
+                 (funcall fn fname)))))
+    (it "extracts ids"
+      (expect (test #'org-roam--extract-ids
+                    "headlines/headline.org")
+              :to-have-same-items-as
+              `(["e84d0630-efad-4017-9059-5ef917908823" ,(test-org-roam--abs-path "headlines/headline.org") 1]
+                ["801b58eb-97e2-435f-a33e-ff59a2f0c213" ,(test-org-roam--abs-path "headlines/headline.org") 1])))))
+
+(describe "Test roam links"
+  (it ""
+    (expect (org-roam-link--split-path "")
+            :to-equal
+            '(title "" "" nil)))
+  (it "title"
+    (expect (org-roam-link--split-path "title")
+            :to-equal
+            '(title "title" "" nil)))
+  (it "title*"
+    (expect (org-roam-link--split-path "title*")
+            :to-equal
+            '(title+headline "title" "" 5)))
+  (it "title*headline"
+    (expect (org-roam-link--split-path "title*headline")
+            :to-equal
+            '(title+headline "title" "headline" 5)))
+  (it "*headline"
+    (expect (org-roam-link--split-path "*headline")
+            :to-equal
+            '(headline "" "headline" 0))))
+
 ;;; Tests
 (xdescribe "org-roam-db-build-cache"
  (before-each