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

* remove org-roam-link-make-string
* remove org-roam-link-store-props and org-roam-link-decode

.readthedocs.yml

@@ -1,8 +0,0 @@
-version: 2
-mkdocs:
- configuration: mkdocs.yml
-formats: all
-python:
-  version: 3.7
-  install:
-    - requirements: doc/requirements.txt

CHANGELOG.md

@@ -1,16 +1,43 @@
 # Changelog
 
-## 1.2.2 (TBD)
+## 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.
@@ -21,9 +48,11 @@ We also added some new features that had been a long time coming:
 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`
@@ -65,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

README.md

@@ -63,7 +63,7 @@ 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-graph-show))
+               ("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-immediate))))

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>

doc/org-roam.org

@@ -8,13 +8,13 @@
 #+texinfo_dir_category: Emacs
 #+texinfo_dir_title: Org-roam: (org-roam).
 #+texinfo_dir_desc: Rudimentary Roam Replica for Emacs.
-#+subtitle: for version 1.2.1
+#+subtitle: for version 1.2.2
 
 #+options: H:4 num:3 toc:2 creator:t
 #+property: header-args :eval never
 #+texinfo: @noindent
 
-This manual is for Org-roam version 1.2.1.
+This manual is for Org-roam version 1.2.2.
 
 #+BEGIN_QUOTE
 Copyright (C) 2020-2020 Jethro Kuan <jethrokuan95@gmail.com>
@@ -195,7 +195,67 @@ using Apt:
 
 Org-roam will then be autoloaded into Emacs.
 
-** TODO Installing from the Git Repository
+** Installing from the Git Repository
+
+You may install Org-roam directly from the repository on [[https://github.com/org-roam/org-roam][GitHub]] if you like. This will give you access to the latest version hours or days before it appears on MELPA, and months (or more) before it is added to the Debian or Ubuntu repositories. This will also give you access to various developmental branches that may be available. 
+
+Note, however, that development version, and especially any feature branches, may not always be in working order. You'll need to be prepared to do some debugging, or to manually roll-back to working versions, if you install from GitHub.
+
+Installing from GitHub requires that you clone the repository:
+
+#+begin_src bash
+git clone https://github.com/org-roam/org-roam.git /path/to/org/roam
+#+end_src
+
+where ~./path/to/org/roam~ is the location you will store your copy of the code.
+
+Next, you need to add this location to your load path, and ~require~ the Org-roam library. Add the following code to your ~.emacs~:
+
+#+begin_src elisp
+(add-to-list 'load-path "/path/to/org/roam")
+(require 'org-roam)
+#+end_src
+
+You now have Org-roam installed. However, you don't necessarily have the dependencies that it requires. These include:
+
+- dash
+- f
+- s
+- org
+- emacsql
+- emacsql-sqlite3
+
+You can install this manually as well, or get the latest version from MELPA. You may wish to use [[https://github.com/jwiegley/use-package][use-package]], [[https://github.com/raxod502/straight.el][straight.el]], or some other tool or tools to help manage this.
+
+If you would like to install the manual for access from Emacs' built-in Info system, you'll need to compile the .texi source file, and install it in an appropriate location.
+
+To compile the .texi source file, from a terminal navigate to the ~/doc~ subdirectory of the Org-roam repository, and run the following:
+
+#+begin_src bash
+make infodir=/path/to/my/info/files install-info
+#+end_src
+
+Where ~/path/to/my/info/files~ is the location where you keep info files. This target directory needs to be stored in the variable `Info-default-directory-list`. If you aren't using one of the default info locations, you can configure this with the following in your ~.emacs~ file:
+
+#+begin_src elisp
+(require 'info)
+(add-to-list 'Info-default-directory-list
+	     "/path/to/my/info/files")
+#+end_src
+
+You can also use one of the default locations, such as:
+
+- /usr/local/share/info/
+- /usr/share/info/
+- /usr/local/share/info/
+
+If you do this, you'll need to make sure you have write-access to that location, or run the above ~make~ command as root.
+
+Now that the info file is ready, you need to add it to the corresponding ~dir~ file:
+
+#+begin_src bash
+install-info /path/to/my/info/files/org-roam.info /path/to/my/info/files/dir
+#+end_src
 
 ** Post-Installation Tasks
 
@@ -513,6 +573,10 @@ This section concerns the placement and creation of files.
   It is the user’s responsibility to set this correctly, especially when used
   with multiple Org-roam instances.
 
+- Variable: org-roam-file-exclude-regexp
+
+  Files matching this regular expression are excluded from the Org-roam.
+
 ** The Org-roam Buffer
 
 The Org-roam buffer displays backlinks for the currently active Org-roam note.
@@ -540,10 +604,46 @@ The Org-roam buffer displays backlinks for the currently active Org-roam note.
 
   The ~no-delete-window~ parameter for the org-roam buffer. Setting it to ~'t~ prevents the window from being deleted when calling ~delete-other-windows~.
 
-** Org-roam Links
+** Org-roam Files
 
-Org-roam links are regular ~file:~ links in Org-mode. By default, links are
-inserted with the title as the link description with ~org-roam-insert~.
+Org-roam files are created and prefilled using Org-roam's templating
+system. The templating system is customizable (see [[*The Templating System][The Templating System]]).
+
+* Inserting Links
+
+The preferred mode of linking is via ~file~ links to files, and ~id~ links for
+headlines. This maintains the strongest compatibility with Org-mode, ensuring
+that the links still function without Org-roam, and work well exporting to other
+backends.
+
+~file~ links can be inserted via ~org-roam-insert~. Links to headlines can be
+inserted by navigating to the desired headline and calling ~org-store-link~.
+This will create an ID for the headline if it does not already exist, and
+populate the Org-roam database. The link can then be inserted via
+~org-insert-link~.
+
+An alternative mode of insertion is using Org-roam's ~roam~ links. Org-roam
+registers this link type, and interprets the path as follows:
+
+- ~[[roam:title]]~ :: links to an Org-roam file with title or alias "title"
+- ~[[roam:*headline]]~ :: links to the headline "headline" in the current Org-roam file
+- ~[[roam:title*headline]]~ :: links to the headline "headline" in the Org-roam file with title or alias "title"
+
+~roam~ links support auto-completion via ~completion-at-point~: simply call
+~completion-at-point~ within a roam link. Users of ~company-mode~ may want to
+prepend ~company-capf~ to the beginning of variable ~company-backends~.
+
+To easily insert ~roam~ links, one may wish to use a package like [[https://github.com/emacsorphanage/key-chord/][key-chord]]. In the following example, typing "[[" will insert a stub ~roam~ link:
+
+#+BEGIN_SRC emacs-lisp
+(key-chord-define org-mode-map "[[" #'my/insert-roam-link)
+
+(defun my/insert-roam-link ()
+    "Inserts an Org-roam link."
+    (interactive)
+    (insert "[[roam:]]")
+    (backward-char 2))
+#+END_SRC
 
 - User Option: org-roam-link-title-format
 
@@ -553,10 +653,18 @@ inserted with the title as the link description with ~org-roam-insert~.
   If your version of Org is at least ~9.2~, consider styling the link differently,
   by customizing the ~org-roam-link~, and ~org-roam-link-current~ faces.
 
-** Org-roam Files
+- User Option: org-roam-completion-ignore-case
 
-Org-roam files are created and prefilled using Org-roam's templating
-system. The templating system is customizable (see [[*The Templating System][The Templating System]]).
+  When non-nil, the ~roam~ link completions are ignore case. For example,
+  calling ~completion-at-point~ within ~[[roam:fo]]~ will present a completion
+  for a file with title "Foo". Defaults to ~t~.
+
+- User Option: org-roam-link-auto-replace
+
+  When non-nil, ~roam~ links will be replaced with ~file~ or ~id~ links when
+  they are navigated to, and on file save, when a match is found. This is
+  desirable to maintain compatibility with vanilla Org, but resolved links are
+  harder to edit. Defaults to ~t~.
 
 * Navigating Around
 
@@ -915,6 +1023,20 @@ checker, to perform autofixes for the errors. For each error detected,
 ~org-roam-doctor~ will move the point to the current error, and pop-up a help
 window displaying the error message, as well as the list of actions that can be
 taken provided in ~:actions~.
+
+* Finding Unlinked References
+
+Unlinked references are occurrences of strings of text that exactly match the
+title or alias of an existing note in the Org-roam database. Org-roam provides
+facilities for discovering these unlinked references, so one may decide whether
+to convert them into links.
+
+To use this feature, simply call ~M-x org-roam-unlinked-references~ from within
+an Org-roam note. Org-roam uses [[https://github.com/BurntSushi/ripgrep][ripgrep]], specifically a clever PCRE regex to
+find occurrences of the title or aliases of the currently open note in all
+Org-roam files. This thus requires a version of ripgrep that is compiled with
+PCRE support.
+
 * Performance Optimization
 ** TODO Profiling Key Operations
 ** Garbage Collection
@@ -1136,7 +1258,7 @@ tight integration between
     :CUSTOM_ID: spaced-repetition
     :END:
 
-[[https://github.com/l3kn/org-fc/][Org-fc]] is a spaced repetition system that scales well with a large number of
+[[https://www.leonrische.me/fc/index.html][Org-fc]] is a spaced repetition system that scales well with a large number of
 files. Other alternatives include [[https://orgmode.org/worg/org-contrib/org-drill.html][org-drill]], and [[https://github.com/abo-abo/pamparam][pamparam]].
 
 * FAQ
@@ -1151,7 +1273,8 @@ variable using directory-local variables. This is what ~.dir-locals.el~ may
 contain:
 
 #+BEGIN_SRC emacs-lisp
-  ((nil . ((org-roam-directory . "/path/to/here/"))))
+    ((nil . ((org-roam-directory . ".")
+             (org-roam-db-location . "./org-roam.db"))))
 #+END_SRC
 
 All files within that directory will be treated as their own separate
@@ -1162,6 +1285,17 @@ file within that directory, at least once.
 
 Fabio has produced a command-line tool that converts markdown files exported from Roam Research into Org-roam compatible markdown. More instructions are provided [[https://github.com/fabioberger/roam-migration][in the repository]].
 
+** How do I create a note whose title already matches one of the candidates?
+
+This situation arises when, for example, one would like to create a note titled
+"bar" when "barricade" already exists.
+
+The solution is dependent on the mini-buffer completion framework in use. Here
+are the solutions:
+
+- Ivy :: call ~ivy-immediate-done~, typically bound to ~C-M-j~. Alternatively, set ~ivy-use-selectable-prompt~ to ~t~, so that "bar" is now selectable.
+- Helm :: Org-roam should provide a selectable "[?] bar" candidate at the top of the candidate list.
+
 # Local Variables:
 # eval: (require 'ol-info)
 # before-save-hook: org-make-toc

doc/org-roam.texi

@@ -31,7 +31,7 @@ General Public License for more details.
 @finalout
 @titlepage
 @title Org-roam User Manual
-@subtitle for version 1.2.1
+@subtitle for version 1.2.2
 @author Jethro Kuan
 @page
 @vskip 0pt plus 1filll
@@ -46,7 +46,7 @@ General Public License for more details.
 
 @noindent
 
-This manual is for Org-roam version 1.2.1.
+This manual is for Org-roam version 1.2.2.
 
 @quotation
 Copyright (C) 2020-2020 Jethro Kuan <jethrokuan95@@gmail.com>
@@ -72,6 +72,7 @@ General Public License for more details.
 * Anatomy of an Org-roam File::
 * The Templating System::
 * Concepts and Configuration::
+* Inserting Links::
 * Navigating Around::
 * Encryption::
 * Graphing::
@@ -79,6 +80,7 @@ General Public License for more details.
 * Roam Protocol::
 * Daily Notes::
 * Diagnosing and Repairing Files::
+* Finding Unlinked References::
 * Performance Optimization::
 * Appendix::
 * FAQ::
@@ -108,7 +110,6 @@ Concepts and Configuration
 
 * Directories and Files::
 * The Org-roam Buffer::
-* Org-roam Links::
 * Org-roam Files::
 
 Navigating Around
@@ -150,6 +151,7 @@ FAQ
 
 * How do I have more than one Org-roam directory?::
 * How do I migrate from Roam Research?::
+* How do I create a note whose title already matches one of the candidates?::
 
 @end detailmenu
 @end menu
@@ -346,7 +348,80 @@ apt-get install elpa-org-roam
 Org-roam will then be autoloaded into Emacs.
 
 @node Installing from the Git Repository
-@section @strong{TODO} Installing from the Git Repository
+@section Installing from the Git Repository
+
+You may install Org-roam directly from the repository on @uref{https://github.com/org-roam/org-roam, GitHub} if you like. This will give you access to the latest version hours or days before it appears on MELPA, and months (or more) before it is added to the Debian or Ubuntu repositories. This will also give you access to various developmental branches that may be available. 
+
+Note, however, that development version, and especially any feature branches, may not always be in working order. You'll need to be prepared to do some debugging, or to manually roll-back to working versions, if you install from GitHub.
+
+Installing from GitHub requires that you clone the repository:
+
+@example
+git clone https://github.com/org-roam/org-roam.git /path/to/org/roam
+@end example
+
+where @code{./path/to/org/roam} is the location you will store your copy of the code.
+
+Next, you need to add this location to your load path, and @code{require} the Org-roam library. Add the following code to your @code{.emacs}:
+
+@lisp
+(add-to-list 'load-path "/path/to/org/roam")
+(require 'org-roam)
+@end lisp
+
+You now have Org-roam installed. However, you don't necessarily have the dependencies that it requires. These include:
+
+@itemize
+@item
+dash
+@item
+f
+@item
+s
+@item
+org
+@item
+emacsql
+@item
+emacsql-sqlite3
+@end itemize
+
+You can install this manually as well, or get the latest version from MELPA@. You may wish to use @uref{https://github.com/jwiegley/use-package, use-package}, @uref{https://github.com/raxod502/straight.el, straight.el}, or some other tool or tools to help manage this.
+
+If you would like to install the manual for access from Emacs' built-in Info system, you'll need to compile the .texi source file, and install it in an appropriate location.
+
+To compile the .texi source file, from a terminal navigate to the @code{/doc} subdirectory of the Org-roam repository, and run the following:
+
+@example
+make infodir=/path/to/my/info/files install-info
+@end example
+
+Where @code{/path/to/my/info/files} is the location where you keep info files. This target directory needs to be stored in the variable `Info-default-directory-list`. If you aren't using one of the default info locations, you can configure this with the following in your @code{.emacs} file:
+
+@lisp
+(require 'info)
+(add-to-list 'Info-default-directory-list
+         "/path/to/my/info/files")
+@end lisp
+
+You can also use one of the default locations, such as:
+
+@itemize
+@item
+@emph{usr/local/share/info}
+@item
+@emph{usr/share/info}
+@item
+@emph{usr/local/share/info}
+@end itemize
+
+If you do this, you'll need to make sure you have write-access to that location, or run the above @code{make} command as root.
+
+Now that the info file is ready, you need to add it to the corresponding @code{dir} file:
+
+@example
+install-info /path/to/my/info/files/org-roam.info /path/to/my/info/files/dir
+@end example
 
 @node Post-Installation Tasks
 @section Post-Installation Tasks
@@ -707,7 +782,6 @@ All of Org-roam's customization options can be viewed via
 @menu
 * Directories and Files::
 * The Org-roam Buffer::
-* Org-roam Links::
 * Org-roam Files::
 @end menu
 
@@ -731,6 +805,11 @@ database is saved here.
 
 It is the user’s responsibility to set this correctly, especially when used
 with multiple Org-roam instances.
+
+@item
+Variable: org-roam-file-exclude-regexp
+
+Files matching this regular expression are excluded from the Org-roam.
 @end itemize
 
 @node The Org-roam Buffer
@@ -768,11 +847,53 @@ User Option: org-roam-buffer-no-delete-other-windows
 The @code{no-delete-window} parameter for the org-roam buffer. Setting it to @code{'t} prevents the window from being deleted when calling @code{delete-other-windows}.
 @end itemize
 
-@node Org-roam Links
-@section Org-roam Links
+@node Org-roam Files
+@section Org-roam Files
 
-Org-roam links are regular @code{file:} links in Org-mode. By default, links are
-inserted with the title as the link description with @code{org-roam-insert}.
+Org-roam files are created and prefilled using Org-roam's templating
+system. The templating system is customizable (see @ref{The Templating System}).
+
+@node Inserting Links
+@chapter Inserting Links
+
+The preferred mode of linking is via @code{file} links to files, and @code{id} links for
+headlines. This maintains the strongest compatibility with Org-mode, ensuring
+that the links still function without Org-roam, and work well exporting to other
+backends.
+
+@code{file} links can be inserted via @code{org-roam-insert}. Links to headlines can be
+inserted by navigating to the desired headline and calling @code{org-store-link}.
+This will create an ID for the headline if it does not already exist, and
+populate the Org-roam database. The link can then be inserted via
+@code{org-insert-link}.
+
+An alternative mode of insertion is using Org-roam's @code{roam} links. Org-roam
+registers this link type, and interprets the path as follows:
+
+@table @asis
+@item @code{[[roam:title]]}
+links to an Org-roam file with title or alias ``title''
+@item @code{[[roam:*headline]]}
+links to the headline ``headline'' in the current Org-roam file
+@item @code{[[roam:title*headline]]}
+links to the headline ``headline'' in the Org-roam file with title or alias ``title''
+@end table
+
+@code{roam} links support auto-completion via @code{completion-at-point}: simply call
+@code{completion-at-point} within a roam link. Users of @code{company-mode} may want to
+prepend @code{company-capf} to the beginning of variable @code{company-backends}.
+
+To easily insert @code{roam} links, one may wish to use a package like @uref{https://github.com/emacsorphanage/key-chord/, key-chord}. In the following example, typing ``[['' will insert a stub @code{roam} link:
+
+@lisp
+(key-chord-define org-mode-map "[[" #'my/insert-roam-link)
+
+(defun my/insert-roam-link ()
+    "Inserts an Org-roam link."
+    (interactive)
+    (insert "[[roam:]]")
+    (backward-char 2))
+@end lisp
 
 @itemize
 @item
@@ -783,14 +904,23 @@ special indicators for Org-roam links. Defaults to @code{"%s"}.
 
 If your version of Org is at least @code{9.2}, consider styling the link differently,
 by customizing the @code{org-roam-link}, and @code{org-roam-link-current} faces.
+
+@item
+User Option: org-roam-completion-ignore-case
+
+When non-nil, the @code{roam} link completions are ignore case. For example,
+calling @code{completion-at-point} within @code{[[roam:fo]]} will present a completion
+for a file with title ``Foo''. Defaults to @code{t}.
+
+@item
+User Option: org-roam-link-auto-replace
+
+When non-nil, @code{roam} links will be replaced with @code{file} or @code{id} links when
+they are navigated to, and on file save, when a match is found. This is
+desirable to maintain compatibility with vanilla Org, but resolved links are
+harder to edit. Defaults to @code{t}.
 @end itemize
 
-@node Org-roam Files
-@section Org-roam Files
-
-Org-roam files are created and prefilled using Org-roam's templating
-system. The templating system is customizable (see @ref{The Templating System}).
-
 @node Navigating Around
 @chapter Navigating Around
 
@@ -1227,6 +1357,20 @@ checker, to perform autofixes for the errors. For each error detected,
 window displaying the error message, as well as the list of actions that can be
 taken provided in @code{:actions}.
 
+@node Finding Unlinked References
+@chapter Finding Unlinked References
+
+Unlinked references are occurrences of strings of text that exactly match the
+title or alias of an existing note in the Org-roam database. Org-roam provides
+facilities for discovering these unlinked references, so one may decide whether
+to convert them into links.
+
+To use this feature, simply call @code{M-x org-roam-unlinked-references} from within
+an Org-roam note. Org-roam uses @uref{https://github.com/BurntSushi/ripgrep, ripgrep}, specifically a clever PCRE regex to
+find occurrences of the title or aliases of the currently open note in all
+Org-roam files. This thus requires a version of ripgrep that is compiled with
+PCRE support.
+
 @node Performance Optimization
 @chapter Performance Optimization
 
@@ -1475,7 +1619,7 @@ tight integration between
 @node Spaced Repetition
 @unnumberedsubsubsec Spaced Repetition
 
-@uref{https://github.com/l3kn/org-fc/, Org-fc} is a spaced repetition system that scales well with a large number of
+@uref{https://www.leonrische.me/fc/index.html, Org-fc} is a spaced repetition system that scales well with a large number of
 files. Other alternatives include @uref{https://orgmode.org/worg/org-contrib/org-drill.html, org-drill}, and @uref{https://github.com/abo-abo/pamparam, pamparam}.
 
 @node FAQ
@@ -1484,6 +1628,7 @@ files. Other alternatives include @uref{https://orgmode.org/worg/org-contrib/org
 @menu
 * How do I have more than one Org-roam directory?::
 * How do I migrate from Roam Research?::
+* How do I create a note whose title already matches one of the candidates?::
 @end menu
 
 @node How do I have more than one Org-roam directory?
@@ -1498,7 +1643,8 @@ variable using directory-local variables. This is what @code{.dir-locals.el} may
 contain:
 
 @lisp
-((nil . ((org-roam-directory . "/path/to/here/"))))
+((nil . ((org-roam-directory . ".")
+         (org-roam-db-location . "./org-roam.db"))))
 @end lisp
 
 All files within that directory will be treated as their own separate
@@ -1510,5 +1656,21 @@ file within that directory, at least once.
 
 Fabio has produced a command-line tool that converts markdown files exported from Roam Research into Org-roam compatible markdown. More instructions are provided @uref{https://github.com/fabioberger/roam-migration, in the repository}.
 
+@node How do I create a note whose title already matches one of the candidates?
+@section How do I create a note whose title already matches one of the candidates?
+
+This situation arises when, for example, one would like to create a note titled
+``bar'' when ``barricade'' already exists.
+
+The solution is dependent on the mini-buffer completion framework in use. Here
+are the solutions:
+
+@table @asis
+@item Ivy
+call @code{ivy-immediate-done}, typically bound to @code{C-M-j}. Alternatively, set @code{ivy-use-selectable-prompt} to @code{t}, so that ``bar'' is now selectable.
+@item Helm
+Org-roam should provide a selectable ``[?] bar'' candidate at the top of the candidate list.
+@end table
+
 Emacs 28.0.50 (Org mode 9.4)
 @bye

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

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.1
-;; 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,14 +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.
@@ -100,6 +106,7 @@ For example: (setq org-roam-buffer-window-parameters '((no-other-window . t)))"
 
 (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))
@@ -123,12 +130,28 @@ For example: (setq org-roam-buffer-window-parameters '((no-other-window . t)))"
                                    ,wrong-type))))))
     (concat string (when (> l 1) "s"))))
 
+(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 ((ref (cdr (with-temp-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 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)))
@@ -137,12 +160,13 @@ For example: (setq org-roam-buffer-window-parameters '((no-other-window . t)))"
           (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 (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)))
@@ -152,7 +176,9 @@ For example: (setq org-roam-buffer-window-parameters '((no-other-window . t)))"
 (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)))
@@ -160,24 +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))
+                (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)))
-                            (string-join outline " > ")
+                          (-> outline
+                              (string-join " > ")
+                              (org-roam-buffer-expand-links file-from))
                         "Top")
                       "\n"
                       (propertize
                        (s-trim (s-replace "\n" " "
-                                            (plist-get props :content)))
+                                          (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"))))))
+                      "\n\n")))))
     (insert "\n\n* No backlinks!")))
 
 (defun org-roam-buffer-update ()
@@ -216,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))))
 

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.1
-;; 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.
 
@@ -45,16 +45,10 @@
 (declare-function  org-roam--get-ref-path-completions   "org-roam")
 (declare-function  org-roam--file-path-from-id          "org-roam")
 (declare-function  org-roam--find-file                  "org-roam")
-(declare-function  org-roam--format-link                "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.")
@@ -340,11 +334,12 @@ the capture)."
              (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))
+                   (insert (org-roam-format-link path desc type))
                  (org-with-point-at mkr
-                   (insert (org-roam--format-link path desc))))))))))
+                   (insert (org-roam-format-link path desc type))))))))))
     (when region
       (set-marker beg nil)
       (set-marker end nil))
@@ -413,13 +408,11 @@ aborted, we do the following:
 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)))
          (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)
@@ -493,6 +486,9 @@ 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))))
@@ -525,10 +521,11 @@ GOTO and KEYS argument have the same functionality as
       (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))
   (let* ((completions (org-roam--get-title-path-completions))
          (title-with-keys (org-roam-completion--completing-read "File: "
@@ -541,7 +538,7 @@ This uses the templates defined at `org-roam-capture-templates'."
                                         (cons 'file file-path)))
           (org-roam-capture--context '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)))))))
 

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.1
-;; 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
@@ -82,9 +80,6 @@
 (define-obsolete-function-alias 'org-roam-db--clear 'org-roam-db-clear
   "org-roam 1.2.0")
 
-(when (version< (org-version) "9.3")
-  (defalias 'org-link-make-string 'org-make-link-string))
-
 ;;;; Variables
 (define-obsolete-variable-alias 'org-roam-graphviz-extra-options
   'org-roam-graph-extra-config "org-roam 1.0.0")

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.1
-;; 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."

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.1
-;; 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.
 
@@ -104,8 +104,7 @@ Template string   :\n%v")
         (org-roam-capture--info (list (cons 'time time)))
         (org-roam-capture--context 'dailies))
     (setq org-roam-capture-additional-template-props (list :finalize 'find-file))
-    (org-roam--with-template-error 'org-roam-dailies-capture-templates
-      (org-roam-capture--capture))))
+    (org-roam-capture--capture)))
 
 (defun org-roam-dailies-today ()
   "Create and find the daily note for today."

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.1
-;; 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,7 +47,7 @@
 (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")
@@ -53,7 +55,7 @@
 (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.
 
@@ -77,20 +79,16 @@ value like `most-positive-fixnum'."
   :type 'int
   :group 'org-roam)
 
-(defconst org-roam-db--version 7)
+(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 ()
@@ -99,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
@@ -138,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)
@@ -197,7 +195,7 @@ the current `org-roam-directory'."
 ;;;;; Initialization
 (defun org-roam-db--initialized-p ()
   "Whether the Org-roam cache has been initialized."
-  (and (file-exists-p (org-roam-db--get))
+  (and (file-exists-p org-roam-db-location)
        (> (caar (org-roam-db-query [:select (funcall count) :from titles]))
           0)))
 
@@ -210,14 +208,14 @@ the current `org-roam-directory'."
 (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
+  (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
@@ -247,25 +245,25 @@ This is equivalent to removing the node from the graph."
    (mapcar (lambda (title)
              (vector file title)) titles)))
 
-(defun org-roam-db--insert-headlines (headlines)
-  "Insert HEADLINES into the Org-roam cache.
+(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 headlines
+         [:insert :into ids
           :values $v1]
-           headlines)
+         ids)
         t)
     (error
-     (unless (listp headlines)
-       (setq headlines (list headlines)))
+     (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 headlines) 1)
+                    (aref (car ids) 1)
                     (string-join (mapcar (lambda (hl)
-                                           (aref hl 0)) headlines) "\n")))
+                                           (aref hl 0)) ids) "\n")))
      nil)))
 
 (defun org-roam-db--insert-tags (file tags)
@@ -314,12 +312,22 @@ Insertions can fail if the key is already in the database."
                             :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\"')
@@ -341,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\"')
@@ -370,28 +378,18 @@ connections, nil is returned."
 
 (defun org-roam-db--file-hash (&optional file-path)
   "Compute the hash of FILE-PATH, a file or current buffer."
-  (let* ((file-p (and file-path))
-         (file-path (or file-path
-                        (buffer-file-name (current-buffer))))
-         (encrypted-p (and file-path
-                           (string= (org-roam--file-name-extension file-path)
-                                    "gpg"))))
-    (cond ((and encrypted-p file-p)
+  (if file-path
       (with-temp-buffer
         (set-buffer-multibyte nil)
         (insert-file-contents-literally file-path)
-             (secure-hash 'sha1 (current-buffer))))
-          (file-p
-           (with-temp-buffer
-             (insert-file-contents file-path)
-             (secure-hash 'sha1 (current-buffer))))
-          (t
-           (secure-hash 'sha1 (current-buffer))))))
+        (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))
@@ -403,7 +401,7 @@ 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)))
+  (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
@@ -413,8 +411,8 @@ connections, nil is returned."
 
 (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)
@@ -423,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)
@@ -432,60 +430,68 @@ 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
+        (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)
-            (org-roam-db--update-headlines)
-            (org-roam-db--update-links))
-          (org-roam-buffer--update-maybe :redisplay t))))))
+        (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* ((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))
          (file-count 0)
-         (headline-count 0)
+         (id-count 0)
          (link-count 0)
          (tag-count 0)
          (title-count 0)
          (ref-count 0)
-         (deleted-count 0))
+         (deleted-count 0)
+         (processed-count 0))
     (emacsql-with-transaction (org-roam-db)
       ;; Two-step building
-      ;; First step: Rebuild files and headlines
+      ;; 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)))
@@ -500,20 +506,10 @@ If FORCE, force a rebuild of the cache from scratch."
                       :values $v1]
                      (vector file contents-hash (list :atime atime :mtime mtime)))
                     (setq file-count (1+ file-count))
-                    (when-let ((headlines (org-roam--extract-headlines file)))
-                      (when (org-roam-db--insert-headlines headlines)
-                        (setq headline-count (1+ headline-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)))))))
-      ;; Second step: Rebuild the rest
-      (dolist (file org-roam-files)
-        (let ((contents-hash (org-roam-db--file-hash file)))
-          (unless (string= (gethash file current-files)
-                           contents-hash)
-            (org-roam--with-temp-buffer file
+                    (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
@@ -532,15 +528,21 @@ If FORCE, force a rebuild of the cache from scratch."
                       (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))))))
-          (remhash file current-files)))
+                        (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, headlines: Δ%s, links: Δ%s, tags: Δ%s, titles: Δ%s, refs: Δ%s, deleted: Δ%s"
+    (org-roam-message "files: Δ%s, ids: Δ%s, links: Δ%s, tags: Δ%s, titles: Δ%s, refs: Δ%s, deleted: Δ%s"
                       file-count
-                      headline-count
+                      id-count
                       link-count
                       tag-count
                       title-count

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.1
-;; 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.
 

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.1
-;; 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)

org-roam-faces.el

@@ -5,7 +5,7 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 1.2.1
+;; Version: 1.2.2
 ;; Package-Requires: ((emacs "26.1"))
 
 ;; This file is NOT part of GNU Emacs.
@@ -42,6 +42,11 @@
   "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."

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.1
-;; 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.
 
@@ -265,7 +265,7 @@ 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))

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

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.1
-;; 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.
 
@@ -37,6 +37,15 @@
 
 (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'.
@@ -46,26 +55,14 @@ If FILE, set `org-roam-temp-file-name' to file and insert its contents."
     `(let ((,current-org-roam-directory org-roam-directory))
        (with-temp-buffer
          (let ((org-roam-directory ,current-org-roam-directory)
-               (org-mode-hook nil))
+               (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

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.1
+;; 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)
@@ -62,8 +63,7 @@ It opens or creates a note with the given 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)
 

tests/test-org-roam-perf.el

@@ -29,7 +29,7 @@
 
 (defun test-org-roam-perf--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-perf--init ()
   "."
@@ -45,7 +45,7 @@
     (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 100))))
+       (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)

tests/test-org-roam.el

@@ -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"
@@ -239,7 +239,7 @@
                 :to-equal
                 '("t1" "t2 with space" "t3" "tags"))))))
 
-(describe "Headline extraction"
+(describe "ID extraction"
   (before-all
     (test-org-roam--init))
 
@@ -252,12 +252,34 @@
                     (buf (find-file-noselect fname)))
                (with-current-buffer buf
                  (funcall fn fname)))))
-    (it "extracts headlines"
-      (expect (test #'org-roam--extract-headlines
+    (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
-              `(["e84d0630-efad-4017-9059-5ef917908823" ,(test-org-roam--abs-path "headlines/headline.org")]
-                ["801b58eb-97e2-435f-a33e-ff59a2f0c213" ,(test-org-roam--abs-path "headlines/headline.org")])))))
+            '(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"