(experimental): react to directory related events in the database

With filenotify events related to subdirectories, automatically
invalidate no longer valid entries and add the new ones as they appear.

.dir-locals.el

@@ -0,0 +1,13 @@
+((emacs-lisp-mode
+  (fill-column . 110)
+  (indent-tabs-mode . nil)
+  (elisp-lint-ignored-validators . ("byte-compile" "package-lint"))
+  (elisp-lint-indent-specs . ((describe . 1)
+                              (it . 1)
+                              (org-element-map . defun)
+                              (org-roam-with-temp-buffer . 1)
+                              (org-with-point-at . 1)
+                              (magit-insert-section . defun)
+                              (magit-section-case . 0)
+                              (->> . 1)
+                              (org-roam-with-file . 2)))))

.github/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+If you discover issues, have ideas for improvements or new features, please
+report them to the [issue tracker][1] of the repository or submit a pull
+request. Please, try to follow these guidelines when you do so.
+
+## Issue reporting
+
+* Check that the issue has not already been reported.
+* Check that the issue has not already been fixed in the latest code
+  (a.k.a. `develop`).
+* Be clear, concise and precise in your description of the problem.
+* Open an issue with a descriptive title and a summary in grammatically correct,
+  complete sentences.
+* Include any relevant code to the issue summary.
+* If you're reporting performance issues it'd be nice if you added some profiling data (Emacs has a built-in profiler).
+
+## Pull requests
+
+* Read [how to properly contribute to open source projects on Github][2].
+* Use a topic branch to easily amend a pull request later, if necessary.
+* Write [good commit messages][3].
+* Mention related tickets in the commit messages (e.g. `[Fix #N] Add missing autoload cookies`)
+* Update the [changelog][5].
+* Use the same coding conventions as the rest of the project.
+* Verify your Emacs Lisp code with `checkdoc` (<kbd>C-c ? d</kbd>).
+* Open a [pull request][4] that relates to *only* one subject with a clear title
+  and description in grammatically correct, complete sentences.
+
+[1]: https://github.com/jethrokuan/org-roam/issues
+[2]: http://gun.io/blog/how-to-github-fork-branch-and-pull-request
+[3]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+[4]: https://help.github.com/articles/using-pull-requests
+[5]: https://github.com/jethrokuan/org-roam/blob/master/CHANGELOG.md

.github/FUNDING.yml

@@ -0,0 +1,12 @@
+# These are supported funding model platforms
+
+github: [jethrokuan, zaeph]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+otechie: # Replace with a single Otechie username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,43 @@
+---
+name: Bug Report
+about: Something's not working.
+title: ""
+labels: ""
+assignees: ""
+---
+
+### Description
+
+#### Steps to Reproduce
+
+<!--
+Example:
+
+1. Load Emacs
+2. Run `org-roam--build-cache-async`
+3. Run `org-roam-find-file`
+...
+-->
+
+#### Backtrace
+<!--
+   Will help us track and understand issues faster.
+   How to provide a backtrace:
+   1. M-x toggle-debug-on-error
+   2. Trigger error. The debugger buffer should pop up.
+   3. Copy the contents of the debugger buffer and paste here
+-->
+
+#### Expected Results
+
+<!-- Example: File A is there -->
+
+#### Actual Results
+
+<!-- Example: File A is missing -->
+
+### Environment
+
+<!-- Please M-x org-roam-diagnostics and paste results here -->
+
+- Org-roam commit: https://github.com/jethrokuan/org-roam/commit/commithashhere

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature Request
+about: Create a feature request to improve Org-roam
+title: ""
+labels: "enhancement"
+assignees: ""
+---
+
+### Brief Abstract
+
+### Long Description
+
+### Proposed Implementation (if any)
+
+### Please check the following:
+
+- [ ] No similar feature requests

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1 @@
+###### Motivation for this change

.github/workflows/docs.yml

@@ -0,0 +1,31 @@
+# * docs.yml --- Build the documentation and publish to Github Pages
+
+name: "Docs"
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Install deps
+      run: |
+        sudo apt-get install texinfo
+
+    - name: Build docs
+      continue-on-error: false
+      run: make html
+
+    - name: Deploy 🚀
+      uses: JamesIves/github-pages-deploy-action@releases/v3
+      with:
+        ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
+        BRANCH: gh-pages # The branch the action should deploy to.
+        FOLDER: doc # The folder the action should deploy.
+        CLEAN: true

.github/workflows/test.yml

@@ -0,0 +1,61 @@
+# * test.yml --- Test Emacs packages using makem.sh on GitHub Actions
+
+# https://github.com/alphapapa/makem.sh
+
+# Based on Steve Purcell's examples at
+# <https://github.com/purcell/setup-emacs/blob/master/.github/workflows/test.yml>,
+# <https://github.com/purcell/package-lint/blob/master/.github/workflows/test.yml>.
+
+# * License:
+
+# 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/>.
+
+# * Code:
+
+name: "CI"
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        emacs_version:
+          - 27.1
+          - snapshot
+    steps:
+      - uses: purcell/setup-emacs@master
+        with:
+          version: ${{ matrix.emacs_version }}
+
+      - uses: actions/checkout@v2
+
+      - name: Install Eldev
+        run: curl -fsSL https://raw.github.com/doublep/eldev/master/webinstall/github-eldev | sh
+
+      - name: Install dependencies
+        run: make prepare
+
+      - name: Lint
+        run: make lint
+
+      - name: Test
+        run: make test
+# Local Variables:
+# eval: (outline-minor-mode)
+# End:

.gitignore

@@ -0,0 +1,16 @@
+/.sandbox/
+**/*.elc
+/doc/dir
+/doc/*.info
+/doc/*.pdf
+/doc/*.epub
+/doc/META_INF/
+/doc/OEBPS/
+/doc/dir
+/doc/epub.xml
+/doc/org-roam/
+/doc/mimetype
+/doc/stats/
+/config.mk
+/doc/manual.html
+/.eldev/

.readthedocs.yml

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

BACKERS.md

@@ -0,0 +1,8 @@
+# Backers
+
+Many thanks to the following backers, your contributions are greatly appreciated!
+
+- Nathan Tran
+- Burke Libbey
+- forkrul
+- Andreas Stuhlmüller

CHANGELOG.md

@@ -0,0 +1,360 @@
+# Changelog
+
+## 1.2.4 (TBD)
+
+### Added
+
+- [#1396](https://github.com/org-roam/org-roam/pull/1396) add option to choose between prepending, appending, and omitting `roam_tags` in file completion
+- [#1270](https://github.com/org-roam/org-roam/pull/1270) capture: create OLP if it does not exist. Removes need for OLP setup in `:head`.
+- [#1353](https://github.com/org-roam/org-roam/pull/1353) support file-level property drawers
+
+### Changed
+
+- [#1352](https://github.com/org-roam/org-roam/pull/1352) prefer lower-case for roam_tag and roam_alias in interactive commands
+- [#1513](https://github.com/org-roam/org-roam/pull/1513) replaced hardcoded "svg" with defcustom org-roam-graph-filetype 
+- [#1540](https://github.com/org-roam/org-roam/pull/1540) allow `roam_tag` and `roam_alias` to be specified on multiple lines
+
+### Fixed
+
+- [#1281](https://github.com/org-roam/org-roam/pull/1281) fixed idle-timer not instantiated on `org-roam-mode`
+- [#1308](https://github.com/org-roam/org-roam/pull/1308) fixed file renames corrupting database
+- [#1325](https://github.com/org-roam/org-roam/pull/1325) make titles and tags extracted unique per note
+- [#1327](https://github.com/org-roam/org-roam/pull/1327) preserve existing link description during automatic replacement
+- [#1346](https://github.com/org-roam/org-roam/pull/1346) prevent malformed path to `org-roam-index-file`
+- [#1347](https://github.com/org-roam/org-roam/pull/1347) allow use of `%a` element in regular Org-roam captures
+- [#1352](https://github.com/org-roam/org-roam/pull/1352) fixed org-roam-{tag/alias}-{add/delete} altering the original case of the Org property
+- [#1374](https://github.com/org-roam/org-roam/pull/1374) fix headline completions erroring out
+- [#1375](https://github.com/org-roam/org-roam/pull/1375) fix org-roam-protocol to use existing ref file
+- [#1403](https://github.com/org-roam/org-roam/issues/1403) fixed inconsistency between how we write and read props like alias and tags
+- [#1409](https://github.com/org-roam/org-roam/issues/1398) prevent inclusion of non-org-roam files in `org-roam-dailies--list-files`
+- [#1542](https://github.com/org-roam/org-roam/issues/1542) fix files not excluded when `org-roam-list-files-commands` is nil
+- [#1705](https://github.com/org-roam/org-roam/pull/1705) fix for add/remove of file-level tags
+
+## 1.2.3 (13-11-2020)
+
+Primarily a stabilization and bug-fix release.
+
+Org-roam-dailies has also been revamped to include new features, see [this video](https://www.youtube.com/watch?v=1q9x2aZCJJ4) for a quick overview.
+
+### Added
+
+- [#978](https://github.com/org-roam/org-roam/pull/978) Revamp org-roam-dailies
+- [#1183](https://github.com/org-roam/org-roam/pull/1183) Interactive functions for managing aliases and tags in Org-roam file, namely `org-roam-alias-add`, `org-roam-alias-delete`, `org-roam-tag-add`, and `org-roam-tag-delete`.
+- [#1215](https://github.com/org-roam/org-roam/pull/1215) Multiple `ROAM_KEY` keywords can now be specified in one file. This allows bibliographical entries to share the same note file.
+- [#1238](https://github.com/org-roam/org-roam/pull/1238) Add `org-roam-prefer-id-links` variable to select linking method
+- [#1239](https://github.com/org-roam/org-roam/pull/1239) Allow `org-roam-protocol` to capture the webpage's selection, and add a toggle for storing the links to the pages
+- [#1264](https://github.com/org-roam/org-roam/pull/1264) add `org-roam-db-update-method` to control when the cache is rebuilt.
+
+### Changed
+
+- [#1264](https://github.com/org-roam/org-roam/pull/1264) renamed `org-roam-update-db-idle-seconds` to `org-roam-db-idle-idle-seconds`
+
+### Fixed
+
+- [#1074](https://github.com/org-roam/org-roam/issues/1074) fix `org-roam--extract-links` to handle content boundaries.
+- [#1193](https://github.com/org-roam/org-roam/issues/1193) fix `org-roam-db-build-cache` by not killing temporary buffer in `org-roam--extract-links`.
+- [#1195](https://github.com/org-roam/org-roam/issues/1195) fix ID face showing as invalid if within Org ID files, but not Org-roam's.
+- [#1199](https://github.com/org-roam/org-roam/issues/1199) make Org-roam link insertions respect `org-roam-link-title-format` everywhere.
+- [#1201](https://github.com/org-roam/org-roam/issues/1201) fix `org-roam-db-build-cache` failing in scenarios involving duplicate IDs and deleted files.
+- [#1226](https://github.com/org-roam/org-roam/issues/1226) only update relative path of file links
+- [#1232](https://github.com/org-roam/org-roam/issues/1232) fix incorrect title extractions from narrowed buffers
+- [#1233](https://github.com/org-roam/org-roam/issues/1233) fixes bug where descriptive file links become plain links during update for relative paths
+- [#1252](https://github.com/org-roam/org-roam/issues/1252) respect original link type during automatic replacement
+
+## 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.
+
+This is a major step forward. Supporting the in-file structure of Org-mode files means that we can interface with many of its core-features like TODOs, properties, priorities, etc. UX will have to be figured out, but this release ushers in a new age in terms of functionalities.
+
+We also add `org-roam-unlinked-references`, which naively finds text that could be references to the current Org-roam file.
+
+### Breaking Changes
+
+- [#701](https://github.com/org-roam/org-roam/pull/701) Use `emacsql-sqlite3` instead of `emacsql-sqlite` for better Windows compatibility. This requires the presence of the standard `sqlite3` binary on your machine.
+- [#750](https://github.com/org-roam/org-roam/pull/750) Deprecate `org-roam-buffer-no-delete-other-windows` in favour of `org-roam-buffer-window-parameters`.
+
+### Features
+
+- [#787](https://github.com/org-roam/org-roam/pull/787) Add `org-roam-unlinked-references`
+- [#783](https://github.com/org-roam/org-roam/pull/783) Add support for headlines
+- [#757](https://github.com/org-roam/org-roam/pull/757) Roam global properties are now case-insensitive
+- [#680](https://github.com/org-roam/org-roam/pull/680) , [#703](https://github.com/org-roam/org-roam/pull/703), [#708](https://github.com/org-roam/org-roam/pull/708) Add `org-roam-doctor` checkers for `ROAM_*` properties
+- [#664](https://github.com/org-roam/org-roam/pull/664) Add support for shelling out to `rg` and `find` in `org-roam--list-files`
+- [#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
+
+## 1.1.1 (18-05-2020)
+
+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://www.orgroam.com/manual/Tags.html#Tags).
+
+As usual, this release comes with a multitude of bug-fixes and refactorings.
+
+### Breaking Changes
+
+- [#523](https://github.com/org-roam/org-roam/pull/523) remove `org-roam-completion-fuzzy-match` in favor of using completion mechanism's configuration options directly
+- [#547](https://github.com/org-roam/org-roam/pull/547) Deprecate `org-roam-db--maybe-update`, in favour of `org-roam-db--update-maybe`
+- [#604](https://github.com/org-roam/org-roam/pull/604) Deprecate `org-roam-title-include-subdirs`, `org-roam-title-subdir-format` `org-roam-title-subdir-separator`, for a more general tagging system built on subdirectories
+
+### Bugfixes
+
+- [#509](https://github.com/org-roam/org-roam/pull/509) fix backup files being tracked in database
+- [#509](https://github.com/org-roam/org-roam/pull/509) fix external org files being tracked in database
+- [#537](https://github.com/org-roam/org-roam/pull/537) quote graphviz node and edge configuration options to allow multi-word configurations
+- [#545](https://github.com/org-roam/org-roam/pull/545) fix `org-roam--extract-links` to ensure that multiple citations (`cite:key1,key2`) are split correctly
+- [#547](https://github.com/org-roam/org-roam/pull/547) Fix unlinked citations
+- [#660](https://github.com/org-roam/org-roam/pull/660) fix rename-file advice not working for renaming to directories
+- [#660](https://github.com/org-roam/org-roam/pull/660) fix links breaking within file on file movement
+
+### Features
+
+- [#538](https://github.com/org-roam/org-roam/pull/538) Optionally use text in first headline as title
+- [#553](https://github.com/org-roam/org-roam/pull/553) Add prefix argument to `org-roam-db-build-cache` for forcing rebuilds
+- [#560](https://github.com/org-roam/org-roam/pull/560) Apply 'error face to distinguish broken links
+- [#570](https://github.com/org-roam/org-roam/pull/570) Add `org-roam-doctor` to diagnose org-roam files
+- [#625](https://github.com/org-roam/org-roam/pull/625) Add `org-roam-title-sources` to control how titles are retrieved within notes
+- [#604](https://github.com/org-roam/org-roam/pull/604) Add a tagging system. `org-roam-tag-sources` controls how tags are retrieved from notes
+
+### Internal Changes
+
+- [#547](https://github.com/org-roam/org-roam/pull/547) Added `type` column to the `refs` table
+- [#606](https://github.com/org-roam/org-roam/pull/606) Added `org-roam-dev.el` for developer coding standards
+- [#622](https://github.com/org-roam/org-roam/pull/622) Online documentation now points to the Org-based documentation
+
+## 1.1.0 (21-04-2020)
+
+To the average user, this release is mainly a bugfix release with additional options to customize. However, the changes made to the source is significant. Most notably, in this release:
+
+1. The codebase has been modularized into separate files, to ease future maintenance and adding of new features (mainly by [@progfolio](https://github.com/progfolio)). Because of these changes, we had to rename many functions and variables: the old names are kept for backwards compatibility, but you are encouraged to use the new function names. You'll receive a warning when you're calling the function with its obsolete name.
+2. [@kljohann](https://github.com/kljohann) did some fantastic work on graph generation: allowing building images for connected components within the graph up to a specified distance
+3. We also started supporting `org-ref` natively: cite links now show up in both the graph and the org-roam buffer.
+
+In the coming months, you can expect work on bigger projects (e.g. revamping the org-roam buffer).
+
+### Breaking Changes
+
+- [#385](https://github.com/org-roam/org-roam/pull/385) Deprecate `org-roam-graph-node-shape` in favour of `org-roam-graph-node-extra-config`.
+- [#473](https://github.com/org-roam/org-roam/pull/473) Deprecate `org-roam-date-filename-format` and `org-roam-date-title-format`, in favour of `org-roam-dailies-capture-templates`.
+
+### New Features
+
+- [#350](https://github.com/org-roam/org-roam/pull/350) Add `org-roam-db-location` to customize location of org-roam database.
+- [#359](https://github.com/org-roam/org-roam/pull/359) Add `org-roam-verbose` to allow or silence printing of information.
+- [#374](https://github.com/org-roam/org-roam/pull/374) Add support for `org-ref` `cite:` links
+- [#380](https://github.com/org-roam/org-roam/pull/380) Allow `org-roam-buffer-position` to also be `top` or `bottom`
+- [#385](https://github.com/org-roam/org-roam/pull/385) Add `org-roam-graph-node-extra-config` to configure Graphviz nodes
+- [#398](https://github.com/org-roam/org-roam/pull/398), [#418](https://github.com/org-roam/org-roam/pull/418) Add graph building for connected components
+- [#435](https://github.com/org-roam/org-roam/pull/435) Add `org-roam-graph-edge-extra-config` to configure Graphviz edges
+- [#439](https://github.com/org-roam/org-roam/pull/439) Add support for `org-ref` citations to display as edges in graph. Add `org-roam-graph-edge-cites-extra-config` to configure these edges
+- [#465](https://github.com/org-roam/org-roam/pull/465) Add `org-roam-file-extensions` to allow detection of org files with different file extensions
+- [#488](https://github.com/org-roam/org-roam/pull/488) Allow a function for `org-roam-graph-viewer`
+- [#491](https://github.com/org-roam/org-roam/pull/491) Use TITLE as description when linking before first heading
+
+### Bugfixes
+
+- [#470](https://github.com/org-roam/org-roam/pull/470) Add workaround for undocumented `file-truename` behaviour in `org-roam--org-roam-file-p`.
+
+### Internal Changes
+
+- [#363](https://github.com/org-roam/org-roam/pull/363), [#473](https://github.com/org-roam/org-roam/pull/473) Modularize org-roam features.
+- [#497](https://github.com/org-roam/org-roam/pull/497) Simplify `org-roam--list-files` implementation
+
+## 1.0.0 (23-03-2020)
+
+Org-roam is now on MELPA! We have squashed most of the bugs, and Org-roam has
+been stable for the most part.
+
+### New Features
+
+- [#269](https://github.com/org-roam/org-roam/pull/269) Add `org-roam-graphviz-extra-options`
+- [#257](https://github.com/org-roam/org-roam/pull/257) Add a company-backend `company-org-roam`
+- [#284](https://github.com/org-roam/org-roam/pull/284), [#289](https://github.com/org-roam/org-roam/pull/289) Configurable `org-roam-completion-system` with options `'default`, `'ido`, `'ivy` and `'helm`
+- [#289](https://github.com/org-roam/org-roam/pull/289) Add customizable `org-roam-fuzzy-match` to allow fuzzy-matching of candidates
+- [#290](https://github.com/org-roam/org-roam/pull/290) Add `org-roam-date-title-format` and `org-roam-date-filename-format` for customizing Org-roam's date files
+- [#296](https://github.com/org-roam/org-roam/pull/296) Allow multiple exclusion matchers in `org-roam-graph-exclude-matcher`
+
+### Bugfixes
+
+- [#293](https://github.com/org-roam/org-roam/pull/293) Fix capture templates not working as expected for `org-roam-find-file`
+- [#275](https://github.com/org-roam/org-roam/pull/275) Fix database rebuild when `org-roam-directory` is set locally
+
+## 1.0.0-rc1 (06-03-2020)
+
+This is a pre-release before the push to MELPA. It contains large
+internal changes, with little user-facing changes. Most notably, the
+backing storage has been changed to a SQLite database, and a
+templating system using `org-capture` is introduced.
+
+### Breaking Changes
+
+- [#200](https://github.com/org-roam/org-roam/pull/200) Move Org-roam cache into a SQLite database.
+- [#203](https://github.com/org-roam/org-roam/pull/203) Roam protocol is deprecated, in favour of extending org-roam-protocol.
+
+### New Features
+
+- [#182](https://github.com/org-roam/org-roam/pull/182) Support file name aliases via `#+ROAM_ALIAS`.
+- [#216](https://github.com/org-roam/org-roam/pull/216) Adds templating functionality by extending org-capture.
+- [#232](https://github.com/org-roam/org-roam/pull/232) Adds a prefix key to `org-roam-show-graph`, to generate graph without opening it.
+- [#233](https://github.com/org-roam/org-roam/pull/233) Adds `org-roam-graph-exclude-matcher`, which allows exclusion of nodes from graph.
+- [#247](https://github.com/org-roam/org-roam/pull/247) Add `org-roam-backlink` face, which allows customizing backlinks appearance
+- [#259](https://github.com/org-roam/org-roam/pull/259) Add optional initial-prompt to `org-roam-find-file`
+
+### Bugfixes
+
+- [#207](https://github.com/org-roam/org-roam/pull/207), [#221](https://github.com/org-roam/org-roam/pull/221) small bugfixes to Org-roam graph generation
+- [#230](https://github.com/org-roam/org-roam/pull/230) remove nonspacing marks from filenames, to prevent cross-platform errors
+
+### New Contributors
+
+- [@acowley][https://github.com/acowley]
+- [@teesloane][https://github.com/teesloane]
+
+## 0.1.2 (2020-02-21)
+
+### Breaking Changes
+
+- [#143](https://github.com/org-roam/org-roam/pull/143) `org-roam-mode` is now a global mode. The installation instructions have changed accordingly.
+- [#103](https://github.com/org-roam/org-roam/pull/103) Change `org-roam-file-format` to a function: `org-roam-file-name-function` to allow more flexible file name customizaton. Also changes `org-roam-use-timestamp-as-filename` to `org-roam-filename-noconfirm` to better describe what it does.
+
+### New Features
+
+- [#145](https://github.com/org-roam/org-roam/pull/145) `org-roam-show-graph`: Fallback to Emacs SVG viewer
+- [#141](https://github.com/org-roam/org-roam/pull/141) add variable `org-roam-new-file-directory` for new Org-roam files
+- [#138](https://github.com/org-roam/org-roam/pull/138) add `org-roam-switch-to-buffer`
+- [#124](https://github.com/org-roam/org-roam/pull/124), [#141](https://github.com/org-roam/org-roam/pull/141) Maintain cache consistency on file rename and delete
+- [#87](https://github.com/org-roam/org-roam/pull/87), [#90](https://github.com/org-roam/org-roam/pull/90) Support encrypted Org files
+- [#110](https://github.com/org-roam/org-roam/pull/110) Add prefix to `org-roam-insert`, for inserting titles down-cased
+- [#99](https://github.com/org-roam/org-roam/pull/99) Add keybinding so that `<return>` or `mouse-1` in the backlinks buffer visits the source file of the backlink at point
+
+### Changes
+
+- [#108](https://github.com/org-roam/org-roam/pull/108) Locally overwrite the link following behaviour in the org-roam-buffer to open files in the same window `org-roam` was called from
+
+### Bugfixes
+
+- [#86](https://github.com/org-roam/org-roam/pull/86) Fix `org-roam--parse-content` incorrect `:to` computation for nested files
+- [#98](https://github.com/org-roam/org-roam/pull/98) Fix `org-roam--find-file` picking up temporary files
+- [#136](https://github.com/org-roam/org-roam/pull/136) Misc bugfixes
+
+### Internal
+
+- [#122](https://github.com/org-roam/org-roam/pull/122), [#128](https://github.com/org-roam/org-roam/pull/128) Improve performance of post-command-hook
+- [#92](https://github.com/org-roam/org-roam/pull/92), [#105](https://github.com/org-roam/org-roam/pull/105) Add tests for core functionality
+
+### New Contributors
+
+- [@frigge](https://github.com/frigge)
+- [@juergenhoetzel](https://github.com/juergenhoetzel)
+- [@chip2n](https://github.com/chip2n)
+- [@l3kn](https://github.com/l3kn)
+- [@jdormit](https://github.com/jdormit)
+- [@herbertjones](https://github.com/herbertjones)
+- [@CeleritasCelery](https://github.com/CeleritasCelery)
+- [@daniel-koudouna](https://github.com/daniel-koudouna)
+
+## 0.1.1 (2020-02-15)
+
+Mostly a documentation/cleanup release.
+
+### New Features
+
+- [#62](https://github.com/org-roam/org-roam/pull/62) Add the options `org-roam-use-timestamps-as-filename` and `org-roam-file-format`, more in documentation.
+
+### Breaking Changes
+
+- [#62](https://github.com/org-roam/org-roam/pull/62) The ID (file-name) workflow is no longer first-class, but a fallback when titles don't exist.
+
+### Changes
+
+- [#66](https://github.com/org-roam/org-roam/pull/66), [#68](https://github.com/org-roam/org-roam/pull/68): Improved the quality of the package in preparation of submission to MELPA
+- [#73](https://github.com/org-roam/org-roam/pull/73): Added CI to the project via Github Issues (Thanks [@alphapapa](https://github.com/alphapapa/) for scripts and setup)
+- [#69](https://github.com/org-roam/org-roam/pull/69), [#72](https://github.com/org-roam/org-roam/pull/72), [#75](https://github.com/org-roam/org-roam/pull/75): Major cleanup and de-duplication of code
+
+### Bugfixes
+
+- [#67](https://github.com/org-roam/org-roam/pull/67): Fixed `org-roam--make-file` not creating files with extensions
+- [#71](https://github.com/org-roam/org-roam/pull/71), [#78](https://github.com/org-roam/org-roam/pull/78): Fixed `org-roam-insert` not inserting correct paths
+- [#82](https://github.com/org-roam/org-roam/pull/82): Fixed nested Org-roam files not being detected as part of Org-roam
+
+<!-- Local Variables: -->
+<!-- eval: (auto-fill-mode -1) -->
+<!-- End: -->

Eldev

@@ -0,0 +1,29 @@
+; -*- mode: emacs-lisp; lexical-binding: t; no-byte-compile: t -*-
+
+;; explicitly set main file
+(setf eldev-project-main-file "org-roam.el")
+
+(eldev-use-package-archive 'gnu)
+(eldev-use-package-archive 'melpa-unstable)
+
+;; allow to load test helpers
+(eldev-add-loading-roots 'test "test/utils")
+
+;; Tell checkdoc not to demand two spaces after a period.
+(setq sentence-end-double-space nil)
+
+(setf eldev-lint-default '(elisp))
+(setf eldev-standard-excludes `(:or ,eldev-standard-excludes "org-roam-macs.el"))
+
+(with-eval-after-load 'elisp-lint
+  ;; We will byte-compile with Eldev.
+  (setf elisp-lint-ignored-validators '("package-lint" "fill-column")
+        enable-local-variables        :all))
+
+;; Teach linter how to properly indent emacsql vectors
+(eldev-add-extra-dependencies 'lint 'emacsql)
+(add-hook 'eldev-lint-hook
+          (lambda ()
+            (eldev-load-project-dependencies 'lint nil t)
+            (require 'emacsql)
+            (call-interactively #'emacsql-fix-vector-indentation)))

Makefile

@@ -0,0 +1,29 @@
+.PHONY: clean
+clean:
+	eldev clean all
+
+.PHONY: prepare
+prepare:
+	eldev -C --unstable -p -dtT prepare
+
+.PHONY: lint
+lint:
+	eldev -C --unstable -T lint
+
+.PHONY: test
+test:
+	eldev -C --unstable -T test
+
+docs:
+	make -C doc all
+
+html:
+	make -C doc html-dir
+
+install: install-docs
+
+install-docs: docs
+	make -C doc install-docs
+
+install-info: info
+	make -C doc install-info

README.md

@@ -1,52 +1,122 @@
-[![Documentation Status](https://readthedocs.org/projects/org-roam/badge/?version=latest)](https://org-roam.readthedocs.io/en/latest/?badge=latest)
+# Org-roam [![GitHub Release][release-badge]][release] [![MELPA][melpa-badge]][melpa] [![License GPL 3][gpl3-badge]][gpl3]
 
-Org-roam is a rudimentary [Roam][roamresearch] replica built around
-the all-powerful [Org-mode][org]. 
+<img src="https://www.orgroam.com/img/logo.svg" align="right" alt="Org-roam Logo" width="240">
 
-Like Roam, Org-roam offers a powerful and effortless non-hierarchical
-note-taking approach. With Org-roam, notes flow naturally, making
-note-taking fun and easy. 
+Org-roam is a plain-text knowledge management system. It brings some of
+[Roam's][roamresearch] more powerful features into the [Org-mode][org]
+ecosystem.
 
-The goal of the project is to implement core features of Roam around
-Org-mode, and eventually introduce features enabled by the Emacs
-ecosystem. 
+Org-roam borrows principles from the Zettelkasten method, providing a solution
+for non-hierarchical note-taking. It should also work as a plug-and-play
+solution for anyone already using Org-mode for their personal wiki.
 
-For more documentation, see [the documentation page](https://org-roam.readthedocs.io/en/latest/).
+- **Private and Secure**: Edit your personal wiki completely offline, entirely
+  in your control. Encrypt your notes with GPG. Take lasting notes in
+  plain-text.
+- **Networked Thought**: Connect notes and thoughts together with ease using
+  backlinks. Discover surprising and previously unseen connections in your notes
+  with the built-in graph visualization.
+- **Extensible and Powerful**: Leverage Emacs' fantastic text-editing interface,
+  and the mature Emacs and Org-mode ecosystem of packages.
+- **Free and Open Source**: Org-roam is licensed under the GNU General Public
+  License version 3 or later.
 
-## Understanding Roam
+<p align="center">
+  <img src="https://www.orgroam.com/img/screenshot.png" alt="Org-roam Screenshot" width="738">
+</p>
 
-To understand more about Roam, I recommend the following links:
+- **[Documentation][docs]**
+- **[Discourse][discourse]**
+- **[Slack][slack]**
+- **[Frequently Asked Questions][faq]**
+- **[Changelog](CHANGELOG.md)**
 
--   [Building a second brain in
-    Roam](https://reddit.com/r/RoamResearch/comments/eho7de/building_a_second_brain_in_roamand_why_you_might)
--   [Roam: Why I Love It and How I Use
-    It](https://www.nateliason.com/blog/roam)
+## Installation
 
-## Project Status
+You can install `org-roam` using `package.el`:
 
-As of February 2020, it is in a very early stage of development. 
+```
+M-x package-install RET org-roam RET
+```
 
-## A Preview
+Here's a sample configuration with `use-package`:
 
-Here's a screenshot of `org-roam`. The `org-roam` buffer shows
-backlinks for the active org buffer in the left window, as well as the
-surrounding content in the backlink file. The backlink database is
-built asynchronously in the background, and is not noticeable to the
-end user. The graph is generated from the link structure, and can be
-used to navigate to the respective files.
+```emacs-lisp
+(use-package org-roam
+      :ensure t
+      :custom
+      (org-roam-directory (file-truename "/path/to/org-files/"))
+      :bind (("C-c n l" . org-roam-buffer-toggle)
+             ("C-c n f" . org-roam-node-find)
+             ("C-c n g" . org-roam-graph)
+             ("C-c n i" . org-roam-node-insert)
+             ("C-c n c" . org-roam-capture)
+             ;; Dailies
+             ("C-c n j" . org-roam-dailies-capture-today))
+      :config
+      (org-roam-db-autosync-mode)
+      ;; If using org-roam-protocol
+      (require 'org-roam-protocol))
+```
 
-![img](doc/images/org-roam-graph.gif)
+The `file-truename` function is only necessary when you use symbolic links
+inside `org-roam-directory`: Org-roam does not resolve symbolic links.
 
-## Knowledge Bases using Org-Roam
+Org-roam requires sqlite to function. Org-roam optionally uses Graphviz for
+graph-related functionality. It is recommended to install PCRE-enabled ripgrep
+for better performance and extended functionality.
+
+## Getting Started
+
+[David Wilson](https://github.com/daviwil) of [System
+Crafters](https://www.youtube.com/c/SystemCrafters) has produced an introductory
+video that covers the basic commands:
+
+[![Getting Started with Org Roam - Build a Second Brain in Emacs](https://img.youtube.com/vi/AyhPmypHDEw/0.jpg)](https://www.youtube.com/watch?v=AyhPmypHDEw)
+
+## 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/)
   ([Source](https://github.com/jethrokuan/braindump/tree/master/org))
+- [Alexey Shmalko](https://braindump.rasen.dev/)
+- [Sidharth Arya](https://sidhartharya.github.io/braindump/index.html)
 
 ## Contributing
 
 To report bugs and suggest new feature use the issue tracker. If you
 have some code which you would like to be merged, then open a pull
-request. Please also see CONTRIBUTING.md.
+request. Please also see [CONTRIBUTING.md](.github/CONTRIBUTING.md).
+
+## License
+
+Copyright © Jethro Kuan and contributors. Distributed under the GNU
+General Public License, Version 3.
 
 [roamresearch]: https://www.roamresearch.com/
 [org]: https://orgmode.org/
+[gpl3-badge]: https://img.shields.io/badge/license-GPL_3-green.svg
+[gpl3]: http://www.gnu.org/licenses/gpl-3.0.txt
+[melpa-badge]: https://melpa.org/packages/org-roam-badge.svg
+[melpa]: https://melpa.org/#/org-roam
+[release-badge]: https://img.shields.io/github/v/release/org-roam/org-roam
+[release]: https://github.com/org-roam/org-roam/releases
+[docs]: https://www.orgroam.com/manual.html
+[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
+[faq]: https://www.orgroam.com/manual.html#FAQ

default.mk

@@ -0,0 +1,107 @@
+TOP := $(dir $(lastword $(MAKEFILE_LIST)))
+
+## User options ######################################################
+#
+# You can override these settings in "config.mk" or on the command
+# line.
+#
+# You might also want to set LOAD_PATH.  If you do, then it must
+# contain "-L .".
+#
+# If you don't do so, then the default is set in the "Load-Path"
+# section below.  The default assumes that all dependencies are
+# installed either at "../<DEPENDENCY>", or when using package.el
+# at "ELPA_DIR/<DEPENDENCY>-<HIGHEST-VERSION>".
+
+sharedir ?= $(HOME)/.local/share
+lispdir  ?= $(sharedir)/emacs/site-lisp/org-roam
+infodir  ?= $(sharedir)/info
+docdir   ?= $(sharedir)/doc/org-roam
+statsdir ?= $(TOP)/doc/stats
+
+CP       ?= install -p -m 644
+MKDIR    ?= install -p -m 755 -d
+RMDIR    ?= rm -rf
+TAR      ?= tar
+SED      ?= sed
+
+EMACSBIN ?= emacs
+BATCH     = $(EMACSBIN) -Q --batch $(LOAD_PATH)
+
+INSTALL_INFO     ?= $(shell command -v ginstall-info || printf install-info)
+MAKEINFO         ?= makeinfo
+MANUAL_HTML_ARGS ?= --css-ref /assets/page.css
+
+## Files #############################################################
+
+PKG       = org-roam
+PACKAGES  = org-roam
+
+TEXIPAGES = $(addsuffix .texi,$(PACKAGES))
+INFOPAGES = $(addsuffix .info,$(PACKAGES))
+HTMLFILES = $(addsuffix .html,$(PACKAGES))
+HTMLDIRS  = $(PACKAGES)
+PDFFILES  = $(addsuffix .pdf,$(PACKAGES))
+EPUBFILES = $(addsuffix .epub,$(PACKAGES))
+
+ELS = org-roam.el
+ELS += org-roam-capture.el
+ELS += org-roam-compat.el
+ELS += org-roam-db.el
+ELS += org-roam-mode.el
+ELS += org-roam-node.el
+ELS += org-roam-utils.el
+ELS += extensions/org-roam-dailies.el
+ELS += extensions/org-roam-graph.el
+ELS += extensions/org-roam-overlay.el
+ELS += extensions/org-roam-protocol.el
+ELCS = $(ELS:.el=.elc)
+ELMS = org-roam.el $(filter-out $(addsuffix .el,$(PACKAGES)),$(ELS))
+ELGS = org-roam-autoloads.el org-roam-version.el
+
+## Versions ##########################################################
+
+VERSION ?= $(shell test -e $(TOP).git && git describe --tags --abbrev=0 | cut -c2-)
+
+EMACS_VERSION = 26.1
+
+EMACSOLD := $(shell $(BATCH) --eval \
+  "(and (version< emacs-version \"$(EMACS_VERSION)\") (princ \"true\"))")
+ifeq "$(EMACSOLD)" "true"
+  $(error At least version $(EMACS_VERSION) of Emacs is required)
+endif
+
+## Load-Path #########################################################
+
+ifndef LOAD_PATH
+
+ELPA_DIR ?= $(HOME)/.emacs.d/elpa
+
+SYSTYPE := $(shell $(EMACSBIN) -Q --batch --eval "(princ system-type)")
+ifeq ($(SYSTYPE), windows-nt)
+  CYGPATH := $(shell cygpath --version 2>/dev/null)
+endif
+
+LOAD_PATH = -L $(TOP)
+
+# When making changes here, then don't forget to adjust "Makefile",
+# ".travis.yml", ".github/ISSUE_TEMPLATE/bug_report.md",
+# `magit-emacs-Q-command' and the "Installing from the Git Repository"
+# info node accordingly.  Also don't forget to "rgrep \b<pkg>\b".
+
+endif # ifndef LOAD_PATH
+
+ifndef ORG_LOAD_PATH
+ORG_LOAD_PATH  = $(LOAD_PATH)
+ORG_LOAD_PATH += -L $(TOP)../ox-texinfo-plus
+ORG_LOAD_PATH += -L $(TOP)../org-mode/contrib/lisp
+ORG_LOAD_PATH += -L $(TOP)../org-mode/lisp
+endif
+
+## Publish ###########################################################
+
+PUBLISH_TARGETS ?= html html-dir pdf epub
+
+DOCBOOK_XSL ?= /usr/share/xml/docbook/stylesheet/docbook-xsl/epub/docbook.xsl
+
+EPUBTRASH = epub.xml META-INF OEBPS

doc/AUTHORS.md

@@ -0,0 +1,37 @@
+Authors
+=======
+
+The following people have contributed to Org-Roam.
+
+Names below are sorted alphabetically.
+
+Author
+------
+
+- Jethro Kuan <jethrokuan95@gmail.com>
+
+Maintainers
+----------
+
+- Jethro Kuan <jethrokuan95@gmail.com>
+- Leo Vivier <leo.vivier+dev@gmail.com>
+
+Contributors
+------------
+
+- Alexey Shmalko <rasen.dubi@gmail.com>
+- James Ravn <james@r-vn.org>
+- Jethro Kuan <jethrokuan95@gmail.com>
+- Johann Klähn <johann@jklaehn.de>
+- Josh English <josh@joshenglish.com>
+- Jürgen Hötzel <juergen@archlinux.org>
+- Langston Barrett <langston.barrett@gmail.com>
+- Leo Vivier <leo.vivier+dev@gmail.com>
+- Michael Glaesemann <grzm@seespotcode.net>
+- Michael Herold <github@michaeljherold.com>
+- Noboru <noboru.ota@gmail.com>
+- N V <44036031+progfolio@users.noreply.github.com>
+- Rafael Accácio Nogueira <raccacio@poli.ufrj.br>
+- Roland Coeurjoly <rolandcoeurjoly@gmail.com>
+- Sayan <dit7ya@users.noreply.github.com>
+- Tim Quelch <tim@tquelch.com>

doc/Makefile

@@ -0,0 +1,127 @@
+-include ../config.mk
+include ../default.mk
+
+###################################################################
+MANUAL_HTML_ARGS = --css-ref assets/page.css
+
+.PHONY: texi install clean AUTHORS.md stats
+
+all: info
+
+## Build #############################################################
+
+info: $(INFOPAGES) dir
+html: $(HTMLFILES)
+pdf:  $(PDFFILES)
+epub: $(EPUBFILES)
+
+%.info: %.texi
+	@printf "Generating $@\n"
+	@$(MAKEINFO) --no-split $< -o $@
+
+dir: org-roam.info
+	@printf "Generating dir\n"
+	@echo $^ | xargs -n 1 $(INSTALL_INFO) --dir=$@
+
+%.html: %.texi
+	@printf "Generating $@\n"
+	@$(MAKEINFO) --html --no-split $(MANUAL_HTML_ARGS) $<
+
+html-dir:
+	@$(MAKEINFO) --html --no-split $(MANUAL_HTML_ARGS) org-roam.texi
+	mv org-roam.html manual.html
+
+%.pdf: %.texi
+	@printf "Generating $@\n"
+	@texi2pdf --clean $< > /dev/null
+
+%.epub: %.texi
+	@printf "Generating $@\n"
+	@$(MAKEINFO) --docbook $< -o epub.xml
+	@xsltproc $(DOCBOOK_XSL) epub.xml 2> /dev/null
+	@echo "application/epub+zip" > mimetype
+	@zip -X --quiet --recurse-paths -0 $@ mimetype
+	@zip -X --quiet --recurse-paths -9 --no-dir-entries $@ META-INF OEBPS
+	@$(RMDIR) $(EPUBTRASH)
+
+## Install ###########################################################
+
+install: install-info install-docs
+
+install-docs: install-info
+	@$(MKDIR) $(DESTDIR)$(docdir)
+	$(CP) AUTHORS.md $(DESTDIR)$(docdir)
+
+install-info: info
+	@$(MKDIR) $(DESTDIR)$(infodir)
+	$(CP) $(INFOPAGES) $(DESTDIR)$(infodir)
+
+## Clean #############################################################
+
+clean:
+	@printf "Cleaning doc/*...\n"
+	@$(RMDIR) dir $(INFOPAGES) $(HTMLFILES) $(HTMLDIRS) $(PDFFILES)
+	@$(RMDIR) $(EPUBFILES) $(EPUBTRASH)
+
+## Release management ################################################
+
+ORG_ARGS  = --batch -Q $(ORG_LOAD_PATH)
+ORG_ARGS += -l ox-extra -l ox-texinfo+
+ORG_ARGS += --eval "(or (require 'org-man nil t) (require 'ol-man))"
+ORG_EVAL  = --eval "(ox-extras-activate '(ignore-headlines))"
+ORG_EVAL += --eval "(setq indent-tabs-mode nil)"
+ORG_EVAL += --eval "(setq org-src-preserve-indentation nil)"
+ORG_EVAL += --funcall org-texinfo-export-to-texinfo
+
+# This target first bumps version strings in the Org source.  The
+# necessary tools might be missing so other targets do not depend
+# on this target and it has to be run explicitly when appropriate.
+#
+#   AMEND=t make texi    Update manual to be amended to HEAD.
+#   VERSION=N make texi  Update manual for release.
+#
+texi:
+	@$(EMACSBIN) $(ORG_ARGS) $(PKG).org $(ORG_EVAL)
+	@printf "\n" >> $(PKG).texi
+	@rm -f $(PKG).texi~
+
+stats:
+	@printf "Generating statistics\n"
+	@gitstats -c style=/assets/stats.css -c max_authors=999 $(TOP) $(statsdir)
+
+authors: AUTHORS.md
+
+AUTHORS.md:
+	@printf "Generating AUTHORS.md..."
+	@test -e $(TOP).git \
+	&& (printf "$$AUTHORS_HEADER\n" > $@ \
+	&& git log --pretty=format:'- %aN <%aE>' | sort -u >> $@ \
+	&& printf "done\n" ; ) \
+	|| printf "FAILED (non-fatal)\n"
+
+# Templates ##########################################################
+
+define AUTHORS_HEADER
+Authors
+=======
+
+The following people have contributed to Org-Roam.
+
+Names below are sorted alphabetically.
+
+Author
+------
+
+- Jethro Kuan <jethrokuan95@gmail.com>
+
+Maintainers
+----------
+
+- Jethro Kuan <jethrokuan95@gmail.com>
+- Leo Vivier <leo.vivier+dev@gmail.com>
+
+Contributors
+------------
+
+endef
+export AUTHORS_HEADER

doc/assets/page.css

@@ -0,0 +1,68 @@
+:root {
+  --border: #526980;
+  --code: #007;
+}
+
+body {
+    margin: 5ex 10ex;
+    max-width: 80ex;
+    line-height: 1.5;
+    font-family: sans-serif;
+}
+
+h1, h2, h3 {
+    font-weight: normal;
+}
+
+pre, code {
+    font-family: x, monospace;
+}
+
+pre {
+    padding: 1ex;
+    background: #eee;
+    border: solid 1px #ddd;
+    min-width: 0;
+    font-size: 80%;
+    overflow: auto;
+}
+
+code {
+    color: var(--code);
+}
+
+img {
+    max-width: 100%;
+}
+
+table {
+  border-collapse: collapse;
+  width: 100%;
+}
+
+pre.menu-comment {
+  background: none;
+  border: none;
+  font-family: sans-serif;
+  padding: 0;
+  margin: 0;
+  font-size: 100%;
+}
+
+thead {
+  border-bottom: 1px solid var(--border);
+}
+
+tfoot {
+  border-top: 1px solid var(--border);
+}
+
+blockquote {
+  margin-left: 1rem;
+  font-style: italic;
+  font-family: serif;
+  border-left: 3px solid;
+  border-left-color: currentcolor;
+  border-color: var(--text-color);
+  padding-left: 1em;
+}

doc/comparison.md

@@ -1,11 +0,0 @@
----
-title: "Comparing Org-Roam With Other Packages"
-metaTitle: "Comparing Org-Roam With Other Packages"
-metaDescription: "Comparing Org-Roam With Other Packages"
----
-
-# Org-brain
-
-# Zetteldeft
-
-# Org-zettelkasten

doc/css/styles.css

@@ -0,0 +1,85 @@
+body {
+  margin: 20px;
+  background: #303030;
+  color: #f5f5f5;
+  font-size: 1.6rem;
+  font-weight: 300;
+}
+
+.container {
+  max-width: 800px;
+}
+
+.nav {
+  margin-top: 5rem;
+}
+
+.nav-item a {
+  /* color: #797979; */
+  color: #bebebe;
+  text-decoration: none;
+  font-family: "Consolas", "Monaco", "Menlo", monospace;
+}
+
+.nav-item a:hover {
+  cursor: pointer;
+  /* color: #4d4a4a; */
+  color: #dcdcdc;
+  border: none;
+}
+
+.hero {
+  color: #f5f5f5;
+}
+
+.hero div {
+  margin-bottom: 5rem;
+}
+
+.hero h3 {
+  /* font-family: "Edelsans", sans-serif; */
+  font-size: 5rem;
+  margin-bottom: 0;
+}
+
+.hero h5 {
+  margin-top: 1rem;
+  margin-bottom: 0;
+  /* font-weight: 200; */
+  font-weight: 250;
+}
+
+.grid-demo-col {
+  background: #e4e4e4;
+}
+
+a {
+  color: #cd86ff;
+}
+
+a:hover {
+  color: #dbb9f3;
+}
+
+img {
+  max-width: 100%;
+}
+
+.footer-links {
+  font-size: 1.5rem;
+  color: #f5f5f5;
+  text-decoration: none;
+  font-weight: 250;
+}
+
+.header {
+  font-weight: 200;
+}
+
+#footer {
+  margin-bottom: 3rem;
+}
+
+#footer h5 {
+  margin-bottom: 1.5rem;
+}

doc/ecosystem.md

@@ -1,37 +0,0 @@
-## Ecosystem
-
-A number of packages work well combined with Org-Roam:
-
-### Deft
-[Deft](https://jblevins.org/projects/deft/) provides a nice
-interface for browsing and filtering org-roam notes.
-
-```
-(use-package deft
-  :after org
-  :bind
-  ("C-c n d" . deft)
-  :custom
-  (deft-recursive t)
-  (deft-use-filter-string-for-filename t)
-  (deft-default-extension "org")
-  (deft-directory "/path/to/org-roam-files/")
-  (deft-use-filename-as-title t))
-```
-
-### Org-journal
-[Org-journal](https://github.com/bastibe/org-journal) is a more
-powerful alternative to the simple function `org-roam-today`. It
-provides better journaling capabilities, and a nice calendar interface
-to see all dated entries.
-
-```
-(use-package org-journal
-  :bind
-  ("C-c n j" . org-journal-new-entry)
-  :custom
-  (org-journal-date-prefix "#+TITLE: ")
-  (org-journal-file-format "%Y-%m-%d.org")
-  (org-journal-dir "/path/to/org-roam-files/")
-  (org-journal-date-format "%A, %d %B %Y"))
-```

doc/htmlxref.cnf

@@ -0,0 +1,15 @@
+# https://www.gnu.org/software/texinfo/manual/texinfo/html_node/HTML-Xref-Configuration.html
+
+EMACS = https://www.gnu.org/software/emacs/manual
+
+auth		mono	${EMACS}/html_mono/auth.html
+auth		node	${EMACS}/html_node/auth/
+
+ediff		mono	${EMACS}/html_mono/ediff.html
+ediff		node	${EMACS}/html_node/ediff/
+
+elisp		mono	${EMACS}/html_mono/elisp.html
+elisp		node	${EMACS}/html_node/elisp/
+
+emacs		mono	${EMACS}/html_mono/emacs.html
+emacs		node	${EMACS}/html_node/emacs/

doc/index.html

@@ -0,0 +1,168 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content="An Effortless PKM System." />
+    <meta name="author" content="Org-roam Contributors" />
+
+    <title>Org-roam</title>
+
+    <link rel="stylesheet" href="https://unpkg.com/wingcss" />
+    <link rel="stylesheet" type="text/css" href="./css/styles.css" />
+
+    <script src="https://code.iconify.design/1/1.0.6/iconify.min.js"></script>
+  </head>
+
+  <body>
+    <section class="hero container center text-center">
+      <div>
+        <img src="./img/logo.png" alt="Org-roam Logo" height="200" />
+        <h3>Org-roam</h3>
+        <h5>A plain-text personal knowledge management system.</h5>
+      </div>
+    </section>
+
+    <section class="container center">
+      <div>
+        <img src="./img/screenshot.png" alt="screenshot" />
+      </div>
+    </section>
+
+    <section id="features" class="container center">
+      <div>
+        <h3 class="header">FEATURES</h3>
+        <div class="row">
+          <div class="col">
+            <h5 class="left">
+              <iconify-icon data-icon="fxemoji:lock"></iconify-icon> &nbsp;
+              Private and Secure
+            </h5>
+            <p class="content">
+              Edit your personal wiki completely offline, entirely in your
+              control. Encrypt your notes with GPG. Take lasting notes in
+              plain-text.
+            </p>
+          </div>
+          <div class="col">
+            <h5 class="left">
+              <iconify-icon data-icon="flat-color-icons:link"></iconify-icon>
+              &nbsp; Make Connections
+            </h5>
+            <p class="content">
+              Connect notes and thoughts together with ease using backlinks.
+              Discover surprising and previously unseen connections in your
+              notes with the built-in graph visualization.
+            </p>
+          </div>
+        </div>
+
+        <div class="row">
+          <div class="col">
+            <h5 class="left">
+              <iconify-icon data-icon="twemoji:puzzle-piece"></iconify-icon>
+              &nbsp; Extensible and Powerful
+            </h5>
+            <p class="content">
+              Leverage Emacs' fantastic text-editing interface, and the mature
+              Emacs and Org-mode ecosystem of packages.
+            </p>
+          </div>
+          <div class="col">
+            <h5 class="left">
+              <iconify-icon data-icon="logos:git-icon"></iconify-icon> &nbsp;
+              Free and Open Source
+            </h5>
+            <p class="content">
+              Org-roam is licensed under the GNU General Public License version
+              3 or later. You are free to extend its functionality and
+              contribute back. Find
+              us <a href="https://github.com/org-roam/org-roam">here</a>.
+            </p>
+          </div>
+        </div>
+      </div>
+    </section>
+    
+    <section id="links" class="container">
+      <div>
+        <h3 class="header">LINKS</h3> New to Emacs and Org-mode, and trying to
+        find your way around? Org-roam has an inclusive community of users
+        passionate about Personal Knowledge Management -- we're happy to help!
+        You can find us on Discourse and Slack.
+        
+        <ul>
+            <li>Read our documentation within Emacs, or on the <a href="https://www.orgroam.com/manual.html">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>
+      </div>
+    </section>
+
+    <section id="footer" class="row container">
+      <div class="col">
+        <div class="row">
+          <h5 class="header">Ecosystem</h5>
+        </div>
+
+        <div class="row">
+          <a
+            class="content footer-links"
+            href="https://github.com/org-roam/org-roam-bibtex"
+            >org-roam-bibtex</a
+          >
+        </div>
+        <div class="row">
+          <a
+            class="content footer-links"
+            href="https://github.com/org-roam/org-roam-server"
+            >org-roam-server</a
+          >
+        </div>
+      </div>
+
+      <div class="col">
+        <div class="row">
+          <h5 class="header">Resources</h5>
+        </div>
+
+        <div class="row">
+          <a
+            class="content footer-links"
+            href="https://github.com/org-roam/org-roam/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc"
+            >Open Issues</a
+          >
+        </div>
+        <div class="row">
+          <a
+            class="content footer-links"
+            href="https://github.com/org-roam/org-roam/releases"
+            >Releases</a
+          >
+        </div>
+      </div>
+
+      <div class="col">
+        <div class="row">
+          <h5 class="header">Connect</h5>
+        </div>
+
+        <div class="row">
+          <a
+            class="content footer-links"
+            href="https://join.slack.com/t/orgroam/shared_invite/zt-deoqamys-043YQ~s5Tay3iJ5QRI~Lxg"
+            >Slack</a
+          >
+        </div>
+        <div class="row">
+          <a
+            class="content footer-links"
+            href="https://org-roam.discourse.group/"
+            >Discourse</a
+          >
+        </div>
+      </div>
+    </section>
+  </body>
+</html>

doc/index.md

@@ -1,41 +0,0 @@
-![org-roam][org-roam-intro-image]
-
-## What is Org-Roam?
-
-Org-roam is a rudimentary [Roam][roamresearch] replica built around
-the all-powerful [Org-mode][org]. 
-
-Like Roam, Org-roam offers a powerful and effortless non-hierarchical
-note-taking approach. With Org-roam, notes flow naturally, making
-note-taking fun and easy. To understand more about Roam, I recommend
-the following links:
-
--   [Building a second brain in
-    Roam](https://reddit.com/r/RoamResearch/comments/eho7de/building_a_second_brain_in_roamand_why_you_might)
--   [Roam: Why I Love It and How I Use
-    It](https://www.nateliason.com/blog/roam)
-
-The goal of the project is to implement core features of Roam around
-Org-mode, and eventually introduce features enabled by the Emacs
-ecosystem. 
-
-## Why build Org-Roam?
-
-With Org-roam, you:
-
-1. Never have to leave Emacs.
-2. Can leverage all the powerful features of Org-mode: LaTeX, tables,
-   and the whole to-do ecosystem (org-agenda etc.)
-3. Be in full control your second brain, and access it offline. Never
-   share your data with anyone
-
-There are several packages that are similar to Org-roam, see the
-[Comparison](comparison.md) page for a detailed comparison.
-
-## Project Status
-
-As of February 2020, it is in a very early stage of development. 
-
-[org-roam-intro-image]: images/org-roam-intro.png
-[roamresearch]: https://www.roamresearch.com/
-[org]: https://orgmode.org/

doc/installation.md

@@ -1,35 +0,0 @@
-## Installation
-
-The recommended method is using [use-package][use-package] and
-[straight][straight], or a similar package manager.
-
-```
-(use-package org-roam
-      :after org
-      :hook (org-mode . org-roam-mode)
-      :straight (:host github :repo "jethrokuan/org-roam")
-      :custom
-      (org-roam-directory "/path/to/org-files/")
-      (org-roam-link-representation 'title) ;; or keep it as 'id
-      :bind
-      ("C-c n l" . org-roam)      
-      ("C-c n t" . org-roam-today)
-      ("C-c n f" . org-roam-find-file)
-      ("C-c n i" . org-roam-insert)
-      ("C-c n g" . org-roam-show-graph))
-```
-
-If not using package.el, you can also clone it into your Emacs
-directory and add it to your load path:
-
-```
-git clone https://github.com/jethrokuan/org-roam/ ~/.emacs.d/elisp/org-roam
-```
-
-```
-(add-to-list 'load-path "./elisp")
-(require 'org-roam)
-```
-
-[use-package]: https://github.com/jwiegley/use-package
-[straight]: https://github.com/raxod502/straight.el

doc/requirements.txt

@@ -1,2 +0,0 @@
-mkdocs-material==4.6.2
-pymdown-extensions==6.3

doc/tour.md

@@ -1,20 +0,0 @@
-### A Tour of Org-Roam
-
-All of this starts from the note. A note is just a simple `.org` file
-in the directory. Any org file in the directory is considered part of
-the org-roam ecosystem. Notes are quickly linked together (and created
-if necessary) using `org-roam-insert`.
-
-![org-roam-insert](images/org-roam-insert.gif)
-
-Org-roam tracks all of these file links, and builds a cache
-asynchronously in the background. This cache is used to populate the
-backlinks buffer, which shows files that link to the current file, as
-well as some preview contents:
-
-![org-roam-buffer](images/org-roam-buffer.gif)
-
-These file links also form a graph. The generated graph is navigable
-in Emacs.
-
-![org-roam-graph](images/org-roam-graph.gif)

extensions/org-roam-dailies.el

@@ -0,0 +1,338 @@
+;;; org-roam-dailies.el --- Daily-notes for Org-roam -*- coding: utf-8; lexical-binding: t; -*-
+;;;
+;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
+;; Copyright © 2020 Leo Vivier <leo.vivier+dev@gmail.com>
+
+;; Author: Jethro Kuan <jethrokuan95@gmail.com>
+;;      Leo Vivier <leo.vivier+dev@gmail.com>
+;; URL: https://github.com/org-roam/org-roam
+;; Keywords: org-mode, roam, convenience
+;; Version: 2.0.0
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org-roam "2.0"))
+
+;; 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 extension provides functionality for creating daily-notes, or shortly
+;; "dailies". Dailies implemented here as a unique node per unique file, where
+;; each file named after certain date and stored in `org-roam-dailies-directory'.
+;;
+;; One can use dailies for various purposes, e.g. journaling, fleeting notes,
+;; scratch notes and whatever else you can came up with.
+;;
+;;; Code:
+(require 'f)
+(require 'dash)
+(require 'org-roam)
+
+;;; Faces
+(defface org-roam-dailies-calendar-note
+  '((t :inherit (org-link) :underline nil))
+  "Face for dates with a daily-note in the calendar."
+  :group 'org-roam-faces)
+
+;;; Options
+(defcustom org-roam-dailies-directory "daily/"
+  "Path to daily-notes.
+This path is relative to `org-roam-directory'."
+  :group 'org-roam
+  :type 'string)
+
+(defcustom org-roam-dailies-find-file-hook nil
+  "Hook that is run right after navigating to a daily-note."
+  :group 'org-roam
+  :type 'hook)
+
+(defcustom org-roam-dailies-capture-templates
+  `(("d" "default" entry
+     "* %?"
+     :if-new (file+head "%<%Y-%m-%d>.org"
+                        "#+title: %<%Y-%m-%d>\n")))
+  "Capture templates for daily-notes in Org-roam.
+Note that for daily files to show up in the calendar, they have to be of format
+\"org-time-string.org\".
+See `org-roam-capture-templates' for the template documentation."
+  :group 'org-roam
+  :type '(repeat
+          (choice (list :tag "Multikey description"
+                        (string :tag "Keys       ")
+                        (string :tag "Description"))
+                  (list :tag "Template entry"
+                        (string :tag "Keys           ")
+                        (string :tag "Description    ")
+                        (choice :tag "Capture Type   " :value entry
+                                (const :tag "Org entry" entry)
+                                (const :tag "Plain list item" item)
+                                (const :tag "Checkbox item" checkitem)
+                                (const :tag "Plain text" plain)
+                                (const :tag "Table line" table-line))
+                        (choice :tag "Template       "
+                                (string)
+                                (list :tag "File"
+                                      (const :format "" file)
+                                      (file :tag "Template file"))
+                                (list :tag "Function"
+                                      (const :format "" function)
+                                      (function :tag "Template function")))
+                        (plist :inline t
+                               ;; Give the most common options as checkboxes
+                               :options (((const :format "%v " :if-new)
+                                          (choice :tag "Node location"
+                                                  (list :tag "File"
+                                                        (const :format "" file)
+                                                        (string :tag "  File"))
+                                                  (list :tag "File & Head Content"
+                                                        (const :format "" file+head)
+                                                        (string :tag "  File")
+                                                        (string :tag "  Head Content"))
+                                                  (list :tag "File & Outline path"
+                                                        (const :format "" file+olp)
+                                                        (string :tag "  File")
+                                                        (list :tag "Outline path"
+                                                              (repeat (string :tag "Headline"))))
+                                                  (list :tag "File & Head Content & Outline path"
+                                                        (const :format "" file+head+olp)
+                                                        (string :tag "  File")
+                                                        (string :tag "  Head Content")
+                                                        (list :tag "Outline path"
+                                                              (repeat (string :tag "Headline"))))))
+                                         ((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 " :unnarrowed) (const t))
+                                         ((const :format "%v " :table-line-pos) (string))
+                                         ((const :format "%v " :kill-buffer) (const t))))))))
+
+;;; Commands
+;;;; Today
+;;;###autoload
+(defun org-roam-dailies-capture-today (&optional goto)
+  "Create an entry in the daily-note for today.
+When GOTO is non-nil, go the note without creating an entry."
+  (interactive "P")
+  (org-roam-dailies--capture (current-time) goto))
+
+;;;###autoload
+(defun org-roam-dailies-goto-today ()
+  "Find the daily-note for today, creating it if necessary."
+  (interactive)
+  (org-roam-dailies-capture-today t))
+
+;;;; Tomorrow
+;;;###autoload
+(defun org-roam-dailies-capture-tomorrow (n &optional goto)
+  "Create an entry in the daily-note for tomorrow.
+
+With numeric argument N, use the daily-note N days in the future.
+
+With a `C-u' prefix or when GOTO is non-nil, go the note without
+creating an entry."
+  (interactive "p")
+  (org-roam-dailies--capture (time-add (* n 86400) (current-time)) goto))
+
+;;;###autoload
+(defun org-roam-dailies-goto-tomorrow (n)
+  "Find the daily-note for tomorrow, creating it if necessary.
+
+With numeric argument N, use the daily-note N days in the
+future."
+  (interactive "p")
+  (org-roam-dailies-capture-tomorrow n t))
+
+;;;; Yesterday
+;;;###autoload
+(defun org-roam-dailies-capture-yesterday (n &optional goto)
+  "Create an entry in the daily-note for yesteday.
+
+With numeric argument N, use the daily-note N days in the past.
+
+When GOTO is non-nil, go the note without creating an entry."
+  (interactive "p")
+  (org-roam-dailies-capture-tomorrow (- n) goto))
+
+;;;###autoload
+(defun org-roam-dailies-goto-yesterday (n)
+  "Find the daily-note for yesterday, creating it if necessary.
+
+With numeric argument N, use the daily-note N days in the
+future."
+  (interactive "p")
+  (org-roam-dailies-capture-tomorrow (- n) t))
+
+;;;; Date
+;;;###autoload
+(defun org-roam-dailies-capture-date (&optional goto prefer-future)
+  "Create an entry in the daily-note for a date using the calendar.
+Prefer past dates, unless PREFER-FUTURE is non-nil.
+With a `C-u' prefix or when GOTO is non-nil, go the note without
+creating an entry."
+  (interactive "P")
+  (let ((time (let ((org-read-date-prefer-future prefer-future))
+                (org-read-date t t nil (if goto
+                                           "Find daily-note: "
+                                         "Capture to daily-note: ")))))
+    (org-roam-dailies--capture time goto)))
+
+;;;###autoload
+(defun org-roam-dailies-goto-date (&optional prefer-future)
+  "Find the daily-note for a date using the calendar, creating it if necessary.
+Prefer past dates, unless PREFER-FUTURE is non-nil."
+  (interactive)
+  (org-roam-dailies-capture-date t prefer-future))
+
+;;;; Navigation
+(defun org-roam-dailies-goto-next-note (&optional n)
+  "Find next daily-note.
+
+With numeric argument N, find note N days in the future. If N is
+negative, find note N days in the past."
+  (interactive "p")
+  (unless (org-roam-dailies--daily-note-p)
+    (user-error "Not in a daily-note"))
+  (setq n (or n 1))
+  (let* ((dailies (org-roam-dailies--list-files))
+         (position
+          (cl-position-if (lambda (candidate)
+                            (string= (buffer-file-name (buffer-base-buffer)) candidate))
+                          dailies))
+         note)
+    (unless position
+      (user-error "Can't find current note file - have you saved it yet?"))
+    (pcase n
+      ((pred (natnump))
+       (when (eq position (- (length dailies) 1))
+         (user-error "Already at newest note")))
+      ((pred (integerp))
+       (when (eq position 0)
+         (user-error "Already at oldest note"))))
+    (setq note (nth (+ position n) dailies))
+    (find-file note)
+    (run-hooks 'org-roam-dailies-find-file-hook)))
+
+(defun org-roam-dailies-goto-previous-note (&optional n)
+  "Find previous daily-note.
+
+With numeric argument N, find note N days in the past. If N is
+negative, find note N days in the future."
+  (interactive "p")
+  (let ((n (if n (- n) -1)))
+    (org-roam-dailies-goto-next-note n)))
+
+(defun org-roam-dailies--list-files (&rest extra-files)
+  "List all files in `org-roam-dailies-directory'.
+EXTRA-FILES can be used to append extra files to the list."
+  (let ((dir (expand-file-name org-roam-dailies-directory org-roam-directory))
+        (regexp (rx-to-string `(and "." (or ,@org-roam-file-extensions)))))
+    (append (--remove (let ((file (file-name-nondirectory it)))
+                        (when (or (auto-save-file-name-p file)
+                                  (backup-file-name-p file)
+                                  (string-match "^\\." file))
+                          it))
+                      (directory-files-recursively dir regexp))
+            extra-files)))
+
+(defun org-roam-dailies--daily-note-p (&optional file)
+  "Return t if FILE is an Org-roam daily-note, nil otherwise.
+If FILE is not specified, use the current buffer's file-path."
+  (when-let ((path (expand-file-name
+                    (or file
+                        (buffer-file-name (buffer-base-buffer)))))
+             (directory (expand-file-name org-roam-dailies-directory org-roam-directory)))
+    (setq path (expand-file-name path))
+    (save-match-data
+      (and
+       (org-roam-file-p path)
+       (f-descendant-of-p path directory)))))
+
+;;;###autoload
+(defun org-roam-dailies-find-directory ()
+  "Find and open `org-roam-dailies-directory'."
+  (interactive)
+  (find-file (expand-file-name org-roam-dailies-directory org-roam-directory)))
+
+;;; Calendar integration
+(defun org-roam-dailies-calendar--file-to-date (file)
+  "Convert FILE to date.
+Return (MONTH DAY YEAR) or nil if not an Org time-string."
+  (ignore-errors
+    (cl-destructuring-bind (_ _ _ d m y _ _ _)
+        (org-parse-time-string
+         (file-name-sans-extension
+          (file-name-nondirectory file)))
+      (list m d y))))
+
+(defun org-roam-dailies-calendar-mark-entries ()
+  "Mark days in the calendar for which a daily-note is present."
+  (when (file-exists-p (expand-file-name org-roam-dailies-directory org-roam-directory))
+    (dolist (date (remove nil
+                          (mapcar #'org-roam-dailies-calendar--file-to-date
+                                  (org-roam-dailies--list-files))))
+      (when (calendar-date-is-visible-p date)
+        (calendar-mark-visible-date date 'org-roam-dailies-calendar-note)))))
+
+(add-hook 'calendar-today-visible-hook #'org-roam-dailies-calendar-mark-entries)
+(add-hook 'calendar-today-invisible-hook #'org-roam-dailies-calendar-mark-entries)
+
+;;; Capture implementation
+(add-to-list 'org-roam-capture--template-keywords :override-default-time)
+
+(defun org-roam-dailies--capture (time &optional goto)
+  "Capture an entry in a daily-note for TIME, creating it if necessary.
+When GOTO is non-nil, go the note without creating an entry."
+  (let ((org-roam-directory (expand-file-name org-roam-dailies-directory org-roam-directory)))
+    (org-roam-capture- :goto (when goto '(4))
+                       :node (org-roam-node-create)
+                       :templates org-roam-dailies-capture-templates
+                       :props (list :override-default-time time)))
+  (when goto (run-hooks 'org-roam-dailies-find-file-hook)))
+
+(add-hook 'org-roam-capture-preface-hook #'org-roam-dailies--override-capture-time-h)
+(defun org-roam-dailies--override-capture-time-h ()
+  "Override the `:default-time' with the time from `:override-default-time'."
+  (prog1 nil
+    (when (org-roam-capture--get :override-default-time)
+      (org-capture-put :default-time (org-roam-capture--get :override-default-time)))))
+
+;;; Bindings
+(defvar org-roam-dailies-map (make-sparse-keymap)
+  "Keymap for `org-roam-dailies'.")
+
+(define-prefix-command 'org-roam-dailies-map)
+
+(define-key org-roam-dailies-map (kbd "d") #'org-roam-dailies-goto-today)
+(define-key org-roam-dailies-map (kbd "y") #'org-roam-dailies-goto-yesterday)
+(define-key org-roam-dailies-map (kbd "t") #'org-roam-dailies-goto-tomorrow)
+(define-key org-roam-dailies-map (kbd "n") #'org-roam-dailies-capture-today)
+(define-key org-roam-dailies-map (kbd "f") #'org-roam-dailies-goto-next-note)
+(define-key org-roam-dailies-map (kbd "b") #'org-roam-dailies-goto-previous-note)
+(define-key org-roam-dailies-map (kbd "c") #'org-roam-dailies-goto-date)
+(define-key org-roam-dailies-map (kbd "v") #'org-roam-dailies-capture-date)
+(define-key org-roam-dailies-map (kbd ".") #'org-roam-dailies-find-directory)
+
+(provide 'org-roam-dailies)
+
+;;; org-roam-dailies.el ends here

extensions/org-roam-graph.el

@@ -0,0 +1,282 @@
+;;; org-roam-graph.el --- Basic graphing functionality for Org-roam -*- coding: utf-8; lexical-binding: t; -*-
+
+;; Copyright © 2020-2021 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: 2.0.0
+;; Package-Requires: ((emacs "26.1") (org "9.4") (org-roam "2.0"))
+
+;; 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 extension implements capability to build and generate graphs in Org-roam
+;; with the help of Graphviz.
+;;
+;;; Code:
+(require 'xml) ;xml-escape-string
+(require 'org-roam)
+
+;;; Options
+(defcustom org-roam-graph-viewer (executable-find "firefox")
+  "Method to view the org-roam graph.
+It may be one of the following:
+  - a string representing the path to the executable for viewing the graph.
+  - a function accepting a single argument: the graph file path.
+  - nil uses `view-file' to view the graph."
+  :type '(choice
+          (string   :tag "Path to executable")
+          (function :tag "Function to display graph" eww-open-file)
+          (const    :tag "view-file"))
+  :group 'org-roam)
+
+(defcustom org-roam-graph-executable "dot"
+  "Path to graphing executable, or its name."
+  :type 'string
+  :group 'org-roam)
+
+(defcustom org-roam-graph-filetype "svg"
+  "File type to generate when producing graphs."
+  :type 'string
+  :group 'org-roam)
+
+
+(defcustom org-roam-graph-extra-config nil
+  "Extra options passed to graphviz.
+Example:
+ '((\"rankdir\" . \"LR\"))"
+  :type '(alist)
+  :group 'org-roam)
+
+(defcustom org-roam-graph-edge-extra-config nil
+  "Extra edge options passed to graphviz.
+Example:
+ '((\"dir\" . \"back\"))"
+  :type '(alist)
+  :group 'org-roam)
+
+(defcustom org-roam-graph-node-extra-config
+  '(("id" . (("style"      . "bold,rounded,filled")
+             ("fillcolor"  . "#EEEEEE")
+             ("color"      . "#C9C9C9")
+             ("fontcolor"  . "#111111")))
+    ("http" . (("style"      . "rounded,filled")
+               ("fillcolor"  . "#EEEEEE")
+               ("color"      . "#C9C9C9")
+               ("fontcolor"  . "#0A97A6")))
+    ("https" . (("shape"      . "rounded,filled")
+                ("fillcolor"  . "#EEEEEE")
+                ("color"      . "#C9C9C9")
+                ("fontcolor"  . "#0A97A6"))))
+  "Extra options for graphviz nodes."
+  :type '(alist)
+  :group 'org-roam)
+
+(defcustom org-roam-graph-link-hidden-types
+  '("file")
+  "What sort of links to hide from the Org-roam graph."
+  :type '(repeat string)
+  :group 'org-roam)
+
+(defcustom org-roam-graph-max-title-length 100
+  "Maximum length of titles in graph nodes."
+  :type 'number
+  :group 'org-roam)
+
+(defcustom org-roam-graph-shorten-titles 'truncate
+  "Determines how long titles appear in graph nodes.
+Recognized values are the symbols `truncate' and `wrap', in which
+cases the title will be truncated or wrapped, respectively, if it
+is longer than `org-roam-graph-max-title-length'.
+
+All other values including nil will have no effect."
+  :type '(choice
+          (const :tag "truncate" truncate)
+          (const :tag "wrap" wrap)
+          (const :tag "no" nil))
+  :group 'org-roam)
+
+;;; Interactive command
+;;;###autoload
+(defun org-roam-graph (&optional arg node)
+  "Build and possibly display a graph for NODE.
+ARG may be any of the following values:
+  - nil       show the graph.
+  - `\\[universal-argument]'     show the graph for NODE.
+  - `\\[universal-argument]' N   show the graph for NODE limiting nodes to N steps."
+  (interactive
+   (list current-prefix-arg
+         (and current-prefix-arg
+              (org-roam-node-at-point 'assert))))
+  (let ((graph (cl-typecase arg
+                 (null (org-roam-graph--dot nil 'all-nodes))
+                 (cons (org-roam-graph--dot (org-roam-graph--connected-component
+                                             (org-roam-node-id node) 0)))
+                 (integer (org-roam-graph--dot (org-roam-graph--connected-component
+                                                (org-roam-node-id node) (abs arg)))))))
+    (org-roam-graph--build graph #'org-roam-graph--open)))
+
+;;; Generation and Build process
+(defun org-roam-graph--build (graph &optional callback)
+  "Generate the GRAPH, and execute CALLBACK when process exits successfully.
+CALLBACK is passed the graph file as its sole argument."
+  (unless (stringp org-roam-graph-executable)
+    (user-error "`org-roam-graph-executable' is not a string"))
+  (unless (executable-find org-roam-graph-executable)
+    (user-error (concat "Cannot find executable \"%s\" to generate the graph.  "
+                        "Please adjust `org-roam-graph-executable'")
+                org-roam-graph-executable))
+  (let* ((temp-dot   (make-temp-file "graph." nil ".dot" graph))
+         (temp-graph (make-temp-file "graph." nil (concat "." org-roam-graph-filetype))))
+    (org-roam-message "building graph")
+    (make-process
+     :name "*org-roam-graph--build-process*"
+     :buffer "*org-roam-graph--build-process*"
+     :command `(,org-roam-graph-executable ,temp-dot "-T" ,org-roam-graph-filetype "-o" ,temp-graph)
+     :sentinel (when callback
+                 (lambda (process _event)
+                   (when (= 0 (process-exit-status process))
+                     (funcall callback temp-graph)))))))
+
+(defun org-roam-graph--dot (&optional edges all-nodes)
+  "Build the graphviz given the EDGES of the graph.
+If ALL-NODES, include also nodes without edges."
+  (let ((org-roam-directory-temp org-roam-directory)
+        (nodes-table (make-hash-table :test #'equal))
+        (seen-nodes (list))
+        (edges (or edges (org-roam-db-query [:select :distinct [source dest type] :from links]))))
+    (pcase-dolist (`(,id ,file ,title)
+                   (org-roam-db-query [:select [id file title] :from nodes]))
+      (puthash id (org-roam-node-create :file file :id id :title title) nodes-table))
+    (with-temp-buffer
+      (setq-local org-roam-directory org-roam-directory-temp)
+      (insert "digraph \"org-roam\" {\n")
+      (dolist (option org-roam-graph-extra-config)
+        (insert (org-roam-graph--dot-option option) ";\n"))
+      (insert (format " edge [%s];\n"
+                      (mapconcat (lambda (var)
+                                   (org-roam-graph--dot-option var nil "\""))
+                                 org-roam-graph-edge-extra-config
+                                 ",")))
+      (pcase-dolist (`(,source ,dest ,type) edges)
+        (unless (member type org-roam-graph-link-hidden-types)
+          (pcase-dolist (`(,node ,node-type) `((,source "id")
+                                               (,dest ,type)))
+            (unless (member node seen-nodes)
+              (insert (org-roam-graph--format-node
+                       (or (gethash node nodes-table) node) node-type))
+              (push node seen-nodes)))
+          (insert (format "  \"%s\" -> \"%s\";\n"
+                          (xml-escape-string source)
+                          (xml-escape-string dest)))))
+      (when all-nodes
+        (maphash (lambda (id node)
+                   (unless (member id seen-nodes)
+                     (insert (org-roam-graph--format-node node "id"))))
+                 nodes-table))
+      (insert "}")
+      (buffer-string))))
+
+(defun org-roam-graph--connected-component (id distance)
+  "Return the edges for all nodes reachable from/connected to ID.
+DISTANCE is the maximum distance away from the root node."
+  (let* ((query
+          (if (= distance 0)
+              "
+WITH RECURSIVE
+  links_of(source, dest) AS
+  (SELECT source, dest FROM links UNION
+   SELECT dest, source FROM links),
+   connected_component(source) AS
+  (SELECT dest FROM links_of WHERE source = $s1 UNION
+   SELECT dest FROM links_of JOIN connected_component USING(source))
+SELECT source, dest, type FROM links WHERE source IN connected_component OR dest IN connected_component;"
+            "
+WITH RECURSIVE
+  links_of(source, dest) AS
+  (SELECT source, dest FROM links UNION
+   SELECT dest, source FROM links),
+  connected_component(source, trace) AS
+  (VALUES ($s1 , json_array($s1)) UNION
+   SELECT lo.dest, json_insert(cc.trace, '$[' || json_array_length(cc.trace) || ']', lo.dest) FROM
+   connected_component AS cc JOIN links_of AS lo USING(source)
+   WHERE (
+    -- Avoid cycles by only visiting each node once.
+    (SELECT count(*) FROM json_each(cc.trace) WHERE json_each.value == lo.dest) == 0
+    -- Note: BFS is cut off early here.
+    AND json_array_length(cc.trace) < $s2)),
+  nodes(source) as (SELECT DISTINCT source
+   FROM connected_component GROUP BY source ORDER BY min(json_array_length(trace)))
+SELECT source, dest, type FROM links WHERE source IN nodes OR dest IN nodes;")))
+    (org-roam-db-query query id distance)))
+
+(defun org-roam-graph--dot-option (option &optional wrap-key wrap-val)
+  "Return dot string of form KEY=VAL for OPTION cons.
+If WRAP-KEY is non-nil it wraps the KEY.
+If WRAP-VAL is non-nil it wraps the VAL."
+  (concat wrap-key (car option) wrap-key
+          "="
+          wrap-val (cdr option) wrap-val))
+
+(defun org-roam-graph--format-node (node type)
+  "Return a graphviz NODE with TYPE.
+Handles both Org-roam nodes, and string nodes (e.g. urls)."
+  (let (node-id node-properties)
+    (if (org-roam-node-p node)
+        (let* ((title (org-roam-quote-string (org-roam-node-title node)))
+               (shortened-title
+                (org-roam-quote-string
+                 (pcase org-roam-graph-shorten-titles
+                   (`truncate (truncate-string-to-width title org-roam-graph-max-title-length nil nil "..."))
+                   (`wrap (s-word-wrap org-roam-graph-max-title-length title))
+                   (_ title)))))
+          (setq node-id (org-roam-node-id node)
+                node-properties `(("label"   . ,shortened-title)
+                                  ("URL"     . ,(concat "org-protocol://roam-node?node="
+                                                        (url-hexify-string (org-roam-node-id node))))
+                                  ("tooltip" . ,(xml-escape-string title)))))
+      (setq node-id node
+            node-properties (append `(("label" . ,(concat type ":" node)))
+                                    (when (member type (list "http" "https"))
+                                      `(("URL" . ,(xml-escape-string (concat type ":" node))))))))
+    (format "\"%s\" [%s];\n"
+            node-id
+            (mapconcat (lambda (n)
+                         (org-roam-graph--dot-option n nil "\""))
+                       (append (cdr (assoc type org-roam-graph-node-extra-config))
+                               node-properties) ","))))
+
+(defun org-roam-graph--open (file)
+  "Open FILE using `org-roam-graph-viewer' with `view-file' as a fallback."
+  (pcase org-roam-graph-viewer
+    ((pred stringp)
+     (if (executable-find org-roam-graph-viewer)
+         (condition-case err
+             (call-process org-roam-graph-viewer nil 0 nil file)
+           (error (user-error "Failed to open org-roam graph: %s" err)))
+       (user-error "Executable not found: \"%s\"" org-roam-graph-viewer)))
+    ((pred functionp) (funcall org-roam-graph-viewer file))
+    ('nil (view-file file))
+    (_ (signal 'wrong-type-argument `((functionp stringp null) ,org-roam-graph-viewer)))))
+
+
+(provide 'org-roam-graph)
+
+;;; org-roam-graph.el ends here

extensions/org-roam-overlay.el

@@ -0,0 +1,96 @@
+;;; org-roam-overlay.el --- Link overlay for [id:] links to Org-roam nodes -*- coding: utf-8; lexical-binding: t; -*-
+
+;; Copyright © 2020-2021 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: 2.0.0
+;; Package-Requires: ((emacs "26.1") (org "9.4") (org-roam "2.0"))
+
+;; 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 extension provides allows to render [[id:]] links that don't have an
+;; asscoiated descriptor with an overlay that displays the node's current title.
+;;
+;;; Code:
+(require 'org-roam)
+
+(defface org-roam-overlay
+  '((((class color) (background light))
+     :background "grey90" :box (:line-width -1 :color "black"))
+    (((class color) (background dark))
+     :background "grey10" :box (:line-width -1 :color "white")))
+  "Face for the Org-roam overlay."
+  :group 'org-roam-faces)
+
+(defun org-roam-overlay--make (l r &rest props)
+  "Make an overlay from L to R with PROPS."
+  (let ((o (make-overlay l (or r l))))
+    (overlay-put o 'category 'org-roam)
+    (while props (overlay-put o (pop props) (pop props)))
+    o))
+
+(defun org-roam-overlay-make-link-overlay (link)
+  "Create overlay for LINK."
+  (save-excursion
+    (save-match-data
+      (let* ((type (org-element-property :type link))
+             (id (org-element-property :path link))
+             (pos (org-element-property :end link))
+             (desc-p (org-element-property :contents-begin link))
+             node)
+        (when (and (string-equal type "id")
+                   (setq node (org-roam-node-from-id id))
+                   (not desc-p))
+          (org-roam-overlay--make
+           pos pos
+           'after-string (format "%s "
+                                 (propertize (org-roam-node-title node)
+                                             'face 'org-roam-overlay))))))))
+
+(defun org-roam-overlay-enable ()
+  "Enable Org-roam overlays."
+  (org-roam-db-map-links
+   (list #'org-roam-overlay-make-link-overlay)))
+
+(defun org-roam-overlay-disable ()
+  "Disable Org-roam overlays."
+  (remove-overlays nil nil 'category 'org-roam))
+
+(defun org-roam-overlay-redisplay ()
+  "Redisplay Org-roam overlays."
+  (org-roam-overlay-disable)
+  (org-roam-overlay-enable))
+
+(define-minor-mode org-roam-overlay-mode
+  "Overlays for Org-roam ID links.
+Org-roam overlay mode is a minor mode.  When enabled,
+overlay displaying the node's title is displayed."
+  :lighter " org-roam-overlay"
+  (if org-roam-overlay-mode
+      (progn
+        (org-roam-overlay-enable)
+        (add-hook 'after-save-hook #'org-roam-overlay-redisplay nil t))
+    (org-roam-overlay-disable)
+    (remove-hook 'after-save-hook #'org-roam-overlay-redisplay t)))
+
+(provide 'org-roam-overlay)
+;;; org-roam-overlay.el ends here

extensions/org-roam-protocol.el

@@ -0,0 +1,192 @@
+;;; org-roam-protocol.el --- Protocol handler for roam:// links  -*- coding: utf-8; lexical-binding: t; -*-
+
+;; Copyright © 2020-2021 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: 2.0.0
+;; Package-Requires: ((emacs "26.1") (org "9.4") (org-roam "2.0"))
+
+;; 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 extension extends `org-protocol', adding custom Org-roam handlers to it
+;; to provide the next new protocols:
+;;
+;; 1. "roam-node": This protocol simply opens the node given by the node ID
+;; 2. "roam-ref": This protocol creates or opens the node with the given REF
+;;
+;; You can find detailed instructions on how to setup the protocol in the
+;; documentation for Org-roam.
+;;
+;;; Code:
+(require 'org-protocol)
+(require 'ol) ;; for org-link-decode
+(require 'org-roam)
+
+;;; Options
+(defcustom org-roam-protocol-store-links nil
+  "Whether to store links when capturing websites with `org-roam-protocol'."
+  :type 'boolean
+  :group 'org-roam)
+
+(defcustom org-roam-capture-ref-templates
+  '(("r" "ref" plain "%?"
+     :if-new (file+head "${slug}.org"
+                        "#+title: ${title}")
+     :unnarrowed t))
+  "The Org-roam templates used during a capture from the roam-ref protocol.
+See `org-roam-capture-templates' for the template documentation."
+  :group 'org-roam
+  :type '(repeat
+          (choice (list :tag "Multikey description"
+                        (string :tag "Keys       ")
+                        (string :tag "Description"))
+                  (list :tag "Template entry"
+                        (string :tag "Keys           ")
+                        (string :tag "Description    ")
+                        (choice :tag "Capture Type   " :value entry
+                                (const :tag "Org entry" entry)
+                                (const :tag "Plain list item" item)
+                                (const :tag "Checkbox item" checkitem)
+                                (const :tag "Plain text" plain)
+                                (const :tag "Table line" table-line))
+                        (choice :tag "Template       "
+                                (string)
+                                (list :tag "File"
+                                      (const :format "" file)
+                                      (file :tag "Template file"))
+                                (list :tag "Function"
+                                      (const :format "" function)
+                                      (function :tag "Template function")))
+                        (plist :inline t
+                               ;; Give the most common options as checkboxes
+                               :options (((const :format "%v " :if-new)
+                                          (choice :tag "Node location"
+                                                  (list :tag "File"
+                                                        (const :format "" file)
+                                                        (string :tag "  File"))
+                                                  (list :tag "File & Head Content"
+                                                        (const :format "" file+head)
+                                                        (string :tag "  File")
+                                                        (string :tag "  Head Content"))
+                                                  (list :tag "File & Outline path"
+                                                        (const :format "" file+olp)
+                                                        (string :tag "  File")
+                                                        (list :tag "Outline path"
+                                                              (repeat (string :tag "Headline"))))
+                                                  (list :tag "File & Head Content & Outline path"
+                                                        (const :format "" file+head+olp)
+                                                        (string :tag "  File")
+                                                        (string :tag "  Head Content")
+                                                        (list :tag "Outline path"
+                                                              (repeat (string :tag "Headline"))))))
+                                         ((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 " :unnarrowed) (const t))
+                                         ((const :format "%v " :table-line-pos) (string))
+                                         ((const :format "%v " :kill-buffer) (const t))))))))
+
+;;; Handlers
+(defun org-roam-protocol-open-ref (info)
+  "Process an org-protocol://roam-ref?ref= style url with INFO.
+
+It opens or creates a note with the given ref.
+
+  javascript:location.href = \\='org-protocol://roam-ref?template=r&ref=\\='+ \\
+        encodeURIComponent(location.href) + \\='&title=\\=' + \\
+        encodeURIComponent(document.title) + \\='&body=\\=' + \\
+        encodeURIComponent(window.getSelection())"
+  (unless (plist-get info :ref)
+    (user-error "No ref key provided"))
+  (org-roam-plist-map! (lambda (k v)
+                         (org-link-decode
+                          (if (equal k :ref)
+                              (org-protocol-sanitize-uri v)
+                            v))) info)
+  (when org-roam-protocol-store-links
+    (push (list (plist-get info :ref)
+                (plist-get info :title)) org-stored-links))
+  (org-link-store-props :type (and (string-match org-link-plain-re
+                                                 (plist-get info :ref))
+                                   (match-string 1 (plist-get info :ref)))
+                        :link (plist-get info :ref)
+                        :annotation (org-link-make-string (plist-get info :ref)
+                                                          (or (plist-get info :title)
+                                                              (plist-get info :ref)))
+                        :initial (or (plist-get info :body) ""))
+  (raise-frame)
+  (org-roam-capture-
+   :keys (plist-get info :template)
+   :node (org-roam-node-create :title (plist-get info :title))
+   :info (list :ref (plist-get info :ref)
+               :body (plist-get info :body))
+   :templates org-roam-capture-ref-templates)
+  nil)
+
+(defun org-roam-protocol-open-node (info)
+  "This handler simply opens the file with emacsclient.
+
+INFO is a plist containing additional information passed by the protocol URL.
+It should contain the FILE key, pointing to the path of the file to open.
+
+  Example protocol string:
+
+org-protocol://roam-node?node=uuid"
+  (when-let ((node (plist-get info :node)))
+    (raise-frame)
+    (org-roam-node-visit (org-roam-populate (org-roam-node-create :id node))))
+  nil)
+
+(push '("org-roam-ref"  :protocol "roam-ref"   :function org-roam-protocol-open-ref)
+      org-protocol-protocol-alist)
+(push '("org-roam-node"  :protocol "roam-node"   :function org-roam-protocol-open-node)
+      org-protocol-protocol-alist)
+
+;;; Capture implementation
+(add-hook 'org-roam-capture-preface-hook #'org-roam-protocol--try-capture-to-ref-h)
+(defun org-roam-protocol--try-capture-to-ref-h ()
+  "Try to capture to an existing node that match the ref."
+  (when-let ((node (and (plist-get org-roam-capture--info :ref)
+                        (org-roam-node-from-ref
+                         (plist-get org-roam-capture--info :ref)))))
+    (set-buffer (org-capture-target-buffer (org-roam-node-file node)))
+    (goto-char (org-roam-node-point node))
+    (widen)
+    (org-roam-node-id node)))
+
+(add-hook 'org-roam-capture-new-node-hook #'org-roam-protocol--insert-captured-ref-h)
+(defun org-roam-protocol--insert-captured-ref-h ()
+  "Insert the ref if any."
+  (when-let ((ref (plist-get org-roam-capture--info :ref)))
+    (org-roam-ref-add ref)))
+
+
+(provide 'org-roam-protocol)
+
+;;; org-roam-protocol.el ends here

mkdocs.yml

@@ -1,30 +0,0 @@
-site_name: "Org-Roam: Roam + Org-Mode = ♥"
-repo_url: https://github.com/jethrokuan/org-roam/
-edit_uri: edit/master/doc/
-copyright: "Copyright (C) 2020 Jethro Kuan and contributors"
-docs_dir: doc
-nav:
-- Home: index.md
-- A Tour of Org-Roam: tour.md
-- Installation: installation.md
-- Ecosystem: ecosystem.md
-- Similar Packages: comparison.md
-markdown_extensions:
-  - admonition
-  - pymdownx.betterem:
-      smart_enable: all
-  - pymdownx.caret
-  - pymdownx.critic
-  - pymdownx.details
-  - pymdownx.mark
-  - pymdownx.smartsymbols
-  - pymdownx.superfences
-  - pymdownx.tasklist:
-      custom_checkbox: true
-  - pymdownx.tilde
-
-theme:
-  name: 'material'
-  palette:
-    primary: 'deep purple'
-    accent: 'deep purple'

org-roam-capture.el

@@ -0,0 +1,767 @@
+;;; org-roam-capture.el --- Capture functionality -*- coding: utf-8; lexical-binding: t; -*-
+
+;; Copyright © 2020-2021 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: 2.0.0
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org "9.4") (emacsql "3.0.0") (emacsql-sqlite "1.0.0") (magit-section "2.90.1") (filenotify-recursive "0.0.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 module provides `org-capture' functionality for Org-roam. With this
+;; module the user can capture new nodes or capture new content to existing
+;; nodes.
+;;
+;;; Code:
+(require 'org-roam)
+
+;;;; Declarations
+(defvar org-end-time-was-given)
+
+;;; Options
+(defcustom org-roam-capture-templates
+  '(("d" "default" plain "%?"
+     :if-new (file+head "%<%Y%m%d%H%M%S>-${slug}.org"
+                        "#+title: ${title}\n")
+     :unnarrowed t))
+  "Templates for the creation of new entries within Org-roam.
+
+Each entry is a list with the following items:
+
+keys   The keys that will select the template, as a string, characters only, for
+       example \"a\" for a template to be selected with a single key, or
+       \"bt\" for selection with two keys. When using several keys, keys
+       using the same prefix must be together in the list and preceded by a
+       2-element entry explaining the prefix key, for example:
+
+                   (\"b\" \"Templates for marking stuff to buy\")
+
+       The \"C\" key is used by default for quick access to the customization of
+       the template variable. But if you want to use that key for a template,
+       you can.
+
+description   A short string describing the template, which will be shown
+              during selection.
+
+type       The type of entry. Valid types are:
+               entry       an Org node, with a headline.  Will be filed
+                           as the child of the target entry or as a
+                           top level entry.  Its default template is:
+                             \"* %?\n %a\"
+               item        a plain list item, will be placed in the
+                           first plain list at the target location.
+                           Its default template is:
+                             \"- %?\"
+               checkitem   a checkbox item.  This differs from the
+                           plain list item only in so far as it uses a
+                           different default template.  Its default
+                           template is:
+                             \"- [ ] %?\"
+               table-line  a new line in the first table at target location.
+                           Its default template is:
+                             \"| %? |\"
+               plain       text to be inserted as it is.
+
+template     The template for creating the capture item.
+             If it is an empty string or nil, a default template based on
+             the entry type will be used (see the \"type\" section above).
+             Instead of a string, this may also be one of:
+
+                 (file \"/path/to/template-file\")
+                 (function function-returning-the-template)
+
+             in order to get a template from a file, or dynamically
+             from a function.
+
+The template contains a compulsory :if-new property. This determines the
+location of the new node. The :if-new property contains a list, supporting
+the following options:
+
+   (file \"path/to/file\")
+       The file will be created, and prescribed an ID.
+
+   (file+head \"path/to/file\" \"head content\")
+       The file will be created, prescribed an ID, and head content will be
+       inserted into the file.
+
+   (file+olp \"path/to/file\" (\"h1\" \"h2\"))
+       The file will be created, prescribed an ID. The OLP (h1, h2) will be
+       created, and the point placed after.
+
+   (file+head+olp \"path/to/file\" \"head content\" (\"h1\" \"h2\"))
+       The file will be created, prescribed an ID. Head content will be
+       inserted at the start of the file. The OLP (h1, h2) will be created,
+       and the point placed after.
+
+   (file+datetree \"path/to/file\" day)
+       The file will be created, prescribed an ID. Head content will be
+       inserted at the start of the file. The datetree will be created,
+       available options are day, week, month.
+
+   (node \"title or alias or ID of an existing node\")
+       The point will be placed for an existing node, based on either, its
+       title, alias or ID.
+
+The rest of the entry is a property list of additional options.  Recognized
+properties are:
+
+ :prepend            Normally newly captured information will be appended at
+                     the target location (last child, last table line,
+                     last list item...).  Setting this property will
+                     change that.
+
+ :immediate-finish   When set, do not offer to edit the information, just
+                     file it away immediately.  This makes sense if the
+                     template only needs information that can be added
+                     automatically.
+
+ :jump-to-captured   When set, jump to the captured entry when finished.
+
+ :empty-lines        Set this to the number of lines that should be inserted
+                     before and after the new item.  Default 0, only common
+                     other value is 1.
+
+ :empty-lines-before Set this to the number of lines that should be inserted
+                     before the new item.  Overrides :empty-lines for the
+                     number lines inserted before.
+
+ :empty-lines-after  Set this to the number of lines that should be inserted
+                     after the new item.  Overrides :empty-lines for the
+                     number of lines inserted after.
+
+ :clock-in           Start the clock in this item.
+
+ :clock-keep         Keep the clock running when filing the captured entry.
+
+ :clock-resume       Start the interrupted clock when finishing the capture.
+                     Note that :clock-keep has precedence over :clock-resume.
+                     When setting both to t, the current clock will run and
+                     the previous one will not be resumed.
+
+ :time-prompt        Prompt for a date/time to be used for date/week trees
+                     and when filling the template.
+
+ :tree-type          When `week', make a week tree instead of the month-day
+                     tree.  When `month', make a month tree instead of the
+                     month-day tree.
+
+ :unnarrowed         Do not narrow the target buffer, simply show the
+                     full buffer.  Default is to narrow it so that you
+                     only see the new stuff.
+
+ :table-line-pos     Specification of the location in the table where the
+                     new line should be inserted.  It should be a string like
+                     \"II-3\", meaning that the new line should become the
+                     third line before the second horizontal separator line.
+
+ :kill-buffer        If the target file was not yet visited by a buffer when
+                     capture was invoked, kill the buffer again after capture
+                     is finalized.
+
+ :no-save            Do not save the target file after finishing the capture.
+
+The template defines the text to be inserted.  Often this is an
+Org mode entry (so the first line should start with a star) that
+will be filed as a child of the target headline.  It can also be
+freely formatted text.  Furthermore, the following %-escapes will
+be replaced with content and expanded:
+
+  %[pathname] Insert the contents of the file given by
+              `pathname'.  These placeholders are expanded at the very
+              beginning of the process so they can be used to extend the
+              current template.
+  %(sexp)     Evaluate elisp `(sexp)' and replace it with the results.
+              Only placeholders pre-existing within the template, or
+              introduced with %[pathname] are expanded this way.  Since this
+              happens after expanding non-interactive %-escapes, those can
+              be used to fill the expression.
+  %<...>      The result of `format-time-string' on the ... format specification.
+  %t          Time stamp, date only.  The time stamp is the current time,
+              except when called from agendas with `\\[org-agenda-capture]' or
+              with `org-capture-use-agenda-date' set.
+  %T          Time stamp as above, with date and time.
+  %u, %U      Like the above, but inactive time stamps.
+  %i          Initial content, copied from the active region.  If
+              there is text before %i on the same line, such as
+              indentation, and %i is not inside a %(sexp), that prefix
+              will be added before every line in the inserted text.
+  %a          Annotation, normally the link created with `org-store-link'.
+  %A          Like %a, but prompt for the description part.
+  %l          Like %a, but only insert the literal link.
+  %L          Like %l, but without brackets (the link content itself).
+  %c          Current kill ring head.
+  %x          Content of the X clipboard.
+  %k          Title of currently clocked task.
+  %K          Link to currently clocked task.
+  %n          User name (taken from the variable `user-full-name').
+  %f          File visited by current buffer when `org-capture' was called.
+  %F          Full path of the file or directory visited by current buffer.
+  %:keyword   Specific information for certain link types, see below.
+  %^g         Prompt for tags, with completion on tags in target file.
+  %^G         Prompt for tags, with completion on all tags in all agenda files.
+  %^t         Like %t, but prompt for date.  Similarly %^T, %^u, %^U.
+              You may define a prompt like: %^{Please specify birthday}t.
+              The default date is that of %t, see above.
+  %^C         Interactive selection of which kill or clip to use.
+  %^L         Like %^C, but insert as link.
+  %^{prop}p   Prompt the user for a value for property `prop'.
+              A default value can be specified like this:
+              %^{prop|default}p.
+  %^{prompt}  Prompt the user for a string and replace this sequence with it.
+              A default value and a completion table can be specified like this:
+              %^{prompt|default|completion2|completion3|...}.
+  %?          After completing the template, position cursor here.
+  %\\1 ... %\\N Insert the text entered at the nth %^{prompt}, where N
+              is a number, starting from 1.
+
+Apart from these general escapes, you can access information specific to
+the link type that is created.  For example, calling `org-capture' in emails
+or in Gnus will record the author and the subject of the message, which you
+can access with \"%:from\" and \"%:subject\", respectively.  Here is a
+complete list of what is recorded for each link type.
+
+Link type               |  Available information
+------------------------+------------------------------------------------------
+bbdb                    |  %:type %:name %:company
+vm, wl, mh, mew, rmail, |  %:type %:subject %:message-id
+gnus                    |  %:from %:fromname %:fromaddress
+                        |  %:to   %:toname   %:toaddress
+                        |  %:fromto (either \"to NAME\" or \"from NAME\")
+                        |  %:date %:date-timestamp (as active timestamp)
+                        |  %:date-timestamp-inactive (as inactive timestamp)
+gnus                    |  %:group, for messages also all email fields
+eww, w3, w3m            |  %:type %:url
+info                    |  %:type %:file %:node
+calendar                |  %:type %:date
+
+When you need to insert a literal percent sign in the template,
+you can escape ambiguous cases with a backward slash, e.g., \\%i.
+
+In addition to all of the above, Org-roam supports additional
+substitutions within its templates. \"${foo}\" will look for the
+foo property in the Org-roam node (see the `org-roam-node'). If
+the property does not exist, the user will be prompted to fill in
+the string value.
+
+Org-roam templates are NOT compatible with regular Org capture:
+they rely on additional hacks and hooks to achieve the
+streamlined user experience in Org-roam."
+  :group 'org-roam
+  :type '(repeat
+          (choice (list :tag "Multikey description"
+                        (string :tag "Keys       ")
+                        (string :tag "Description"))
+                  (list :tag "Template entry"
+                        (string :tag "Keys           ")
+                        (string :tag "Description    ")
+                        (choice :tag "Capture Type   " :value entry
+                                (const :tag "Org entry" entry)
+                                (const :tag "Plain list item" item)
+                                (const :tag "Checkbox item" checkitem)
+                                (const :tag "Plain text" plain)
+                                (const :tag "Table line" table-line))
+                        (choice :tag "Template       "
+                                (string)
+                                (list :tag "File"
+                                      (const :format "" file)
+                                      (file :tag "Template file"))
+                                (list :tag "Function"
+                                      (const :format "" function)
+                                      (function :tag "Template function")))
+                        (plist :inline t
+                               ;; Give the most common options as checkboxes
+                               :options (((const :format "%v " :if-new)
+                                          (choice :tag "Node location"
+                                                  (list :tag "File"
+                                                        (const :format "" file)
+                                                        (string :tag "  File"))
+                                                  (list :tag "File & Head Content"
+                                                        (const :format "" file+head)
+                                                        (string :tag "  File")
+                                                        (string :tag "  Head Content"))
+                                                  (list :tag "File & Outline path"
+                                                        (const :format "" file+olp)
+                                                        (string :tag "  File")
+                                                        (list :tag "Outline path"
+                                                              (repeat (string :tag "Headline"))))
+                                                  (list :tag "File & Head Content & Outline path"
+                                                        (const :format "" file+head+olp)
+                                                        (string :tag "  File")
+                                                        (string :tag "  Head Content")
+                                                        (list :tag "Outline path"
+                                                              (repeat (string :tag "Headline"))))))
+                                         ((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 " :unnarrowed) (const t))
+                                         ((const :format "%v " :table-line-pos) (string))
+                                         ((const :format "%v " :kill-buffer) (const t))))))))
+
+(defcustom org-roam-capture-new-node-hook nil
+  "Normal-mode hooks run when a new Org-roam node is created.
+The current point is the point of the new node.
+The hooks must not move the point."
+  :group 'org-roam
+  :type 'hook)
+
+(defvar org-roam-capture-preface-hook nil
+  "Hook run when Org-roam tries to determine capture location of the node.
+If any hook returns a value (which should be an ID), all hooks
+after it are ignored.
+
+With this hook you can hijack controls over the location of the
+node for which the capture process is currently running for, or
+use to just perform an arbitrary side effect, e.g. modify the
+state related to the capture process. See `org-roam-protocol' and
+`org-roam-dailies' as examples for what and how this hook is used
+for.
+
+If you're trying to perform the hijack, it's mandatory for you to:
+  1. Set the currently active buffer for editing operations using
+     `org-capture-target-buffer'.
+  2. Place the point in this buffer from where the location starts
+     from (e.g. if it's a file based node it should be the BOB,
+     otherwise it should be the position from where the heading
+     based node starts from).
+  3. Return the ID (as a string) of the capturing node.
+
+If you use this hook for any other purpose, but not the hijack,
+it's mandatory that you should return nil as the return value; so
+the capture process would be able to setup the capture buffer.
+
+If you need to do something when you capture new nodes, use
+`org-roam-capture-new-node-hook' instead of this hook.
+
+WARNING: This hook is primarily designed for the usage by the
+extensions and packages, and requires understanding of the
+internal capture process. If you don't understand it, you should
+learn these internals before using this or use it at your own
+risk breaking things.")
+
+;;; Variables
+
+(defvar org-roam-capture--node nil
+  "The node passed during an Org-roam capture.
+This variable is populated dynamically, and is only non-nil
+during the Org-roam capture process.")
+
+(defvar org-roam-capture--info nil
+  "A property-list of additional information passed to the Org-roam template.
+This variable is populated dynamically, and is only non-nil
+during the Org-roam capture process.")
+
+(defconst org-roam-capture--template-keywords (list :if-new :id :link-description :call-location
+                                                    :region)
+  "Keywords used in `org-roam-capture-templates' specific to Org-roam.")
+
+;;; Main entry point
+;;;###autoload
+(cl-defun org-roam-capture- (&key goto keys node info props templates)
+  "Main entry point of `org-roam-capture' module.
+GOTO and KEYS correspond to `org-capture' arguments.
+INFO is a plist for filling up Org-roam's capture templates.
+NODE is an `org-roam-node' construct containing information about the node.
+PROPS is a plist containing additional Org-roam properties for each template.
+TEMPLATES is a list of org-roam templates."
+  (let* ((props (plist-put props :call-location (point-marker)))
+         (org-capture-templates
+          (mapcar (lambda (template)
+                    (org-roam-capture--convert-template template props))
+                  (or templates org-roam-capture-templates)))
+         (org-roam-capture--node node)
+         (org-roam-capture--info info))
+    (when (and (not keys)
+               (= (length org-capture-templates) 1))
+      (setq keys (caar org-capture-templates)))
+    (org-capture goto keys)))
+
+;;;###autoload
+(cl-defun org-roam-capture (&optional goto keys &key filter-fn templates info)
+  "Launches an `org-capture' process for a new or existing node.
+This uses the templates defined at `org-roam-capture-templates'.
+Arguments GOTO and KEYS see `org-capture'.
+FILTER-FN is a function to filter out nodes: it takes an `org-roam-node',
+and when nil is returned the node will be filtered out.
+The TEMPLATES, if provided, override the list of capture templates (see
+`org-roam-capture-'.)
+The INFO, if provided, is passed along to the underlying `org-roam-capture-'."
+  (interactive "P")
+  (let ((node (org-roam-node-read nil filter-fn)))
+    (org-roam-capture- :goto goto
+                       :info info
+                       :keys keys
+                       :templates templates
+                       :node node
+                       :props '(:immediate-finish nil))))
+
+;;; Capture process
+(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)
+  "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)
+  "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 org-capture-plist
+          (plist-put org-capture-plist :org-roam p))))
+
+;;;; Capture target
+(defun org-roam-capture--prepare-buffer ()
+  "Prepare the capture buffer for the current Org-roam based capture template.
+This function will initialize and setup the capture buffer,
+create the target node (`:if-new') if it doesn't exist, and place
+the point for further processing by `org-capture'.
+
+Note: During the capture process this function is run by
+`org-capture-set-target-location', as a (function ...) based
+capture target."
+  (let ((id (cond ((run-hook-with-args-until-success 'org-roam-capture-preface-hook))
+                  ((and (org-roam-node-file org-roam-capture--node)
+                        (org-roam-node-point org-roam-capture--node))
+                   (set-buffer (org-capture-target-buffer (org-roam-node-file org-roam-capture--node)))
+                   (goto-char (org-roam-node-point org-roam-capture--node))
+                   (widen)
+                   (org-roam-node-id org-roam-capture--node))
+                  (t
+                   (org-roam-capture--setup-target-location)))))
+    (org-roam-capture--adjust-point-for-capture-type)
+    (org-capture-put :template
+                     (org-roam-capture--fill-template (org-capture-get :template)))
+    (org-roam-capture--put :id id)
+    (org-roam-capture--put :finalize (or (org-capture-get :finalize)
+                                         (org-roam-capture--get :finalize)))))
+
+(defun org-roam-capture--setup-target-location ()
+  "Initialize the buffer, and goto the location of the new capture.
+Return the ID of the location."
+  (let (p new-file-p)
+    (pcase (or (org-roam-capture--get :if-new)
+               (user-error "Template needs to specify `:if-new'"))
+      (`(file ,path)
+       (setq path (expand-file-name
+                   (string-trim (org-roam-capture--fill-template path t))
+                   org-roam-directory))
+       (setq new-file-p (org-roam-capture--new-file-p path))
+       (when new-file-p (org-roam-capture--put :new-file path))
+       (set-buffer (org-capture-target-buffer path))
+       (widen)
+       (setq p (goto-char (point-min))))
+      (`(file+olp ,path ,olp)
+       (setq path (expand-file-name
+                   (string-trim (org-roam-capture--fill-template path t))
+                   org-roam-directory))
+       (setq new-file-p (org-roam-capture--new-file-p path))
+       (when new-file-p (org-roam-capture--put :new-file path))
+       (set-buffer (org-capture-target-buffer path))
+       (setq p (point-min))
+       (let ((m (org-roam-capture-find-or-create-olp olp)))
+         (goto-char m))
+       (widen))
+      (`(file+head ,path ,head)
+       (setq path (expand-file-name
+                   (string-trim (org-roam-capture--fill-template path t))
+                   org-roam-directory))
+       (setq new-file-p (org-roam-capture--new-file-p path))
+       (set-buffer (org-capture-target-buffer path))
+       (when new-file-p
+         (org-roam-capture--put :new-file path)
+         (insert (org-roam-capture--fill-template head t)))
+       (widen)
+       (setq p (goto-char (point-min))))
+      (`(file+head+olp ,path ,head ,olp)
+       (setq path (expand-file-name
+                   (string-trim (org-roam-capture--fill-template path t))
+                   org-roam-directory))
+       (setq new-file-p (org-roam-capture--new-file-p path))
+       (set-buffer (org-capture-target-buffer path))
+       (widen)
+       (when new-file-p
+         (org-roam-capture--put :new-file path)
+         (insert (org-roam-capture--fill-template head t)))
+       (setq p (point-min))
+       (let ((m (org-roam-capture-find-or-create-olp olp)))
+         (goto-char m)))
+      (`(file+datetree ,path ,tree-type)
+       (setq path (expand-file-name
+                   (string-trim (org-roam-capture--fill-template path t))
+                   org-roam-directory))
+       (require 'org-datetree)
+       (widen)
+       (set-buffer (org-capture-target-buffer path))
+       (unless (file-exists-p path)
+         (org-roam-capture--put :new-file path))
+       (funcall
+        (pcase tree-type
+          (`week #'org-datetree-find-iso-week-create)
+          (`month #'org-datetree-find-month-create)
+          (_ #'org-datetree-find-date-create))
+        (calendar-gregorian-from-absolute
+         (cond
+          (org-overriding-default-time
+           ;; Use the overriding default time.
+           (time-to-days org-overriding-default-time))
+          ((org-capture-get :default-time)
+           (time-to-days (org-capture-get :default-time)))
+          ((org-capture-get :time-prompt)
+           ;; Prompt for date.  Bind `org-end-time-was-given' so
+           ;; that `org-read-date-analyze' handles the time range
+           ;; case and returns `prompt-time' with the start value.
+           (let* ((org-time-was-given nil)
+                  (org-end-time-was-given nil)
+                  (prompt-time (org-read-date
+                                nil t nil "Date for tree entry:")))
+             (org-capture-put
+              :default-time
+              (if (or org-time-was-given
+                      (= (time-to-days prompt-time) (org-today)))
+                  prompt-time
+                ;; Use 00:00 when no time is given for another
+                ;; date than today?
+                (apply #'encode-time 0 0
+                       org-extend-today-until
+                       (cl-cdddr (decode-time prompt-time)))))
+             (time-to-days prompt-time)))
+          (t
+           ;; Current date, possibly corrected for late night
+           ;; workers.
+           (org-today)))))
+       (setq p (point)))
+      (`(node ,title-or-id)
+       ;; first try to get ID, then try to get title/alias
+       (let ((node (or (org-roam-node-from-id title-or-id)
+                       (org-roam-node-from-title-or-alias title-or-id)
+                       (user-error "No node with title or id \"%s\"" title-or-id))))
+         (set-buffer (org-capture-target-buffer (org-roam-node-file node)))
+         (goto-char (org-roam-node-point node))
+         (setq p (org-roam-node-point node)))))
+    ;; Setup `org-id' for the current capture target and return it back to the
+    ;; caller.
+    (save-excursion
+      (goto-char p)
+      (when-let* ((node org-roam-capture--node)
+                  (id (org-roam-node-id node)))
+        (org-entry-put p "ID" id))
+      (prog1
+          (org-id-get-create)
+        (run-hooks 'org-roam-capture-new-node-hook)))))
+
+(defun org-roam-capture--new-file-p (path)
+  "Return t if PATH is for a new file with no visiting buffer."
+  (not (or (file-exists-p path)
+           (org-find-base-buffer-visiting path))))
+
+(defun org-roam-capture-find-or-create-olp (olp)
+  "Return a marker pointing to the entry at OLP in the current buffer.
+If OLP does not exist, create it. If anything goes wrong, throw
+an error, and if you need to do something based on this error,
+you can catch it with `condition-case'."
+  (let* ((level 1)
+         (lmin 1)
+         (lmax 1)
+         (start (point-min))
+         (end (point-max))
+         found flevel)
+    (unless (derived-mode-p 'org-mode)
+      (error "Buffer %s needs to be in Org mode" (current-buffer)))
+    (org-with-wide-buffer
+     (goto-char start)
+     (dolist (heading olp)
+       (let ((re (format org-complex-heading-regexp-format
+                         (regexp-quote heading)))
+             (cnt 0))
+         (while (re-search-forward re end t)
+           (setq level (- (match-end 1) (match-beginning 1)))
+           (when (and (>= level lmin) (<= level lmax))
+             (setq found (match-beginning 0) flevel level cnt (1+ cnt))))
+         (when (> cnt 1)
+           (error "Heading not unique on level %d: %s" lmax heading))
+         (when (= cnt 0)
+           ;; Create heading if it doesn't exist
+           (goto-char end)
+           (unless (bolp) (newline))
+           (let (org-insert-heading-respect-content)
+             (org-insert-heading nil nil t))
+           (unless (= lmax 1)
+             (dotimes (_ level) (org-do-demote)))
+           (insert heading)
+           (setq end (point))
+           (goto-char start)
+           (while (re-search-forward re end t)
+             (setq level (- (match-end 1) (match-beginning 1)))
+             (when (and (>= level lmin) (<= level lmax))
+               (setq found (match-beginning 0) flevel level cnt (1+ cnt))))))
+       (goto-char found)
+       (setq lmin (1+ flevel) lmax (+ lmin (if org-odd-levels-only 1 0)))
+       (setq start found
+             end (save-excursion (org-end-of-subtree t t))))
+     (point-marker))))
+
+(defun org-roam-capture--adjust-point-for-capture-type (&optional pos)
+  "Reposition the point for template insertion dependently on the capture type.
+Return the newly adjusted position of `point'.
+
+POS is the current position of point (an integer) inside the
+currently active capture buffer, where the adjustment should
+start to begin from. If it's nil, then it will default to
+the current value of `point'."
+  (or pos (setq pos (point)))
+  (goto-char pos)
+  (let ((location-type (if (= pos 1) 'beginning-of-file 'heading-at-point)))
+    (and (eq location-type 'heading-at-point)
+         (cl-assert (org-at-heading-p)))
+    (pcase (org-capture-get :type)
+      (`plain
+       (cl-case location-type
+         (beginning-of-file
+          (if (org-capture-get :prepend)
+              (let ((el (org-element-at-point)))
+                (while (and (not (eobp))
+                            (memq (org-element-type el)
+                                  '(drawer property-drawer keyword comment comment-block horizontal-rule)))
+                  (goto-char (org-element-property :end el))
+                  (setq el (org-element-at-point))))
+            (goto-char (org-entry-end-position))))
+         (heading-at-point
+          (if (org-capture-get :prepend)
+              (org-end-of-meta-data t)
+            (goto-char (org-entry-end-position))))))))
+  (point))
+
+;;;; Finalizers
+(add-hook 'org-capture-prepare-finalize-hook #'org-roam-capture--install-finalize-h)
+(defun org-roam-capture--install-finalize-h ()
+  "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)))
+
+(defun org-roam-capture--finalize ()
+  "Finalize the `org-roam-capture' process."
+  (when-let ((region (org-roam-capture--get :region)))
+    (org-roam-unshield-region (car region) (cdr region)))
+  (if org-note-abort
+      (when-let ((new-file (org-roam-capture--get :new-file)))
+        (org-roam-message "Deleting file for aborted capture %s" new-file)
+        (when (find-buffer-visiting new-file)
+          (kill-buffer (find-buffer-visiting new-file)))
+        (delete-file new-file))
+    (when-let* ((finalize (org-roam-capture--get :finalize))
+                (org-roam-finalize-fn (intern (concat "org-roam-capture--finalize-"
+                                                      (symbol-name finalize)))))
+      (if (functionp org-roam-finalize-fn)
+          (funcall org-roam-finalize-fn)
+        (funcall finalize))))
+  (remove-hook 'org-capture-after-finalize-hook #'org-roam-capture--finalize))
+
+(defun org-roam-capture--finalize-find-file ()
+  "Visit the buffer after Org-capture is done.
+This function is to be called in the Org-capture finalization process.
+ID is unused."
+  (switch-to-buffer (org-capture-get :buffer)))
+
+(defun org-roam-capture--finalize-insert-link ()
+  "Insert a link to ID into the buffer where Org-capture was called.
+ID is the Org id of the newly captured content.
+This function is to be called in the Org-capture finalization process."
+  (when-let* ((mkr (org-roam-capture--get :call-location))
+              (buf (marker-buffer mkr)))
+    (with-current-buffer buf
+      (when-let ((region (org-roam-capture--get :region)))
+        (org-roam-unshield-region (car region) (cdr region))
+        (delete-region (car region) (cdr region))
+        (set-marker (car region) nil)
+        (set-marker (cdr region) nil))
+      (org-with-point-at mkr
+        (insert (org-link-make-string (concat "id:" (org-roam-capture--get :id))
+                                      (org-roam-capture--get :link-description)))))))
+
+;;;; Processing of the capture templates
+(defun org-roam-capture--fill-template (template &optional org-capture-p)
+  "Expand TEMPLATE and return it.
+It expands ${var} occurrences in TEMPLATE. When ORG-CAPTURE-P,
+also run Org-capture's template expansion."
+  (funcall (if org-capture-p #'org-capture-fill-template #'identity)
+           (org-roam-format-template
+            template
+            (lambda (key default-val)
+              (let ((fn (intern key))
+                    (node-fn (intern (concat "org-roam-node-" key)))
+                    (ksym (intern (concat ":" key))))
+                (cond
+                 ((fboundp fn)
+                  (funcall fn org-roam-capture--node))
+                 ((fboundp node-fn)
+                  (funcall node-fn org-roam-capture--node))
+                 ((plist-get org-roam-capture--info ksym)
+                  (plist-get org-roam-capture--info ksym))
+                 (t (let ((r (completing-read (format "%s: " key) nil nil nil default-val)))
+                      (plist-put org-roam-capture--info ksym r)
+                      r))))))))
+
+(defun org-roam-capture--convert-template (template &optional props)
+  "Convert TEMPLATE from Org-roam syntax to `org-capture-templates' syntax.
+PROPS is a plist containing additional Org-roam specific
+properties to be added to the template."
+  (pcase template
+    (`(,_key ,_desc)
+     template)
+    ((or `(,key ,desc ,type ignore ,body . ,rest)
+         `(,key ,desc ,type (function ignore) ,body . ,rest)
+         `(,key ,desc ,type ,body . ,rest))
+     (setq rest (append rest props))
+     (let (org-roam-plist options)
+       (while rest
+         (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))
+           (if custom
+               (setq org-roam-plist (plist-put org-roam-plist key val))
+             (setq options (plist-put options key val)))))
+       (append `(,key ,desc ,type #'org-roam-capture--prepare-buffer ,body)
+               options
+               (list :org-roam org-roam-plist))))
+    (_
+     (signal 'invalid-template template))))
+
+
+(provide 'org-roam-capture)
+
+;;; org-roam-capture.el ends here

org-roam-compat.el

@@ -0,0 +1,210 @@
+;;; org-roam-compat.el --- Backward compatibility code -*- coding: utf-8; lexical-binding: t; -*-
+
+;; Copyright © 2020-2021 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: 2.0.0
+;; 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 is dedicated to maintain backward compatibility with older older
+;; Emacsen and Org-roam versions.
+;;
+;;; Code:
+;;; Backports
+;; REVIEW Remove when 26.x support is dropped. This is exact the same as
+;; `directory-files-recursively' from Emacs 26, but with FOLLOW-SYMLINKS
+;; parameter from Emacs 27.
+(defun org-roam--directory-files-recursively (dir regexp
+                                                  &optional include-directories predicate
+                                                  follow-symlinks)
+  "Return list of all files under directory DIR whose names match REGEXP.
+This function works recursively.  Files are returned in \"depth
+first\" order, and files from each directory are sorted in
+alphabetical order.  Each file name appears in the returned list
+in its absolute form.
+
+By default, the returned list excludes directories, but if
+optional argument INCLUDE-DIRECTORIES is non-nil, they are
+included.
+
+PREDICATE can be either nil (which means that all subdirectories
+of DIR are descended into), t (which means that subdirectories that
+can't be read are ignored), or a function (which is called with
+the name of each subdirectory, and should return non-nil if the
+subdirectory is to be descended into).
+
+If FOLLOW-SYMLINKS is non-nil, symbolic links that point to
+directories are followed.  Note that this can lead to infinite
+recursion."
+  (let* ((result nil)
+         (files nil)
+         (dir (directory-file-name dir))
+         ;; When DIR is "/", remote file names like "/method:" could
+         ;; also be offered.  We shall suppress them.
+         (tramp-mode (and tramp-mode (file-remote-p (expand-file-name dir)))))
+    (dolist (file (sort (file-name-all-completions "" dir)
+                        'string<))
+      (unless (member file '("./" "../"))
+        (if (directory-name-p file)
+            (let* ((leaf (substring file 0 (1- (length file))))
+                   (full-file (concat dir "/" leaf)))
+              ;; Don't follow symlinks to other directories.
+              (when (and (or (not (file-symlink-p full-file))
+                             (and (file-symlink-p full-file)
+                                  follow-symlinks))
+                         ;; Allow filtering subdirectories.
+                         (or (eq predicate nil)
+                             (eq predicate t)
+                             (funcall predicate full-file)))
+                (let ((sub-files
+                       (if (eq predicate t)
+                           (condition-case nil
+                               (org-roam--directory-files-recursively
+                                full-file regexp include-directories
+                                predicate follow-symlinks)
+                             (file-error nil))
+                         (org-roam--directory-files-recursively
+                          full-file regexp include-directories
+                          predicate follow-symlinks))))
+                  (setq result (nconc result sub-files))))
+              (when (and include-directories
+                         (string-match regexp leaf))
+                (setq result (nconc result (list full-file)))))
+          (when (string-match regexp file)
+            (push (concat dir "/" file) files)))))
+    (nconc result (nreverse files))))
+
+;;; Compatibility hacks and patches
+(advice-add #'org-id-add-location :around #'org-roam--handle-absent-org-id-locations-file-a)
+(defun org-roam--handle-absent-org-id-locations-file-a (fn &rest args)
+  "Gracefully handle errors related to absence of `org-id-locations-file'.
+FN is `org-id-locations-file' that comes from advice and ARGS are
+passed to it."
+  (let (result)
+    ;; Use `unwind-protect' over `condition-case' because `org-id' can produce various other errors, but all
+    ;; of its errors are generic ones, so trapping all of them isn't a good idea and preserving the correct
+    ;; backtrace is valuable.
+    (unwind-protect (setq result (apply fn args))
+      (unless result
+        (unless org-id-locations
+          ;; Pre-allocate the hash table to avoid weird access related errors during the regeneration.
+          (setq org-id-locations (make-hash-table :type 'equal)))
+        ;; `org-id' makes the assumption that `org-id-locations-file' will be stored in `user-emacs-directory'
+        ;; which always exist if you have Emacs, so it uses `with-temp-file' to write to the file. However,
+        ;; the users *do* change the path to this file and `with-temp-file' unable to create the file, if the
+        ;; path to it consists of directories that don't exist. We'll have to handle this ourselves.
+        (unless (file-exists-p (file-truename org-id-locations-file))
+          ;; If permissions allow that, try to create the user specified directory path to
+          ;; `org-id-locations-file' ourselves.
+          (condition-case _err
+              (progn (org-roam-message (concat "`org-id-locations-file' (%s) doesn't exist. "
+                                               "Trying to regenerate it (this may take a while)...")
+                                       org-id-locations-file)
+                     (make-directory (file-name-directory (file-truename org-id-locations-file)))
+                     (org-roam-update-org-id-locations)
+                     (apply fn args))
+            ;; In case of failure (lack of permissions), we'll patch it to at least handle the current session
+            ;; without errors.
+            (file-error (org-roam-message "Failed to regenerate `org-id-locations-file'")
+                        (lwarn 'org-roam :error "
+--------
+WARNING: `org-id-locations-file' (%s) doesn't exist!
+         Org-roam is unable to create it for you.
+--------
+
+This happens when Emacs doesn't have permissions to create the
+path to your `org-id-locations-file'. Org-roam will now fallback
+storing the file in your current `org-roam-directory', but the
+warning will keep popup with each new session.
+
+To stop this warning from popping up, set `org-id-locations-file'
+to the location you want and ensure that the path exists on your
+filesystem, then run M-x `org-roam-update-org-id-locations'.
+
+Note: While Org-roam doesn't depend on `org-id-locations-file' to
+lookup IDs for the nodes that are stored in the database, it
+still tries to keep it updated so IDs work across other files in
+Org-mode, so the IDs used in your `org-roam-directory' would be
+able to cross-reference outside of `org-roam-directory'. It also
+allows to keep linking with \"id:\" links within the current
+`org-roam-directory' to headings and files that are excluded from
+identification (e.g. with \"ROAM_EXCLUDE\" property) as Org-roam
+nodes." org-id-locations-file)
+                        (setq org-id-locations-file
+                              (expand-file-name ".orgids" (file-truename org-roam-directory)))
+                        (apply fn args)))))
+      result)))
+
+;;; Obsolete aliases (remove after next major release)
+(define-obsolete-function-alias
+  'org-roam-setup
+  'org-roam-db-autosync-enable "org-roam 2.0")
+(define-obsolete-function-alias
+  'org-roam-teardown
+  'org-roam-db-autosync-disable "org-roam 2.0")
+(define-obsolete-variable-alias
+  'org-roam-db-update-on-save
+  'org-roam-db-autosync-update-method "org-roam 2.0")
+
+(define-obsolete-variable-alias
+  'org-roam-current-node
+  'org-roam-buffer-current-node "org-roam 2.0")
+(define-obsolete-variable-alias
+  'org-roam-current-directory
+  'org-roam-buffer-current-directory "org-roam 2.0")
+(define-obsolete-function-alias
+  'org-roam-buffer-render
+  'org-roam-buffer-render-contents "org-roam 2.0")
+(define-obsolete-function-alias
+  'org-roam-buffer
+  'org-roam-buffer-display-dedicated "org-roam 2.0")
+(define-obsolete-function-alias
+  'org-roam-visit-thing
+  'org-roam-buffer-visit-thing "org-roam 2.0")
+
+(define-obsolete-function-alias
+  'org-roam-dailies-find-today
+  'org-roam-dailies-goto-today "org-roam 2.0")
+(define-obsolete-function-alias
+  'org-roam-dailies-find-yesterday
+  'org-roam-dailies-goto-yesterday "org-roam 2.0")
+(define-obsolete-function-alias
+  'org-roam-dailies-find-tomorrow
+  'org-roam-dailies-goto-tomorrow "org-roam 2.0")
+(define-obsolete-function-alias
+  'org-roam-dailies-find-next-note
+  'org-roam-dailies-goto-next-note "org-roam 2.0")
+(define-obsolete-function-alias
+  'org-roam-dailies-find-previous-note
+  'org-roam-dailies-goto-previous-note "org-roam 2.0")
+(define-obsolete-function-alias
+  'org-roam-dailies-find-date
+  'org-roam-dailies-goto-date "org-roam 2.0")
+
+;;; Obsolete functions
+(make-obsolete 'org-roam-get-keyword 'org-collect-keywords "org-roam 2.0")
+
+(provide 'org-roam-compat)
+
+;;; org-roam-compat.el ends here

org-roam-db.el

@@ -0,0 +1,709 @@
+;;; org-roam-db.el --- Org-roam database API -*- coding: utf-8; lexical-binding: t; -*-
+
+;; Copyright © 2020-2021 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: 2.0.0
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org "9.4") (emacsql "3.0.0") (emacsql-sqlite "1.0.0") (magit-section "2.90.1") (filenotify-recursive "0.0.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 module provides the underlying database API to Org-roam.
+;;
+;;; Code:
+(require 'org-roam)
+(require 'filenotify)
+(require 'filenotify-recursive)
+
+(defvar org-outline-path-cache)
+
+;;; Options
+(defcustom org-roam-db-location (expand-file-name "org-roam.db" user-emacs-directory)
+  "The path to file where the Org-roam database is stored.
+
+It is the user's responsibility to set this correctly, especially
+when used with multiple Org-roam instances."
+  :type 'string
+  :group 'org-roam)
+
+(defcustom org-roam-db-gc-threshold gc-cons-threshold
+  "The value to temporarily set the `gc-cons-threshold' threshold to.
+During `org-roam-db-sync', Emacs can pause multiple times to
+perform garbage collection because of the large number of
+temporary structures generated (e.g. parsed ASTs).
+
+`gc-cons-threshold' is temporarily set to
+`org-roam-db-gc-threshold' during this operation, and increasing
+`gc-cons-threshold' will help reduce the number of GC operations,
+at the cost of memory usage. Tweaking this value may lead to
+better overall performance.
+
+For example, to reduce the number of GCs to the minimum, on
+machines with large memory one may set it to
+`most-positive-fixnum'."
+  :type 'int
+  :group 'org-roam)
+
+(defcustom org-roam-db-node-include-function (lambda () t)
+  "A custom function to check if the point contains a valid node.
+This function is called each time a node (both file and headline)
+is about to be saved into the Org-roam database.
+
+If the function returns nil, Org-roam will skip the node. This
+function is useful for excluding certain nodes from the Org-roam
+database."
+  :type 'function
+  :group 'org-roam)
+
+(defcustom org-roam-db-autosync-update-method
+  (if file-notify--library 'filenotify 'on-save)
+  "What method to use to keep Org-roam's database updated.
+
+  'filenotify
+    Update Org-roam upon detecting changes from the filesystem using
+    file watchers. Requires Emacs that's compiled with support for
+    file notifications.
+
+  'on-save
+    Update the database whenever Emacs buffer that visits an Org-roam
+    file is saved. Unlike `filenotify' this won't be able to react to
+    external changes in the filesystem.
+
+  nil
+    Do not automatically update the Org-roam database."
+  :type '(choice (const :tag "Filenotify" filenotify)
+                 (const :tag "On save" onsave)
+                 (const :tag "Do not autoupdate" nil))
+  :group 'org-roam)
+
+;;; Initialization
+(defconst org-roam-db-version 16)
+
+(defvar org-roam-db--connection (make-hash-table :test #'equal)
+  "Database connection to Org-roam database.")
+
+(defconst org-roam--sqlite-available-p
+  (with-demoted-errors "Org-roam initialization: %S"
+    (emacsql-sqlite-ensure-binary)
+    t))
+
+(defun org-roam-db--get-connection ()
+  "Return the database connection, if any."
+  (gethash (expand-file-name org-roam-directory)
+           org-roam-db--connection))
+
+(defun org-roam-db ()
+  "Entrypoint to the Org-roam sqlite database.
+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 ((init-db (not (file-exists-p org-roam-db-location))))
+      (make-directory (file-name-directory org-roam-db-location) t)
+      (let ((conn (emacsql-sqlite org-roam-db-location)))
+        (set-process-query-on-exit-flag (emacsql-process conn) nil)
+        (puthash (expand-file-name org-roam-directory)
+                 conn
+                 org-roam-db--connection)
+        (when init-db
+          (org-roam-db--init conn))
+        (let* ((version (caar (emacsql conn "PRAGMA user_version")))
+               (version (org-roam-db--upgrade-maybe conn version)))
+          (cond
+           ((> version org-roam-db-version)
+            (emacsql-close conn)
+            (user-error
+             "The Org-roam database was created with a newer Org-roam version.  "
+             "You need to update the Org-roam package"))
+           ((< version org-roam-db-version)
+            (emacsql-close conn)
+            (error "BUG: The Org-roam database scheme changed %s"
+                   "and there is no upgrade path")))))))
+  (org-roam-db--get-connection))
+
+;;; Entrypoint: (org-roam-db-query)
+(define-error 'emacsql-constraint "SQL constraint violation")
+(defun org-roam-db-query (sql &rest args)
+  "Run SQL query on Org-roam database with ARGS.
+SQL can be either the emacsql vector representation, or a string."
+  (apply #'emacsql (org-roam-db) sql args))
+
+(defun org-roam-db-query! (handler sql &rest args)
+  "Run SQL query on Org-roam database with ARGS.
+SQL can be either the emacsql vector representation, or a string.
+The query is expected to be able to fail, in this situation, run HANDLER."
+  (condition-case err
+      (org-roam-db-query sql args)
+    (emacsql-constraint
+     (funcall handler err))))
+
+;;; Schemata
+(defconst org-roam-db--table-schemata
+  '((files
+     [(file :unique :primary-key)
+      (hash :not-null)
+      (atime :not-null)
+      (mtime :not-null)])
+
+    (nodes
+     ([(id :not-null :primary-key)
+       (file :not-null)
+       (level :not-null)
+       (pos :not-null)
+       todo
+       priority
+       (scheduled text)
+       (deadline text)
+       title
+       properties
+       olp]
+      (:foreign-key [file] :references files [file] :on-delete :cascade)))
+
+    (aliases
+     ([(node-id :not-null)
+       alias]
+      (:foreign-key [node-id] :references nodes [id] :on-delete :cascade)))
+
+    (refs
+     ([(node-id :not-null)
+       (ref :not-null)
+       (type :not-null)]
+      (:foreign-key [node-id] :references nodes [id] :on-delete :cascade)))
+
+    (tags
+     ([(node-id :not-null)
+       tag]
+      (:foreign-key [node-id] :references nodes [id] :on-delete :cascade)))
+
+    (links
+     ([(pos :not-null)
+       (source :not-null)
+       (dest :not-null)
+       (type :not-null)
+       (properties :not-null)]
+      (:foreign-key [source] :references nodes [id] :on-delete :cascade)))))
+
+(defconst org-roam-db--table-indices
+  '((alias-node-id aliases [node-id])
+    (refs-node-id refs [node-id])
+    (tags-node-id tags [node-id])))
+
+(defun org-roam-db--init (db)
+  "Initialize database DB with the correct schema and user version."
+  (emacsql-with-transaction db
+    (emacsql db "PRAGMA foreign_keys = ON")
+    (pcase-dolist (`(,table ,schema) org-roam-db--table-schemata)
+      (emacsql db [:create-table $i1 $S2] table schema))
+    (pcase-dolist (`(,index-name ,table ,columns) org-roam-db--table-indices)
+      (emacsql db [:create-index $i1 :on $i2 $S3] index-name table columns))
+    (emacsql db (format "PRAGMA user_version = %s" org-roam-db-version))))
+
+(defun org-roam-db--upgrade-maybe (db version)
+  "Upgrades the database schema for DB, if VERSION is old."
+  (emacsql-with-transaction db
+    'ignore
+    (if (< version org-roam-db-version)
+        (progn
+          (org-roam-message (format "Upgrading the Org-roam database from version %d to version %d"
+                                    version org-roam-db-version))
+          (org-roam-db-sync t))))
+  version)
+
+(defun org-roam-db--close (&optional db)
+  "Closes the database connection for database DB.
+If DB is nil, closes the database connection for the database in
+the current `org-roam-directory'."
+  (unless db
+    (setq db (org-roam-db--get-connection)))
+  (when (and db (emacsql-live-p db))
+    (emacsql-close db)))
+
+(defun org-roam-db--close-all ()
+  "Closes all database connections made by Org-roam."
+  (dolist (conn (hash-table-values org-roam-db--connection))
+    (org-roam-db--close conn)))
+
+;;; Database API
+;;;; Clearing
+(defun org-roam-db-clear-all ()
+  "Clears all entries in the Org-roam cache."
+  (interactive)
+  (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 file)
+  "Remove any related links to the FILE.
+This is equivalent to removing the node from the graph.
+If FILE is nil, clear the current buffer."
+  (setq file (or file (buffer-file-name (buffer-base-buffer))))
+  (org-roam-db-query [:delete :from files
+                      :where (= file $s1)]
+                     file))
+
+;;;; Updating tables
+(defun org-roam-db-insert-file ()
+  "Update the files table for the current buffer.
+If UPDATE-P is non-nil, first remove the file in the database."
+  (let* ((file (buffer-file-name))
+         (attr (file-attributes file))
+         (atime (file-attribute-access-time attr))
+         (mtime (file-attribute-modification-time attr))
+         (hash (org-roam-db--file-hash)))
+    (org-roam-db-query
+     [:insert :into files
+      :values $v1]
+     (list (vector file hash atime mtime)))))
+
+(defun org-roam-db-get-scheduled-time ()
+  "Return the scheduled time at point in ISO8601 format."
+  (when-let ((time (org-get-scheduled-time (point))))
+    (org-format-time-string "%FT%T%z" time)))
+
+(defun org-roam-db-get-deadline-time ()
+  "Return the deadline time at point in ISO8601 format."
+  (when-let ((time (org-get-deadline-time (point))))
+    (org-format-time-string "%FT%T%z" time)))
+
+(defun org-roam-db-node-p ()
+  "Return t if headline at point is an Org-roam node, else return nil."
+  (and (org-id-get)
+       (not (cdr (assoc "ROAM_EXCLUDE" (org-entry-properties))))
+       (funcall org-roam-db-node-include-function)))
+
+(defun org-roam-db-map-nodes (fns)
+  "Run FNS over all nodes in the current buffer."
+  (org-with-point-at 1
+    (org-map-entries
+     (lambda ()
+       (when (org-roam-db-node-p)
+         (dolist (fn fns)
+           (funcall fn)))))))
+
+(defun org-roam-db-map-links (fns)
+  "Run FNS over all links in the current buffer."
+  (org-with-point-at 1
+    (org-element-map (org-element-parse-buffer) 'link
+      (lambda (link)
+        (dolist (fn fns)
+          (funcall fn link))))))
+
+(defun org-roam-db-insert-file-node ()
+  "Insert the file-level node into the Org-roam cache."
+  (org-with-point-at 1
+    (when (and (= (org-outline-level) 0)
+               (org-roam-db-node-p))
+      (when-let ((id (org-id-get)))
+        (let* ((file (buffer-file-name (buffer-base-buffer)))
+               (title (org-link-display-format
+                       (or (cadr (assoc "TITLE" (org-collect-keywords '("title"))
+                                        #'string-equal))
+                           (file-relative-name file org-roam-directory))))
+               (pos (point))
+               (todo nil)
+               (priority nil)
+               (scheduled nil)
+               (deadline nil)
+               (level 0)
+               (aliases (org-entry-get (point) "ROAM_ALIASES"))
+               (tags org-file-tags)
+               (refs (org-entry-get (point) "ROAM_REFS"))
+               (properties (org-entry-properties))
+               (olp nil))
+          (org-roam-db-query!
+           (lambda (err)
+             (lwarn 'org-roam :warning "%s for %s (%s) in %s"
+                    (error-message-string err)
+                    title id file))
+           [:insert :into nodes
+            :values $v1]
+           (vector id file level pos todo priority
+                   scheduled deadline title properties olp))
+          (when tags
+            (org-roam-db-query
+             [:insert :into tags
+              :values $v1]
+             (mapcar (lambda (tag)
+                       (vector id (substring-no-properties tag)))
+                     tags)))
+          (when aliases
+            (org-roam-db-query
+             [:insert :into aliases
+              :values $v1]
+             (mapcar (lambda (alias)
+                       (vector id alias))
+                     (split-string-and-unquote aliases))))
+          (when refs
+            (setq refs (split-string-and-unquote refs))
+            (let (rows)
+              (dolist (ref refs)
+                (if (string-match org-link-plain-re ref)
+                    (progn
+                      (push (vector id (match-string 2 ref)
+                                    (match-string 1 ref)) rows))
+                  (lwarn '(org-roam) :warning
+                         "%s:%s\tInvalid ref %s, skipping..."
+                         (buffer-file-name) (point) ref)))
+              (when rows
+                (org-roam-db-query
+                 [:insert :into refs
+                  :values $v1]
+                 rows)))))))))
+
+(cl-defun org-roam-db-insert-node-data ()
+  "Insert node data for headline at point into the Org-roam cache."
+  (when-let ((id (org-id-get)))
+    (let* ((file (buffer-file-name (buffer-base-buffer)))
+           (heading-components (org-heading-components))
+           (pos (point))
+           (todo (nth 2 heading-components))
+           (priority (nth 3 heading-components))
+           (level (nth 1 heading-components))
+           (scheduled (org-roam-db-get-scheduled-time))
+           (deadline (org-roam-db-get-deadline-time))
+           (title (or (nth 4 heading-components)
+                      (progn (lwarn 'org-roam :warning "Node in %s:%s:%s has no title, skipping..."
+                                    file
+                                    (line-number-at-pos)
+                                    (1+ (- (point) (line-beginning-position))))
+                             (cl-return-from org-roam-db-insert-node-data))))
+           (properties (org-entry-properties))
+           (olp (org-get-outline-path nil 'use-cache))
+           (title (org-link-display-format title)))
+      (org-roam-db-query!
+       (lambda (err)
+         (lwarn 'org-roam :warning "%s for %s (%s) in %s"
+                (error-message-string err)
+                title id file))
+       [:insert :into nodes
+        :values $v1]
+       (vector id file level pos todo priority
+               scheduled deadline title properties olp)))))
+
+(defun org-roam-db-insert-aliases ()
+  "Insert aliases for node at point into Org-roam cache."
+  (when-let ((node-id (org-id-get))
+             (aliases (org-entry-get (point) "ROAM_ALIASES")))
+    (org-roam-db-query [:insert :into aliases
+                        :values $v1]
+                       (mapcar (lambda (alias)
+                                 (vector node-id alias))
+                               (split-string-and-unquote aliases)))))
+
+(defun org-roam-db-insert-tags ()
+  "Insert tags for node at point into Org-roam cache."
+  (when-let ((node-id (org-id-get))
+             (tags (org-get-tags)))
+    (org-roam-db-query [:insert :into tags
+                        :values $v1]
+                       (mapcar (lambda (tag)
+                                 (vector node-id (substring-no-properties tag))) tags))))
+
+(defun org-roam-db-insert-refs ()
+  "Insert refs for node at point into Org-roam cache."
+  (when-let* ((node-id (org-id-get))
+              (refs (org-entry-get (point) "ROAM_REFS"))
+              (refs (split-string-and-unquote refs)))
+    (let (rows)
+      (dolist (ref refs)
+        (save-match-data
+          (if (string-match org-link-plain-re ref)
+              (progn
+                (push (vector node-id (match-string 2 ref) (match-string 1 ref)) rows))
+            (lwarn '(org-roam) :warning
+                   "%s:%s\tInvalid ref %s, skipping..." (buffer-file-name) (point) ref))))
+      (org-roam-db-query [:insert :into refs
+                          :values $v1]
+                         rows))))
+
+(defun org-roam-db-insert-link (link)
+  "Insert link data for LINK at current point into the Org-roam cache."
+  (save-excursion
+    (goto-char (org-element-property :begin link))
+    (let ((type (org-element-property :type link))
+          (path (org-element-property :path link))
+          (properties (list :outline (ignore-errors
+                                       ;; This can error if link is not under any headline
+                                       (org-get-outline-path 'with-self 'use-cache))))
+          (source (org-roam-id-at-point)))
+      ;; For Org-ref links, we need to split the path into the cite keys
+      (when (and (boundp 'org-ref-cite-types)
+                 (fboundp 'org-ref-split-and-strip-string)
+                 (member type org-ref-cite-types))
+        (setq path (org-ref-split-and-strip-string path)))
+      (unless (listp path)
+        (setq path (list path)))
+      (when (and source path)
+        (org-roam-db-query
+         [:insert :into links
+          :values $v1]
+         (mapcar (lambda (p)
+                   (vector (point) source p type properties))
+                 path))))))
+
+;;;; Fetching
+(defun org-roam-db--get-current-files ()
+  "Return a hash-table of file to the hash of its file contents."
+  (let ((current-files (org-roam-db-query [:select [file hash] :from files]))
+        (ht (make-hash-table :test #'equal)))
+    (dolist (row current-files)
+      (puthash (car row) (cadr row) ht))
+    ht))
+
+(defun org-roam-db--file-hash (&optional file-path)
+  "Compute the hash of FILE-PATH, a file or current buffer."
+  ;; If it is a GPG encrypted file, we always want to compute the hash
+  ;; for the GPG encrypted file (undecrypted)
+  (when (and (not file-path) (equal "gpg" (file-name-extension (buffer-file-name))))
+    (setq file-path (buffer-file-name)))
+  (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)))))
+
+;;;; Synchronization
+(defun org-roam-db-update-file (&optional file-path)
+  "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))))
+  (org-roam-db-clear-file file-path)
+  (when (file-exists-p file-path)
+    (let ((content-hash (org-roam-db--file-hash file-path))
+          (db-hash (caar (org-roam-db-query [:select hash :from files
+                                             :where (= file $s1)] file-path))))
+      (unless (string= content-hash db-hash)
+        (org-roam-with-file file-path nil
+          (save-excursion
+            (org-set-regexps-and-options 'tags-only)
+            (org-roam-db-insert-file)
+            (org-roam-db-insert-file-node)
+            (setq org-outline-path-cache nil)
+            (org-roam-db-map-nodes
+             (list #'org-roam-db-insert-node-data
+                   #'org-roam-db-insert-aliases
+                   #'org-roam-db-insert-tags
+                   #'org-roam-db-insert-refs))
+            (setq org-outline-path-cache nil)
+            (org-roam-db-map-links
+             (list #'org-roam-db-insert-link))))))))
+
+;;;###autoload
+(defun org-roam-db-sync (&optional force)
+  "Synchronize the cache state with the current Org files on-disk.
+If FORCE, force a rebuild of the cache from scratch."
+  (interactive "P")
+  (org-roam-db--close) ;; Force a reconnect
+  (when force (delete-file org-roam-db-location))
+  (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-files))
+         (current-files (org-roam-db--get-current-files))
+         (modified-files nil))
+    (dolist (file org-roam-files)
+      (let ((contents-hash (org-roam-db--file-hash file)))
+        (unless (string= (gethash file current-files)
+                         contents-hash)
+          (push file modified-files)))
+      (remhash file current-files))
+    (emacsql-with-transaction (org-roam-db)
+      (if (fboundp 'dolist-with-progress-reporter)
+          (dolist-with-progress-reporter (file (hash-table-keys current-files))
+              "Clearing removed files..."
+            (org-roam-db-clear-file file))
+        (dolist (file (hash-table-keys current-files))
+          (org-roam-db-clear-file file)))
+      (if (fboundp 'dolist-with-progress-reporter)
+          (dolist-with-progress-reporter (file modified-files)
+              "Processing modified files..."
+            (org-roam-db-update-file file))
+        (dolist (file modified-files)
+          (org-roam-db-update-file file))))))
+
+;;;###autoload
+(defun org-roam-db-autosync-enable ()
+  "Activate `org-roam-db-autosync-mode'."
+  (org-roam-db-autosync-mode +1))
+
+(defun org-roam-db-autosync-disable ()
+  "Deactivate `org-roam-db-autosync-mode'."
+  (org-roam-db-autosync-mode -1))
+
+(defun org-roam-db-autosync-toggle ()
+  "Toggle `org-roam-db-autosync-mode' enabled/disabled."
+  (org-roam-db-autosync-mode 'toggle))
+
+;;;###autoload
+(define-minor-mode org-roam-db-autosync-mode
+  "Global minor mode to keep your Org-roam session automatically synchronized.
+Through the session this will continue to setup your
+buffers (that are Org-roam file visiting), keep track of the
+related changes, maintain cache consistency and incrementally
+update the currently active database.
+
+If you need to manually trigger resync of the currently active
+database, see `org-roam-db-sync' command."
+  :group 'org-roam
+  :global t
+  :init-value nil
+  (let ((enabled org-roam-db-autosync-mode)
+        (update-method org-roam-db-autosync-update-method))
+    (cond
+     (enabled
+      (add-hook 'find-file-hook  #'org-roam-db-autosync--setup-file-h)
+      (org-roam-db-autosync--update-method :enable update-method)
+      (add-hook 'kill-emacs-hook #'org-roam-db--close-all)
+      (org-roam-db-sync))
+     (t
+      (remove-hook 'find-file-hook  #'org-roam-db-autosync--setup-file-h)
+      (org-roam-db-autosync--update-method :disable update-method)
+      (remove-hook 'kill-emacs-hook #'org-roam-db--close-all)
+      (org-roam-db--close-all)
+      ;; Disable local hooks for all org-roam buffers
+      (dolist (buf (org-roam-buffer-list))
+        (with-current-buffer buf
+          (remove-hook 'after-save-hook #'org-roam-db-autosync--try-update-on-save-h t)))))))
+
+(defvar org-roam-db-autosync--filenotify-descriptors (list)
+  "An alist mapping watched Org-roam directories to `filenotify-recursive' uuid.")
+
+(defun org-roam-db-autosync--update-method (state method)
+  "Change the current `org-roam-db-autosync-update-method' to METHOD.
+STATE should be either :enable or :disable, while METHOD should
+be on of the values from `org-roam-db-autosync-update-method'."
+  (unless (memq method '(filenotify on-save nil))
+    (user-error "Unknown `org-roam-db-autosync-update-method': %s" method))
+  (cl-ecase state
+    (:enable
+     (unless (eq method org-roam-db-autosync-update-method)
+       ;; Clean up the old method in case of hot swap.
+       (org-roam-db-autosync--update-method :disable org-roam-db-autosync-update-method))
+     (setq org-roam-db-autosync-update-method method)
+     (pcase method
+       ('filenotify
+        (cl-pushnew
+         (cons org-roam-directory
+               (fnr-add-watch org-roam-directory
+                              '(change)
+                              #'org-roam-db-autosync--filenotify-update
+                              "\\`\\.")) ; Ignore directories that start with "."
+         org-roam-db-autosync--filenotify-descriptors))
+       ('on-save
+        (add-hook 'org-roam-find-file-hook #'org-roam-db-autosync--setup-update-on-save-h)
+        (advice-add #'rename-file :after  #'org-roam-db-autosync--rename-file-a)
+        (advice-add #'delete-file :before #'org-roam-db-autosync--delete-file-a))
+       ((pred nilp)
+        t)))
+    (:disable
+     (pcase org-roam-db-autosync-update-method
+       ('filenotify
+        (cl-loop for entry in org-roam-db-autosync--filenotify-descriptors
+                 for _dir = (car entry)
+                 for uuid = (cdr entry)
+                 do (fnr-rm-watch uuid))
+        (setq org-roam-db-autosync--filenotify-descriptors nil))
+       ('on-save
+        (remove-hook 'org-roam-find-file-hook #'org-roam-db-autosync--setup-update-on-save-h)
+        (advice-remove #'rename-file #'org-roam-db-autosync--rename-file-a)
+        (advice-remove #'delete-file #'org-roam-db-autosync--delete-file-a))
+       ((pred nilp)
+        t)))))
+
+(defun org-roam-db-autosync--filenotify-update (event)
+  "Update Org-roam's database according to EVENT sent by `filenotify'."
+  (cl-destructuring-bind (_descriptor action &rest files) event
+    (cond
+     ((cl-find-if #'org-roam-file-p files)
+      (mapc #'org-roam-db-update-file files))
+     ((memq action '(created deleted renamed))
+      (apply (intern (format "org-roam-db-autosync--update-%s-dir" action)) files)))))
+
+(defun org-roam-db-autosync--update-created-dir (dir)
+  "Add entries from Org-roam files under DIR to the database."
+  (when (file-directory-p dir)
+    (let ((files (let ((org-roam-directory dir))
+                   (org-roam-list-files))))
+      (emacsql-with-transaction (org-roam-db)
+        (mapc #'org-roam-db-update-file files)))))
+
+(defun org-roam-db-autosync--update-deleted-dir (dir)
+  "Invalidate entries related to Org-roam files under DIR from the database."
+  (let ((dir (thread-first dir
+               ;; Ensure that separator is present in the name
+               (directory-file-name)
+               (concat (f-path-separator))
+               ;; Follow the same format as the rest of the files in the database
+               (expand-file-name))))
+    (org-roam-db-query [:delete :from files :where (like file $s1)]
+                       (concat dir "%"))))
+
+(defun org-roam-db-autosync--update-renamed-dir (old-name new-name)
+  "Invalidate and then add files renamed from OLD-NAME directory to NEW-NAME."
+  (org-roam-db-autosync--update-deleted-dir old-name)
+  (org-roam-db-autosync--update-created-dir new-name))
+
+(defun org-roam-db-autosync--delete-file-a (file &optional _trash)
+  "Maintain cache consistency when file deletes.
+FILE is removed from the database."
+  (when (and (not (auto-save-file-name-p file))
+             (not (backup-file-name-p file))
+             (org-roam-file-p file))
+    (org-roam-db-clear-file (expand-file-name file))))
+
+(defun org-roam-db-autosync--rename-file-a (old-file new-file-or-dir &rest _args)
+  "Maintain cache consistency of file rename.
+OLD-FILE is cleared from the database, and NEW-FILE-OR-DIR is added."
+  (let ((new-file (if (directory-name-p new-file-or-dir)
+                      (expand-file-name (file-name-nondirectory old-file) new-file-or-dir)
+                    new-file-or-dir)))
+    (setq new-file (expand-file-name new-file))
+    (setq old-file (expand-file-name old-file))
+    (when (and (not (auto-save-file-name-p old-file))
+               (not (auto-save-file-name-p new-file))
+               (not (backup-file-name-p old-file))
+               (not (backup-file-name-p new-file))
+               (org-roam-file-p old-file))
+      (org-roam-db-clear-file old-file))
+    (when (org-roam-file-p new-file)
+      (org-roam-db-update-file new-file))))
+
+(defun org-roam-db-autosync--setup-file-h ()
+  "Setup the current buffer if it visits an Org-roam file."
+  (when (org-roam-file-p) (run-hooks 'org-roam-find-file-hook)))
+
+(defun org-roam-db-autosync--setup-update-on-save-h ()
+  "Setup the current buffer to update the DB after saving the current file."
+  (add-hook 'after-save-hook #'org-roam-db-update-file nil t))
+
+;;; Diagnostics
+(defun org-roam-db-diagnose-node ()
+  "Print information about node at point."
+  (interactive)
+  (prin1 (org-roam-node-at-point)))
+
+(provide 'org-roam-db)
+
+;;; org-roam-db.el ends here

org-roam-migrate.el

@@ -0,0 +1,210 @@
+;;; org-roam-migrate.el --- Migration utilities from v1 to v2 -*- coding: utf-8; lexical-binding: t; -*-
+
+;; Copyright © 2020-2021 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: 2.0.0
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org "9.4") (emacsql "3.0.0") (emacsql-sqlite "1.0.0") (magit-section "2.90.1") (filenotify-recursive "0.0.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 is a special library provided for the v1 users of this package. It's
+;; purpose is to ease the transition from v1 to v2, by providing migration
+;; utilities to convert from v1 notes to v2 nodes.
+;;
+;;; Code:
+(require 'org-roam)
+
+;;; v1 breaking warning
+(defvar org-roam-v2-ack nil
+  "When set to t, won't display the annoying warning message about the upgrade.
+Need to be set before the package is loaded, otherwise won't take
+any affect.")
+
+(unless org-roam-v2-ack
+  (lwarn 'org-roam :error "
+------------------------------------
+WARNING: You're now on Org-roam v2!
+------------------------------------
+
+You may have arrived here from a package upgrade. Please read the
+wiki entry at
+%s
+for an overview of the major changes.
+
+Notes taken in v1 are incompatible with v2, but you can upgrade
+them to the v2 format via a simple command. To migrate your
+notes, first make sure you're on at least Org 9.4 (check with
+C-h v org-version) and set your org-roam-directory to your notes:
+
+(setq org-roam-directory \"path/to/org/files\")
+
+then, run:
+
+  M-x org-roam-migrate-wizard
+
+If you wish to stay on v1, v1 is unfortunately not distributed on
+MELPA. See org-roam/org-roam-v1 on GitHub on how to install v1.
+
+If you've gone through the migration steps (if necessary), and
+know what you're doing set `org-roam-v2-ack' to `t' to disable
+this warning. You can do so by adding:
+
+(setq org-roam-v2-ack t)
+
+To your init file.
+
+"
+         "https://github.com/org-roam/org-roam/wiki/Hitchhiker's-Rough-Guide-to-Org-roam-V2"))
+
+;;; Migration wizard (v1 -> v2)
+;;;###autoload
+(defun org-roam-migrate-wizard ()
+  "Migrate all notes from to be compatible with Org-roam v2.
+1. Convert all notes from v1 format to v2.
+2. Rebuild the cache.
+3. Replace all file links with ID links."
+  (interactive)
+  (when (yes-or-no-p "Org-roam will now convert all your notes from v1 to v2.
+This will take a while. Are you sure you want to do this?")
+    ;; Back up notes
+    (let ((backup-dir (expand-file-name "org-roam.bak"
+                                        (file-name-directory (directory-file-name org-roam-directory)))))
+      (message "Backing up files to %s" backup-dir)
+      (copy-directory org-roam-directory backup-dir))
+
+    ;; Upgrade database to v2
+    (org-roam-db-sync 'force)
+
+    ;; Convert v1 to v2
+    (dolist (f (org-roam-list-files))
+      (org-roam-with-file f nil
+        (org-roam-migrate-v1-to-v2)))
+
+    ;; Rebuild cache
+    (org-roam-db-sync 'force)
+
+    ;;Replace all file links with ID links
+    (dolist (f (org-roam-list-files))
+      (org-roam-with-file f nil
+        (org-roam-migrate-replace-file-links-with-id)
+        (save-buffer)))))
+
+(defun org-roam-migrate-v1-to-v2 ()
+  "Convert the current buffer to v2 format."
+  ;; Create file level ID
+  (org-with-point-at 1
+    (org-id-get-create))
+  ;; Replace roam_key into properties drawer roam_ref
+  (when-let* ((refs (mapcan #'split-string-and-unquote
+                            (cdar (org-collect-keywords '("roam_key"))))))
+    (let ((case-fold-search t))
+      (org-with-point-at 1
+        (dolist (ref refs)
+          (org-roam-ref-add ref))
+        (while (re-search-forward "^#\\+roam_key:" (point-max) t)
+          (beginning-of-line)
+          (kill-line 1)))))
+
+  ;; Replace roam_alias into properties drawer roam_aliases
+  (when-let* ((aliases (mapcan #'split-string-and-unquote
+                               (cdar (org-collect-keywords '("roam_alias"))))))
+    (dolist (alias aliases)
+      (org-roam-alias-add alias)))
+  (let ((case-fold-search t))
+    (org-with-point-at 1
+      (while (re-search-forward "^#\\+roam_alias:" (point-max) t)
+        (beginning-of-line)
+        (kill-line 1))))
+
+  ;; Replace #+roam_tags into #+filetags
+  (org-with-point-at 1
+    (let* ((roam-tags (org-roam-migrate-get-prop-list "ROAM_TAGS"))
+           (file-tags (cl-mapcan (lambda (value)
+                                   (cl-mapcan
+                                    (lambda (k) (org-split-string k ":"))
+                                    (split-string value)))
+                                 (org-roam-migrate-get-prop-list "FILETAGS")))
+           (tags (append roam-tags file-tags))
+           (tags (seq-map (lambda (tag)
+                            (replace-regexp-in-string
+                             "[^[:alnum:]_@#%]"
+                             "_"
+                             tag)) tags))
+           (tags (seq-uniq tags)))
+      (when tags
+        (org-roam-migrate-prop-set "filetags" (org-make-tag-string tags))))
+    (let ((case-fold-search t))
+      (org-with-point-at 1
+        (while (re-search-forward "^#\\+roam_tags:" (point-max) t)
+          (beginning-of-line)
+          (kill-line 1)))))
+  (save-buffer))
+
+(defun org-roam-migrate-get-prop-list (keyword)
+  "Return prop list for KEYWORD."
+  (let ((re (format "^#\\+%s:[ \t]*\\([^\n]+\\)" (upcase keyword)))
+        lst)
+    (goto-char (point-min))
+    (while (re-search-forward re 2048 t)
+      (setq lst (append lst (split-string-and-unquote
+                             (buffer-substring-no-properties
+                              (match-beginning 1) (match-end 1))))))
+    lst))
+
+(defun org-roam-migrate-prop-set (name value)
+  "Set a file property called NAME to VALUE in buffer file.
+If the property is already set, replace its value."
+  (setq name (downcase name))
+  (org-with-point-at 1
+    (let ((case-fold-search t))
+      (if (re-search-forward (concat "^#\\+" name ":\\(.*\\)")
+                             (point-max) t)
+          (replace-match (concat "#+" name ": " value) 'fixedcase)
+        (while (and (not (eobp))
+                    (looking-at "^[#:]"))
+          (if (save-excursion (end-of-line) (eobp))
+              (progn
+                (end-of-line)
+                (insert "\n"))
+            (forward-line)
+            (beginning-of-line)))
+        (insert "#+" name ": " value "\n")))))
+
+(defun org-roam-migrate-replace-file-links-with-id ()
+  "Replace all file: links with ID links in current buffer."
+  (org-with-point-at 1
+    (while (re-search-forward org-link-bracket-re nil t)
+      (let* ((mdata (match-data))
+             (path (match-string 1))
+             (desc (match-string 2)))
+        (when (string-prefix-p "file:" path)
+          (setq path (expand-file-name (substring path 5)))
+          (when-let ((node-id (caar (org-roam-db-query [:select [id] :from nodes
+                                                        :where (= file $s1)
+                                                        :and (= level 0)] path))))
+            (set-match-data mdata)
+            (replace-match (org-link-make-string (concat "id:" node-id)
+                                                 desc) nil t)))))))
+
+(provide 'org-roam-migrate)
+;;; org-roam-migrate.el ends here

org-roam-mode.el

@@ -0,0 +1,688 @@
+;;; org-roam-mode.el --- Major mode for special Org-roam buffers -*- lexical-binding: t -*-
+
+;; Copyright © 2020-2021 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: 2.0.0
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org "9.4") (emacsql "3.0.0") (emacsql-sqlite "1.0.0") (magit-section "2.90.1") (filenotify-recursive "0.0.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 module implements `org-roam-mode', which is a major mode that used by
+;; special Org-roam buffers to display various content in a section-like manner
+;; about the nodes and relevant to them information (e.g. backlinks) with which
+;; the user can interact with.
+;;
+;;; Code:
+(require 'org-roam)
+
+;;;; Declarations
+(defvar org-ref-buffer-hacked)
+
+;;; Options
+(defcustom org-roam-mode-section-functions (list #'org-roam-backlinks-section
+                                                 #'org-roam-reflinks-section)
+  "Functions that insert sections in the `org-roam-mode' based buffers.
+Each function is called with one argument, which is an
+`org-roam-node' for which the buffer will be constructed for.
+Normally this node is `org-roam-buffer-current-node'."
+  :group 'org-roam
+  :type 'hook)
+
+;;; Faces
+(defface org-roam-header-line
+  `((((class color) (background light))
+     ,@(and (>= emacs-major-version 27) '(:extend t))
+     :foreground "DarkGoldenrod4"
+     :weight bold)
+    (((class color) (background  dark))
+     ,@(and (>= emacs-major-version 27) '(:extend t))
+     :foreground "LightGoldenrod2"
+     :weight bold))
+  "Face for the `header-line' in some Org-roam modes."
+  :group 'org-roam-faces)
+
+(defface org-roam-title
+  '((t :weight bold))
+  "Face for Org-roam titles."
+  :group 'org-roam-faces)
+
+(defface org-roam-olp
+  '((((class color) (background light)) :foreground "grey60")
+    (((class color) (background  dark)) :foreground "grey40"))
+  "Face for the OLP of the node."
+  :group 'org-roam-faces)
+
+(defface org-roam-preview-heading
+  `((((class color) (background light))
+     ,@(and (>= emacs-major-version 27) '(:extend t))
+     :background "grey80"
+     :foreground "grey30")
+    (((class color) (background dark))
+     ,@(and (>= emacs-major-version 27) '(:extend t))
+     :background "grey25"
+     :foreground "grey70"))
+  "Face for preview headings."
+  :group 'org-roam-faces)
+
+(defface org-roam-preview-heading-highlight
+  `((((class color) (background light))
+     ,@(and (>= emacs-major-version 27) '(:extend t))
+     :background "grey75"
+     :foreground "grey30")
+    (((class color) (background dark))
+     ,@(and (>= emacs-major-version 27) '(:extend t))
+     :background "grey35"
+     :foreground "grey70"))
+  "Face for current preview headings."
+  :group 'org-roam-faces)
+
+(defface org-roam-preview-heading-selection
+  `((((class color) (background light))
+     ,@(and (>= emacs-major-version 27) '(:extend t))
+     :inherit org-roam-preview-heading-highlight
+     :foreground "salmon4")
+    (((class color) (background dark))
+     ,@(and (>= emacs-major-version 27) '(:extend t))
+     :inherit org-roam-preview-heading-highlight
+     :foreground "LightSalmon3"))
+  "Face for selected preview headings."
+  :group 'org-roam-faces)
+
+(defface org-roam-preview-region
+  `((t :inherit bold
+       ,@(and (>= emacs-major-version 27)
+              (list :extend (ignore-errors (face-attribute 'region :extend))))))
+  "Face used by `org-roam-highlight-preview-region-using-face'.
+
+This face is overlaid over text that uses other hunk faces,
+and those normally set the foreground and background colors.
+The `:foreground' and especially the `:background' properties
+should be avoided here.  Setting the latter would cause the
+loss of information.  Good properties to set here are `:weight'
+and `:slant'."
+  :group 'org-roam-faces)
+
+(defface org-roam-dim
+  '((((class color) (background light)) :foreground "grey60")
+    (((class color) (background  dark)) :foreground "grey40"))
+  "Face for the dimmer part of the widgets."
+  :group 'org-roam-faces)
+
+;;; Major mode
+(defvar org-roam-mode-map
+  (let ((map (make-sparse-keymap)))
+    (set-keymap-parent map magit-section-mode-map)
+    (define-key map [C-return]  'org-roam-buffer-visit-thing)
+    (define-key map (kbd "C-m") 'org-roam-buffer-visit-thing)
+    (define-key map [remap revert-buffer] 'org-roam-buffer-refresh)
+    map)
+  "Parent keymap for all keymaps of modes derived from `org-roam-mode'.")
+
+(define-derived-mode org-roam-mode magit-section-mode "Org-roam"
+  "Major mode for displaying relevant information about Org-roam nodes.
+This mode is used by special Org-roam buffers, such as persistent
+`org-roam-buffer' and dedicated Org-roam buffers
+\(`org-roam-buffer-display-dedicated'), which render the
+information in a section-like manner (see
+`org-roam-mode-section-functions'), with which the user can
+interact with."
+  :group 'org-roam
+  (face-remap-add-relative 'header-line 'org-roam-header-line))
+
+;;; Buffers
+(defvar org-roam-buffer-current-node nil
+  "The node for which an `org-roam-mode' based buffer displays its contents.
+This set both, locally and globally. Normally the local value is
+only set in the `org-roam-mode' based buffers, while the global
+value shows the current node in the persistent `org-roam-buffer'.")
+
+(put 'org-roam-buffer-current-node 'permanent-local t)
+
+(defvar org-roam-buffer-current-directory nil
+  "The `org-roam-directory' value of `org-roam-buffer-current-node'.
+Set both, locally and globally in the same way as `org-roam-buffer-current-node'.")
+
+(put 'org-roam-buffer-current-directory 'permanent-local t)
+
+;;;; Library
+(defun org-roam-buffer-visit-thing ()
+  "This is a placeholder command.
+Where applicable, section-specific keymaps bind another command
+which visits the thing at point."
+  (interactive)
+  (user-error "There is no thing at point that could be visited"))
+
+(defun org-roam-buffer-file-at-point (&optional assert)
+  "Return the file at point in the current `org-roam-mode' based buffer.
+If ASSERT, throw an error."
+  (if-let ((file (magit-section-case
+                   (org-roam-node-section (org-roam-node-file (oref it node)))
+                   (org-roam-grep-section (oref it file))
+                   (org-roam-preview-section (oref it file))
+                   (t (cl-assert (derived-mode-p 'org-roam-mode))))))
+      file
+    (when assert
+      (user-error "No file at point"))))
+
+(defun org-roam-buffer-refresh ()
+  "Refresh the contents of the currently selected Org-roam buffer."
+  (interactive)
+  (cl-assert (derived-mode-p 'org-roam-mode))
+  (save-excursion (org-roam-buffer-render-contents)))
+
+(defun org-roam-buffer-render-contents ()
+  "Recompute and render the contents of an Org-roam buffer.
+Assumes that the current buffer is an `org-roam-mode' based
+buffer."
+  (let ((inhibit-read-only t))
+    (erase-buffer)
+    (org-roam-mode)
+    (setq-local default-directory org-roam-buffer-current-directory)
+    (setq-local org-roam-directory org-roam-buffer-current-directory)
+    (org-roam-buffer-set-header-line-format
+     (org-roam-node-title org-roam-buffer-current-node))
+    (magit-insert-section (org-roam)
+      (magit-insert-heading)
+      (run-hook-with-args 'org-roam-mode-section-functions org-roam-buffer-current-node))
+    (goto-char 0)))
+
+(defun org-roam-buffer-set-header-line-format (string)
+  "Set the header-line using STRING.
+If the `face' property of any part of STRING is already set, then
+that takes precedence. Also pad the left side of STRING so that
+it aligns with the text area."
+  (setq-local header-line-format
+              (concat (propertize " " 'display '(space :align-to 0))
+                      string)))
+
+;;;; Dedicated buffer
+;;;###autoload
+(defun org-roam-buffer-display-dedicated (node)
+  "Launch NODE dedicated Org-roam buffer.
+Unlike the persistent `org-roam-buffer', the contents of this
+buffer won't be automatically changed and will be held in place.
+
+In interactive calls prompt to select NODE, unless called with
+`universal-argument', in which case NODE will be set to
+`org-roam-node-at-point'."
+  (interactive
+   (list (if current-prefix-arg
+             (org-roam-node-at-point 'assert)
+           (org-roam-node-read nil nil nil 'require-match))))
+  (let ((buffer (get-buffer-create (org-roam-buffer--dedicated-name node))))
+    (with-current-buffer buffer
+      (setq-local org-roam-buffer-current-node node)
+      (setq-local org-roam-buffer-current-directory org-roam-directory)
+      (org-roam-buffer-render-contents))
+    (display-buffer buffer)))
+
+(defun org-roam-buffer--dedicated-name (node)
+  "Construct buffer name for NODE dedicated Org-roam buffer."
+  (let ((title (org-roam-node-title node))
+        (filename (file-relative-name (org-roam-node-file node) org-roam-directory)))
+    (format "*org-roam: %s<%s>*" title filename)))
+
+(defun org-roam-buffer-dedicated-p (&optional buffer)
+  "Return t if an Org-roam BUFFER is a node dedicated one.
+See `org-roam-buffer-display-dedicated' for more details.
+If BUFFER is nil, default it to `current-buffer'."
+  (or buffer (setq buffer (current-buffer)))
+  (string-match-p (concat "^" (regexp-quote "*org-roam: "))
+                  (buffer-name buffer)))
+
+;;;; Persistent buffer
+(defvar org-roam-buffer "*org-roam*"
+  "The persistent Org-roam buffer name. Must be surround with \"*\".
+The content inside of this buffer will be automatically updated
+to the nearest node at point that comes from the current buffer.
+To toggle its display use `org-roam-buffer-toggle' command.")
+
+(defun org-roam-buffer-toggle ()
+  "Toggle display of the persistent `org-roam-buffer'."
+  (interactive)
+  (pcase (org-roam-buffer--visibility)
+    ('visible
+     (progn
+       (delete-window (get-buffer-window org-roam-buffer))
+       (remove-hook 'post-command-hook #'org-roam-buffer--redisplay-h)))
+    ((or 'exists 'none)
+     (progn
+       (display-buffer (get-buffer-create org-roam-buffer))
+       (org-roam-buffer-persistent-redisplay)))))
+
+(define-inline org-roam-buffer--visibility ()
+  "Return the current visibility state of the persistent `org-roam-buffer'.
+Valid states are 'visible, 'exists and 'none."
+  (declare (side-effect-free t))
+  (inline-quote
+   (cond
+    ((get-buffer-window org-roam-buffer) 'visible)
+    ((get-buffer org-roam-buffer) 'exists)
+    (t 'none))))
+
+(defun org-roam-buffer-persistent-redisplay ()
+  "Recompute contents of the persistent `org-roam-buffer'.
+Has no effect when there's no `org-roam-node-at-point'."
+  (when-let ((node (org-roam-node-at-point)))
+    (unless (equal node org-roam-buffer-current-node)
+      (setq org-roam-buffer-current-node node
+            org-roam-buffer-current-directory org-roam-directory)
+      (with-current-buffer (get-buffer-create org-roam-buffer)
+        (org-roam-buffer-render-contents)
+        (add-hook 'kill-buffer-hook #'org-roam-buffer--persistent-cleanup-h nil t)))))
+
+(defun org-roam-buffer--persistent-cleanup-h ()
+  "Clean-up global state thats dedicated for the persistent `org-roam-buffer'."
+  (setq-default org-roam-buffer-current-node nil
+                org-roam-buffer-current-directory nil))
+
+(add-hook 'org-roam-find-file-hook #'org-roam-buffer--setup-redisplay-h)
+(defun org-roam-buffer--setup-redisplay-h ()
+  "Setup automatic redisplay of the persistent `org-roam-buffer'."
+  (add-hook 'post-command-hook #'org-roam-buffer--redisplay-h nil t))
+
+(defun org-roam-buffer--redisplay-h ()
+  "Reconstruct the persistent `org-roam-buffer'.
+This needs to be quick or infrequent, because this designed to
+run at `post-command-hook'."
+  (and (get-buffer-window org-roam-buffer)
+       (org-roam-buffer-persistent-redisplay)))
+
+;;; Sections
+;;;; Node
+(defvar org-roam-node-map
+  (let ((map (make-sparse-keymap)))
+    (set-keymap-parent map org-roam-mode-map)
+    (define-key map [remap org-roam-buffer-visit-thing] 'org-roam-node-visit)
+    map)
+  "Keymap for `org-roam-node-section's.")
+
+(defclass org-roam-node-section (magit-section)
+  ((keymap :initform 'org-roam-node-map)
+   (node :initform nil))
+  "A `magit-section' used by `org-roam-mode' to outline NODE in its own heading.")
+
+(cl-defun org-roam-node-insert-section (&key source-node point properties)
+  "Insert section for a link from SOURCE-NODE to some other node.
+The other node is normally `org-roam-buffer-current-node'.
+
+SOURCE-NODE is an `org-roam-node' that links or references with
+the other node.
+
+POINT is a character position where the link is located in
+SOURCE-NODE's file.
+
+PROPERTIES (a plist) contains additional information about the
+link.
+
+Despite the name, this function actually inserts 2 sections at
+the same time:
+
+1. `org-roam-node-section' for a heading that describes
+   SOURCE-NODE. Acts as a parent section of the following one.
+
+2. `org-roam-preview-section' for a preview content that comes
+   from SOURCE-NODE's file for the link (that references the
+   other node) at POINT. Acts a child section of the previous
+   one."
+  (magit-insert-section section (org-roam-node-section)
+    (let ((outline (if-let ((outline (plist-get properties :outline)))
+                       (mapconcat #'org-link-display-format outline " > ")
+                     "Top")))
+      (insert (concat (propertize (org-roam-node-title source-node)
+                                  'font-lock-face 'org-roam-title)
+                      (format " (%s)"
+                              (propertize outline 'font-lock-face 'org-roam-olp)))))
+    (magit-insert-heading)
+    (oset section node source-node)
+    (magit-insert-section section (org-roam-preview-section)
+      (insert (org-roam-fontify-like-in-org-mode
+               (org-roam-preview-get-contents (org-roam-node-file source-node) point))
+              "\n")
+      (oset section file (org-roam-node-file source-node))
+      (oset section point point)
+      (insert ?\n))))
+
+;;;; Preview
+(defvar org-roam-preview-map
+  (let ((map (make-sparse-keymap)))
+    (set-keymap-parent map org-roam-mode-map)
+    (define-key map [remap org-roam-buffer-visit-thing] 'org-roam-preview-visit)
+    map)
+  "Keymap for `org-roam-preview-section's.")
+
+(defclass org-roam-preview-section (magit-section)
+  ((keymap :initform 'org-roam-preview-map)
+   (file :initform nil)
+   (point :initform nil))
+  "A `magit-section' used by `org-roam-mode' to contain preview content.
+The preview content comes from FILE, and the link as at POINT.")
+
+(defun org-roam-preview-visit (file point &optional other-window)
+  "Visit FILE at POINT. With OTHER-WINDOW non-nil do so in another window.
+In interactive calls OTHER-WINDOW is set with
+`universal-argument'."
+  (interactive (list (org-roam-buffer-file-at-point 'assert)
+                     (oref (magit-current-section) point)
+                     current-prefix-arg))
+  (let ((buf (find-file-noselect file))
+        (display-buffer-fn (if other-window
+                               #'switch-to-buffer-other-window
+                             #'pop-to-buffer-same-window)))
+    (with-current-buffer buf
+      (widen)
+      (goto-char point))
+    (funcall display-buffer-fn buf)
+    (when (org-invisible-p) (org-show-context))))
+
+(defun org-roam-preview-get-contents (file point)
+  "Get preview content for FILE at POINT."
+  (save-excursion
+    (org-roam-with-temp-buffer file
+      (goto-char point)
+      (let ((elem (org-element-at-point)))
+        ;; We want the parent element always
+        (while (org-element-property :parent elem)
+          (setq elem (org-element-property :parent elem)))
+        (pcase (car elem)
+          ('headline                    ; show subtree
+           (org-roam-preview-get-entry-text (point-marker) most-positive-fixnum))
+          (_
+           (let ((begin (org-element-property :begin elem))
+                 (end (org-element-property :end elem)))
+             (or (string-trim (buffer-substring-no-properties begin end))
+                 (org-element-property :raw-value elem)))))))))
+
+(defun org-roam-preview-get-entry-text (marker n-lines &optional indent)
+  "Extract entry text from MARKER, at most N-LINES lines.
+This will ignore drawers etc, just get the text.
+If INDENT is given, prefix every line with this string."
+  (let (txt ind)
+    (save-excursion
+      (with-current-buffer (marker-buffer marker)
+        (if (not (derived-mode-p 'org-mode))
+            (setq txt "")
+          (org-with-wide-buffer
+           (goto-char marker)
+           (end-of-line 1)
+           (setq txt (buffer-substring
+                      (min (1+ (point)) (point-max))
+                      (progn (outline-next-heading) (point))))
+           (with-temp-buffer
+             (insert txt)
+             (goto-char (point-min))
+             (while (org-activate-links (point-max))
+               (goto-char (match-end 0)))
+             (goto-char (point-min))
+             (while (re-search-forward org-link-bracket-re (point-max) t)
+               (set-text-properties (match-beginning 0) (match-end 0)
+                                    nil))
+             (goto-char (point-min))
+             (while (re-search-forward org-drawer-regexp nil t)
+               (delete-region
+                (match-beginning 0)
+                (progn (re-search-forward
+                        "^[ \t]*:END:.*\n?" nil 'move)
+                       (point))))
+             (goto-char (point-min))
+             (goto-char (point-max))
+             (skip-chars-backward " \t\n")
+             (when (looking-at "[ \t\n]+\\'") (replace-match ""))
+
+             ;; find and remove min common indentation
+             (goto-char (point-min))
+             (untabify (point-min) (point-max))
+             (setq ind (current-indentation))
+             (while (not (eobp))
+               (unless (looking-at "[ \t]*$")
+                 (setq ind (min ind (current-indentation))))
+               (beginning-of-line 2))
+             (goto-char (point-min))
+             (while (not (eobp))
+               (unless (looking-at "[ \t]*$")
+                 (move-to-column ind)
+                 (delete-region (point-at-bol) (point)))
+               (beginning-of-line 2))
+             (goto-char (point-min))
+             (when indent
+               (while (and (not (eobp)) (re-search-forward "^" nil t))
+                 (replace-match indent t t)))
+             (goto-char (point-min))
+             (while (looking-at "[ \t]*\n") (replace-match ""))
+             (goto-char (point-max))
+             (when (> (org-current-line)
+                      n-lines)
+               (org-goto-line (1+ n-lines))
+               (backward-char 1))
+             (setq txt (buffer-substring (point-min) (point))))))))
+    txt))
+
+;;;; Backlinks
+(cl-defstruct (org-roam-backlink (:constructor org-roam-backlink-create)
+                                 (:copier nil))
+  source-node target-node
+  point properties)
+
+(cl-defmethod org-roam-populate ((backlink org-roam-backlink))
+  "Populate BACKLINK from database."
+  (setf (org-roam-backlink-source-node backlink)
+        (org-roam-populate (org-roam-backlink-source-node backlink))
+        (org-roam-backlink-target-node backlink)
+        (org-roam-populate (org-roam-backlink-target-node backlink)))
+  backlink)
+
+(defun org-roam-backlinks-get (node)
+  "Return the backlinks for NODE."
+  (let ((backlinks (org-roam-db-query
+                    [:select [source dest pos properties]
+                     :from links
+                     :where (= dest $s1)
+                     :and (= type "id")]
+                    (org-roam-node-id node))))
+    (cl-loop for backlink in backlinks
+             collect (pcase-let ((`(,source-id ,dest-id ,pos ,properties) backlink))
+                       (org-roam-populate
+                        (org-roam-backlink-create
+                         :source-node (org-roam-node-create :id source-id)
+                         :target-node (org-roam-node-create :id dest-id)
+                         :point pos
+                         :properties properties))))))
+
+(defun org-roam-backlinks-sort (a b)
+  "Default sorting function for backlinks A and B.
+Sorts by title."
+  (string< (org-roam-node-title (org-roam-backlink-source-node a))
+           (org-roam-node-title (org-roam-backlink-source-node b))))
+
+(defun org-roam-backlinks-section (node)
+  "The backlinks section for NODE."
+  (when-let ((backlinks (seq-sort #'org-roam-backlinks-sort (org-roam-backlinks-get node))))
+    (magit-insert-section (org-roam-backlinks)
+      (magit-insert-heading "Backlinks:")
+      (dolist (backlink backlinks)
+        (org-roam-node-insert-section
+         :source-node (org-roam-backlink-source-node backlink)
+         :point (org-roam-backlink-point backlink)
+         :properties (org-roam-backlink-properties backlink)))
+      (insert ?\n))))
+
+;;;; Reflinks
+(cl-defstruct (org-roam-reflink (:constructor org-roam-reflink-create)
+                                (:copier nil))
+  source-node ref
+  point properties)
+
+(cl-defmethod org-roam-populate ((reflink org-roam-reflink))
+  "Populate REFLINK from database."
+  (setf (org-roam-reflink-source-node reflink)
+        (org-roam-populate (org-roam-reflink-source-node reflink)))
+  reflink)
+
+(defun org-roam-reflinks-get (node)
+  "Return the reflinks for NODE."
+  (let ((refs (org-roam-db-query [:select [ref] :from refs
+                                  :where (= node-id $s1)]
+                                 (org-roam-node-id node)))
+        links)
+    (pcase-dolist (`(,ref) refs)
+      (pcase-dolist (`(,source-id ,pos ,properties) (org-roam-db-query
+                                                     [:select [source pos properties]
+                                                      :from links
+                                                      :where (= dest $s1)]
+                                                     ref))
+        (push (org-roam-populate
+               (org-roam-reflink-create
+                :source-node (org-roam-node-create :id source-id)
+                :ref ref
+                :point pos
+                :properties properties)) links)))
+    links))
+
+(defun org-roam-reflinks-sort (a b)
+  "Default sorting function for reflinks A and B.
+Sorts by title."
+  (string< (org-roam-node-title (org-roam-reflink-source-node a))
+           (org-roam-node-title (org-roam-reflink-source-node b))))
+
+(defun org-roam-reflinks-section (node)
+  "The reflinks section for NODE."
+  (when (org-roam-node-refs node)
+    (let* ((reflinks (seq-sort #'org-roam-reflinks-sort (org-roam-reflinks-get node))))
+      (magit-insert-section (org-roam-reflinks)
+        (magit-insert-heading "Reflinks:")
+        (dolist (reflink reflinks)
+          (org-roam-node-insert-section
+           :source-node (org-roam-reflink-source-node reflink)
+           :point (org-roam-reflink-point reflink)
+           :properties (org-roam-reflink-properties reflink)))
+        (insert ?\n)))))
+
+;;;; Grep
+(defvar org-roam-grep-map
+  (let ((map (make-sparse-keymap)))
+    (set-keymap-parent map org-roam-mode-map)
+    (define-key map [remap org-roam-buffer-visit-thing] 'org-roam-grep-visit)
+    map)
+  "Keymap for Org-roam grep result sections.")
+
+(defclass org-roam-grep-section (magit-section)
+  ((keymap :initform 'org-roam-grep-map)
+   (file :initform nil)
+   (row :initform nil)
+   (col :initform nil))
+  "A `magit-section' used by `org-roam-mode' to contain grep output.")
+
+(defun org-roam-grep-visit (file &optional other-window row col)
+  "Visits FILE. If ROW, move to the row, and if COL move to the COL.
+With OTHER-WINDOW non-nil (in interactive calls set with
+`universal-argument') display the buffer in another window
+instead."
+  (interactive (list (org-roam-buffer-file-at-point t)
+                     current-prefix-arg
+                     (oref (magit-current-section) row)
+                     (oref (magit-current-section) col)))
+  (let ((buf (find-file-noselect file))
+        (display-buffer-fn (if other-window
+                               #'switch-to-buffer-other-window
+                             #'pop-to-buffer-same-window)))
+    (with-current-buffer buf
+      (widen)
+      (goto-char (point-min))
+      (when row
+        (forward-line (1- row)))
+      (when col
+        (forward-char (1- col))))
+    (funcall display-buffer-fn buf)
+    (when (org-invisible-p) (org-show-context))))
+
+;;;; Unlinked references
+(defvar org-roam-unlinked-references-result-re
+  (rx (group (one-or-more anything))
+      ":"
+      (group (one-or-more digit))
+      ":"
+      (group (one-or-more digit))
+      ":"
+      (group (zero-or-more anything)))
+  "Regex for the return result of a ripgrep query.")
+
+(defun org-roam-unlinked-references-preview-line (file row)
+  "Return the preview line from FILE.
+This is the ROW within FILE."
+  (with-temp-buffer
+    (insert-file-contents file)
+    (forward-line (1- row))
+    (buffer-substring-no-properties
+     (save-excursion
+       (beginning-of-line)
+       (point))
+     (save-excursion
+       (end-of-line)
+       (point)))))
+
+(defun org-roam-unlinked-references-section (node)
+  "The unlinked references section for NODE.
+References from FILE are excluded."
+  (when (and (executable-find "rg")
+             (not (string-match "PCRE2 is not available"
+                                (shell-command-to-string "rg --pcre2-version"))))
+    (let* ((titles (cons (org-roam-node-title node)
+                         (org-roam-node-aliases node)))
+           (rg-command (concat "rg -o --vimgrep -P -i "
+                               (mapconcat (lambda (glob) (concat "-g " glob))
+                                          (org-roam--list-files-search-globs org-roam-file-extensions)
+                                          " ")
+                               (format " '\\[([^[]]++|(?R))*\\]%s' "
+                                       (mapconcat (lambda (title)
+                                                    (format "|(\\b%s\\b)" (shell-quote-argument title)))
+                                                  titles ""))
+                               org-roam-directory))
+           (results (split-string (shell-command-to-string rg-command) "\n"))
+           f row col match)
+      (magit-insert-section (unlinked-references)
+        (magit-insert-heading "Unlinked References:")
+        (dolist (line results)
+          (save-match-data
+            (when (string-match org-roam-unlinked-references-result-re line)
+              (setq f (match-string 1 line)
+                    row (string-to-number (match-string 2 line))
+                    col (string-to-number (match-string 3 line))
+                    match (match-string 4 line))
+              (when (and match
+                         (not (f-equal-p (org-roam-node-file node) f))
+                         (member (downcase match) (mapcar #'downcase titles)))
+                (magit-insert-section section (org-roam-grep-section)
+                  (oset section file f)
+                  (oset section row row)
+                  (oset section col col)
+                  (insert (propertize (format "%s:%s:%s"
+                                              (truncate-string-to-width (file-name-base f) 15 nil nil "...")
+                                              row col) 'font-lock-face 'org-roam-dim)
+                          " "
+                          (org-roam-fontify-like-in-org-mode
+                           (org-roam-unlinked-references-preview-line f row))
+                          "\n"))))))
+        (insert ?\n)))))
+
+(provide 'org-roam-mode)
+;;; org-roam-mode.el ends here

org-roam-utils.el

@@ -0,0 +1,321 @@
+;;; org-roam-utils.el --- Utilities for Org-roam -*- lexical-binding: t; -*-
+
+;; Copyright © 2020-2021 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: 2.0.0
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (org "9.4"))
+
+;; 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 library provides definitions for utilities that used throughout the
+;; whole package.
+;;
+;;; Code:
+
+;;; String utilities
+;; TODO Refactor this.
+(defun org-roam-replace-string (old new s)
+  "Replace OLD with NEW in S."
+  (declare (pure t) (side-effect-free t))
+  (replace-regexp-in-string (regexp-quote old) new s t t))
+
+(defun org-roam-quote-string (s)
+  "Quotes string S."
+  (->> s
+    (org-roam-replace-string "\\" "\\\\")
+    (org-roam-replace-string "\"" "\\\"")))
+
+;;; List utilities
+(defmacro org-roam-plist-map! (fn plist)
+  "Map FN over PLIST, modifying it in-place."
+  (declare (indent 1))
+  (let ((plist-var (make-symbol "plist"))
+        (k (make-symbol "k"))
+        (v (make-symbol "v")))
+    `(let ((,plist-var (copy-sequence ,plist)))
+       (while ,plist-var
+         (setq ,k (pop ,plist-var))
+         (setq ,v (pop ,plist-var))
+         (setq ,plist (plist-put ,plist ,k (funcall ,fn ,k ,v)))))))
+
+;;; File utilities
+(defmacro org-roam-with-file (file keep-buf-p &rest body)
+  "Execute BODY within FILE.
+If FILE is nil, execute BODY in the current buffer.
+Kills the buffer if KEEP-BUF-P is nil, and FILE is not yet visited."
+  (declare (indent 2) (debug t))
+  `(let* (new-buf
+          (auto-mode-alist nil)
+          (buf (or (and (not ,file)
+                        (current-buffer)) ;If FILE is nil, use current buffer
+                   (find-buffer-visiting ,file) ; If FILE is already visited, find buffer
+                   (progn
+                     (setq new-buf t)
+                     (find-file-noselect ,file)))) ; Else, visit FILE and return buffer
+          res)
+     (with-current-buffer buf
+       (unless (equal major-mode 'org-mode)
+         (delay-mode-hooks
+           (let ((org-inhibit-startup t)
+                 (org-agenda-files nil))
+             (org-mode))))
+       (setq res (progn ,@body))
+       (unless (and new-buf (not ,keep-buf-p))
+         (save-buffer)))
+     (if (and new-buf (not ,keep-buf-p))
+         (when (find-buffer-visiting ,file)
+           (kill-buffer (find-buffer-visiting ,file))))
+     res))
+
+;;; Buffer utilities
+(defmacro org-roam-with-temp-buffer (file &rest body)
+  "Execute BODY within a temp buffer.
+Like `with-temp-buffer', but propagates `org-roam-directory'.
+If FILE, set `default-directory' to FILE's directory and insert its contents."
+  (declare (indent 1) (debug t))
+  (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))
+           (delay-mode-hooks (org-mode))
+           (when ,file
+             (insert-file-contents ,file)
+             (setq-local default-directory (file-name-directory ,file)))
+           ,@body)))))
+
+;;; Formatting
+(defun org-roam-format-template (template replacer)
+  "Format TEMPLATE with the function REPLACER.
+The templates are of form ${foo} for variable foo, and
+${foo=default} for variable foo with default value \"default\".
+REPLACER takes an argument of the format variable and the default
+value (possibly nil). Adapted from `s-format'."
+  (let ((saved-match-data (match-data)))
+    (unwind-protect
+        (replace-regexp-in-string
+         "\\${\\([^}]+\\)}"
+         (lambda (md)
+           (let ((var (match-string 1 md))
+                 (replacer-match-data (match-data))
+                 default-val)
+             (when (string-match "\\(.+\\)=\\(.+\\)" var)
+               (setq default-val (match-string 2 var)
+                     var (match-string 1 var)))
+             (unwind-protect
+                 (let ((v (progn
+                            (set-match-data saved-match-data)
+                            (funcall replacer var default-val))))
+                   (if v (format "%s" v) (signal 'org-roam-format-resolve md)))
+               (set-match-data replacer-match-data))))
+         template
+         ;; Need literal to make sure it works
+         t t)
+      (set-match-data saved-match-data))))
+
+;;; Fontification
+(defun org-roam-fontify-like-in-org-mode (s)
+  "Fontify string S like in Org mode.
+Like `org-fontify-like-in-org-mode', but supports `org-ref'."
+  ;; NOTE: pretend that the temporary buffer created by `org-fontify-like-in-org-mode' to
+  ;; fontify a `cite:' reference has been hacked by org-ref, whatever that means;
+  ;;
+  ;; `org-ref-cite-link-face-fn', which is used to supply a face for `cite:' links, calls
+  ;; `hack-dir-local-variables' rationalizing that `bibtex-completion' would throw some warnings
+  ;; otherwise.  This doesn't seem to be the case and calling this function just before
+  ;; `org-font-lock-ensure' (alias of `font-lock-ensure') actually instead of fixing the alleged
+  ;; warnings messes the things so badly that `font-lock-ensure' crashes with error and doesn't let
+  ;; org-roam to proceed further. I don't know what's happening there exactly but disabling this hackery
+  ;; fixes the crashing.  Fortunately, org-ref provides the `org-ref-buffer-hacked' switch, which we use
+  ;; here to make it believe that the buffer was hacked.
+  ;;
+  ;; This is a workaround for `cite:' links and does not have any effect on other ref types.
+  ;;
+  ;; `org-ref-buffer-hacked' is a buffer-local variable, therefore we inline
+  ;; `org-fontify-like-in-org-mode' here
+  (with-temp-buffer
+    (insert s)
+    (let ((org-ref-buffer-hacked t))
+      (org-mode)
+      (org-font-lock-ensure)
+      (buffer-string))))
+
+;;;; Shielding regions
+(defface org-roam-shielded
+  '((t :inherit (warning)))
+  "Face for regions that are shielded (marked as read-only).
+This face is used on the region target by org-roam-insertion
+during an `org-roam-capture'."
+  :group 'org-roam-faces)
+
+(defun org-roam-shield-region (beg end)
+  "Shield region against modifications.
+BEG and END are markers for the beginning and end regions.
+REGION must be a cons-cell containing the marker to the region
+beginning and maximum values."
+  (add-text-properties beg end
+                       '(font-lock-face org-roam-shielded
+                                        read-only t)
+                       (marker-buffer beg)))
+
+(defun org-roam-unshield-region (beg end)
+  "Unshield the shielded REGION.
+BEG and END are markers for the beginning and end regions."
+  (let ((inhibit-read-only t))
+    (remove-text-properties beg end
+                            '(font-lock-face org-roam-shielded
+                                             read-only t)
+                            (marker-buffer beg))))
+
+;;; Org-mode utilities
+;;;; Motions
+(defun org-roam-up-heading-or-point-min ()
+  "Fixed version of Org's `org-up-heading-or-point-min'."
+  (ignore-errors (org-back-to-heading t))
+  (let ((p (point)))
+    (if (< 1 (funcall outline-level))
+        (progn
+          (org-up-heading-safe)
+          (when (= (point) p)
+            (goto-char (point-min))))
+      (unless (bobp) (goto-char (point-min))))))
+
+;;;; Keywords
+(defun org-roam-get-keyword (name &optional file bound)
+  "Return keyword property NAME from an org FILE.
+FILE defaults to current file.
+Only scans up to BOUND bytes of the document."
+  (unless bound
+    (setq bound 1024))
+  (if file
+      (with-temp-buffer
+        (insert-file-contents file nil 0 bound)
+        (org-roam--get-keyword name))
+    (org-roam--get-keyword name bound)))
+
+(defun org-roam--get-keyword (name &optional bound)
+  "Return keyword property NAME in current buffer.
+If BOUND, scan up to BOUND bytes of the buffer."
+  (save-excursion
+    (let ((re (format "^#\\+%s:[ \t]*\\([^\n]+\\)" (upcase name))))
+      (goto-char (point-min))
+      (when (re-search-forward re bound t)
+        (buffer-substring-no-properties (match-beginning 1) (match-end 1))))))
+
+(defun org-roam-set-keyword (key value)
+  "Set keyword KEY to VALUE.
+If the property is already set, it's value is replaced."
+  (org-with-point-at 1
+    (let ((case-fold-search t))
+      (if (re-search-forward (concat "^#\\+" key ":\\(.*\\)") (point-max) t)
+          (if (string-blank-p value)
+              (kill-whole-line)
+            (replace-match (concat " " value) 'fixedcase nil nil 1))
+        (while (and (not (eobp))
+                    (looking-at "^[#:]"))
+          (if (save-excursion (end-of-line) (eobp))
+              (progn
+                (end-of-line)
+                (insert "\n"))
+            (forward-line)
+            (beginning-of-line)))
+        (insert "#+" key ": " value "\n")))))
+
+(defun org-roam-erase-keyword (keyword)
+  "Erase the line where the KEYWORD is, setting line from the top of the file."
+  (let ((case-fold-search t))
+    (org-with-point-at 1
+      (when (re-search-forward (concat "^#\\+" keyword ":") nil t)
+        (beginning-of-line)
+        (delete-region (point) (line-end-position))
+        (delete-char 1)))))
+
+;;;; Properties
+(defun org-roam-add-property (val prop)
+  "Add VAL value to PROP property for the node at point.
+Both, VAL and PROP are strings."
+  (let* ((p (org-entry-get (point) prop))
+         (lst (when p (split-string-and-unquote p)))
+         (lst (if (memq val lst) lst (cons val lst)))
+         (lst (seq-uniq lst)))
+    (org-set-property prop (combine-and-quote-strings lst))
+    val))
+
+(defun org-roam-remove-property (prop &optional val)
+  "Remove VAL value from PROP property for the node at point.
+Both VAL and PROP are strings.
+
+If VAL is not specified, user is prompted to select a value."
+  (let* ((p (org-entry-get (point) prop))
+         (lst (when p (split-string-and-unquote p)))
+         (prop-to-remove (or val (completing-read "Remove: " lst)))
+         (lst (delete prop-to-remove lst)))
+    (if lst
+        (org-set-property prop (combine-and-quote-strings lst))
+      (org-delete-property prop))
+    prop-to-remove))
+
+;;; Logs
+(defvar org-roam-verbose)
+(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))))
+
+;;; Diagnostics
+;; TODO Update this to also get commit hash
+;;;###autoload
+(defun org-roam-version (&optional message)
+  "Return `org-roam' version.
+Interactively, or when MESSAGE is non-nil, show in the echo area."
+  (interactive)
+  (let* ((version
+          (with-temp-buffer
+            (insert-file-contents-literally (locate-library "org-roam.el"))
+            (goto-char (point-min))
+            (save-match-data
+              (if (re-search-forward "\\(?:;; Version: \\([^z-a]*?$\\)\\)" nil nil)
+                  (substring-no-properties (match-string 1))
+                "N/A")))))
+    (if (or message (called-interactively-p 'interactive))
+        (message "%s" version)
+      version)))
+
+;;;###autoload
+(defun org-roam-diagnostics ()
+  "Collect and print info for `org-roam' issues."
+  (interactive)
+  (with-current-buffer (switch-to-buffer-other-window (get-buffer-create "*org-roam diagnostics*"))
+    (erase-buffer)
+    (insert (propertize "Copy info below this line into issue:\n" 'face '(:weight bold)))
+    (insert (format "- Emacs: %s\n" (emacs-version)))
+    (insert (format "- Framework: %s\n"
+                    (condition-case _
+                        (completing-read "I'm using the following Emacs framework:"
+                                         '("Doom" "Spacemacs" "N/A" "I don't know"))
+                      (quit "N/A"))))
+    (insert (format "- Org: %s\n" (org-version nil 'full)))
+    (insert (format "- Org-roam: %s" (org-roam-version)))))
+
+
+(provide 'org-roam-utils)
+;;; org-roam-utils.el ends here

org-roam.el

@@ -1,697 +1,319 @@
-;;; org-roam.el --- Roam Research replica with Org-mode -*- coding: utf-8; lexical-binding: t -*-
+;;; org-roam.el --- A database abstraction layer for Org-mode -*- coding: utf-8; lexical-binding: t; -*-
+
+;; Copyright © 2020-2021 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: 2.0.0
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (org "9.4") (emacsql "3.0.0") (emacsql-sqlite "1.0.0") (magit-section "2.90.1") (filenotify-recursive "0.0.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:
 ;;
-
+;; Org-roam is a Roam Research inspired Emacs package and is an addition to
+;; Org-mode to have a way to quickly process complex SQL-like queries over a
+;; large set of plain text Org-mode files. To achieve this Org-roam provides a
+;; database abstraction layer, the capabilities of which include, but are not
+;; limited to:
+;;
+;; - Link graph traversal and visualization.
+;; - Instantaneous SQL-like queries on headlines
+;;   - What are my TODOs, scheduled for X, or due by Y?
+;; - Accessing the properties of a node, such as its tags, refs, TODO state or
+;;   priority.
+;;
+;; All of these functionality is powered by this layer. Hence, at its core
+;; Org-roam's primary goal is to provide a resilient dual representation of
+;; what's already available in plain text, while cached in a binary database,
+;; that is cheap to maintain, easy to understand, and is as up-to-date as it
+;; possibly can. For users who would like to perform arbitrary programmatic
+;; queries on their Org files Org-roam also exposes an API to this database
+;; abstraction layer.
+;;
+;; -----------------------------------------------------------------------------
+;;
+;; In order for the package to correctly work through your interactive session
+;; it's mandatory to add somewhere to your configuration the next form:
+;;
+;;     (org-roam-db-autosync-mode)
+;;
+;; The form can be called both, before or after loading the package, which is up
+;; to your preferences. If you call this before the package is loaded, then it
+;; will automatically load the package.
+;;
+;; -----------------------------------------------------------------------------
+;;
+;; This package also comes with a set of officially supported extensions that
+;; provide extra features. You can find them in the "extensions/" subdirectory.
+;; These extensions are not automatically loaded with `org-roam`, but they still
+;; will be lazy-loaded through their own `autoload's.
+;;
+;; Org-roam also has other extensions that don't come together with this package.
+;; Such extensions are distributed as their own packages, while also
+;; authored and maintained by different people on distinct repositories. The
+;; majority of them can be found at https://github.com/org-roam and MELPA.
+;;
 ;;; Code:
-(eval-when-compile (require 'cl-lib))
-(require 'dash)
-(require 'org-element)
-(require 'async)
-(require 'subr-x)
-(require 's)
 (require 'f)
+(require 'dash)
 
-;;; Customizations
+(require 'rx)
+(require 'seq)
+(require 'cl-lib)
+
+(require 'magit-section)
+
+(require 'emacsql)
+(require 'emacsql-sqlite)
+
+(require 'org)
+(require 'org-id)
+(require 'ol)
+(require 'org-element)
+(require 'org-capture)
+
+(require 'ansi-color) ; to strip ANSI color codes in `org-roam--list-files'
+
+(eval-when-compile
+  (require 'subr-x))
+
+(require 'org-roam-utils)
+(require 'org-roam-compat)
+
+;;; Options
 (defgroup org-roam nil
-  "Roam Research replica in Org-mode."
+  "A database abstraction layer for Org-mode."
   :group 'org
-  :prefix "org-roam-")
+  :prefix "org-roam-"
+  :link '(url-link :tag "Github" "https://github.com/org-roam/org-roam")
+  :link '(url-link :tag "Online Manual" "https://www.orgroam.com/manual.html"))
+
+(defgroup org-roam-faces nil
+  "Faces used by Org-roam."
+  :group 'org-roam
+  :group 'faces)
+
+(defcustom org-roam-verbose t
+  "Echo messages that are not errors."
+  :type 'boolean
+  :group 'org-roam)
 
 (defcustom org-roam-directory (expand-file-name "~/org-roam/")
-  "Org-roam directory."
+  "Default path to Org-roam files.
+All Org files, at any level of nesting, are considered part of the Org-roam."
   :type 'directory
   :group 'org-roam)
 
-(defcustom org-roam-position 'right
-  "Position of `org-roam' buffer.
+(defcustom org-roam-find-file-hook nil
+  "Hook run when an Org-roam file is visited."
+  :group 'org-roam
+  :type 'hook)
 
-Valid values are
- * left,
- * right."
-  :type '(choice (const left)
-                 (const right))
+(defcustom org-roam-file-extensions '("org")
+  "List of file extensions to be included by Org-Roam.
+While a file extension different from \".org\" may be used, the
+file still needs to be an `org-mode' file, and it is the user's
+responsibility to ensure that."
+  :type '(repeat string)
   :group 'org-roam)
 
-(defcustom org-roam-link-representation 'id
-  "The value used to represent an org-roam link.
-
-Valid values are
- * file,
- * title."
-  :type '(choice (const id)
-                 (const title))
+(defcustom org-roam-file-exclude-regexp nil
+  "Files matching this regular expression are excluded from the Org-roam."
+  :type '(choice
+          (string :tag "Regular expression matching files to ignore")
+          (const :tag "Include everything" nil))
   :group 'org-roam)
 
-(defcustom org-roam-timestamped-files nil
-  "Whether to use timestamps to generate unique filenames."
-  :type 'boolean
-  :group 'org-roam)
-
-(defcustom org-roam-timestamp-format "%Y-%m-%d%H%M%S"
-  "The timestamp format to use filenames.")
-
-(defcustom org-roam-link-id-format "§%s"
-  "The format string used when inserting org-roam links that use id."
-  :type 'string
-  :group 'org-roam)
-
-(defcustom org-roam-link-title-format "%s"
-  "The format string used when inserting org-roam links that use their title."
-  :type 'string
-  :group 'org-roam)
-
-(defcustom org-roam-autopopulate-title t "Whether to autopopulate the title."
-  :type 'boolean
-  :group 'org-roam)
-
-(defcustom org-roam-buffer-width 0.33 "Width of `org-roam' buffer."
-  :type 'number
-  :group 'org-roam)
-
-(defcustom org-roam-buffer "*org-roam*"
-  "Org-roam buffer name."
-  :type 'string
-  :group 'org-roam)
-
-(defcustom org-roam-graph-viewer (executable-find "firefox")
-  "Path to executable for viewing SVG."
-  :type 'string
-  :group 'org-roam)
-
-(defcustom org-roam-graphviz-executable (executable-find "dot")
-  "Path to graphviz executable."
-  :type 'string
-  :group 'org-roam)
-
-;;; Polyfills
-;; These are for functions I use that are only available in newer Emacs
-
-;; Introduced in Emacs 27.1
-(unless (fboundp 'make-empty-file)
-  (defun make-empty-file (filename &optional parents)
-    "Create an empty file FILENAME.
-Optional arg PARENTS, if non-nil then creates parent dirs as needed.
-
-If called interactively, then PARENTS is non-nil."
-    (interactive
-     (let ((filename (read-file-name "Create empty file: ")))
-       (list filename t)))
-    (when (and (file-exists-p filename) (null parents))
-      (signal 'file-already-exists `("File exists" ,filename)))
-    (let ((paren-dir (file-name-directory filename)))
-      (when (and paren-dir (not (file-exists-p paren-dir)))
-        (make-directory paren-dir parents)))
-    (write-region "" nil filename nil 0)))
-
-;;; Dynamic variables
-(defvar org-roam-cache-initialized nil
-  "Boolean value indicating whether the cache is initialized.")
-
-(defvar org-roam-forward-links-cache (make-hash-table :test #'equal)
-  "Cache containing forward links.")
-
-(defvar org-roam-backward-links-cache (make-hash-table :test #'equal)
-  "Cache containing backward-links.")
-
-(defvar org-roam-titles-cache (make-hash-table :test #'equal)
-  "Cache containing titles for org-roam files.")
-
-(defvar org-roam-current-file nil
-  "Currently displayed file in `org-roam' buffer.")
-
-;;; Utilities
-(defun org-roam--ensure-cache-built ()
-  "Ensures that org-roam cache is built."
-  (unless org-roam-cache-initialized
-    (org-roam--build-cache-async)
-    (user-error "Your Org-Roam cache isn't built yet! Please wait")))
-
-(defun org-roam--org-roam-file-p ()
-  "Return t if file is part of org-roam system, false otherwise."
-  (and (buffer-file-name (current-buffer))
-       (f-child-of-p (file-truename (buffer-file-name (current-buffer)))
-                     org-roam-directory)))
-
-(defun org-roam--get-title (file)
-  "Return title of `FILE'.
-
-It first tries the cache. If the cache does not contain the file,
-it will return the title by loading the file."
-  (or (gethash file org-roam-titles-cache)
-      (org-roam--extract-file-title file)))
-
-(defun org-roam--find-files (dir)
-  "Return all org-roam files in `DIR'."
-  (if (file-exists-p dir)
-      (let ((files (directory-files dir t "." t))
-            (dir-ignore-regexp (concat "\\(?:"
-                                       "\\."
-                                       "\\|\\.\\."
-                                       "\\)$"))
-            result)
-        (dolist (file files)
-          (cond
-           ((file-directory-p file)
-            (when (not (string-match dir-ignore-regexp file))
-              (setq result (append (org-roam--find-files file) result))))
-           ((and (file-readable-p file)
-                 (string= (file-name-extension file) "org"))
-            (setq result (cons (file-truename file) result)))))
-        result)))
-
-(defun org-roam--find-all-files ()
-  "Return all org-roam files."
-  (org-roam--find-files (file-truename org-roam-directory)))
-
-(defun org-roam--get-file-path (id &optional absolute)
-  "Convert identifier `ID' to file path.
-
-If `ABSOLUTE', return the absolute file-path. Else, return the relative file-path."
-  (let ((absolute-file-path (file-truename
-                             (expand-file-name
-                              (concat id ".org")
-                              org-roam-directory))))
-    (if absolute
-        absolute-file-path
-      (file-relative-name absolute-file-path
-                          (file-truename org-roam-directory)))))
-
-(defun org-roam--get-id (file-path)
-  "Convert `FILE-PATH' to the org-roam id."
-  (file-name-sans-extension
-   (file-relative-name
-    (file-truename file-path)
-    (file-truename org-roam-directory))))
-
-(defun org-roam--get-title-or-id (file-path)
-  "Convert `FILE-PATH' to the file title, if it exists. Else, return the id."
-  (or (org-roam--get-title file-path)
-      (org-roam--get-id file-path)))
-
-(defun org-roam--title-to-id (title)
-  "Convert TITLE to id."
-  (let* ((s (s-downcase title))
-         (s (replace-regexp-in-string "[^a-zA-Z0-9_ ]" "" s))
-         (s (s-split " " s))
-         (s (s-join "_" s)))
-    s))
-
-;;; Creating org-roam files
-(defun org-roam--populate-title (file &optional title)
-  "Populate title line for FILE using TITLE, if provided.
-If not provided, derive the title from the file name."
-  (let ((title (or title
-                   (-> file
-                       (file-name-nondirectory)
-                       (file-name-sans-extension)
-                       (split-string "_")
-                       (string-join " ")
-                       (s-titleize)))))
-    (write-region
-     (concat
-      "#+TITLE: "
-      title
-      "\n\n")
-     nil file nil)))
-
-(defun org-roam--make-file (file-path &optional title)
-  "Create an org-roam file at FILE-PATH, optionally setting the TITLE attribute."
-  (if (file-exists-p file-path)
-      (error (format "Aborting, file already exists at " file-path))
-    (if org-roam-autopopulate-title
-        (org-roam--populate-title file-path title)
-      (make-empty-file file-path))))
-
-(defun org-roam--new-file-named (slug)
-  "Create a new file named `SLUG'.
-`SLUG' is the short file name, without a path or a file extension."
-  (interactive "sNew filename (without extension): ")
-  (let ((file-path (org-roam--get-file-path slug t)))
-    (unless (file-exists-p file-path)
-      (org-roam--make-file file-path))
-    (find-file file-path)))
-
-(defun org-roam--get-new-id ()
-  "Return a new ID, generated from the current time."
-  (format-time-string org-roam-timestamp-format (current-time)))
-
-(defun org-roam-new-file ()
-  "Quickly create a new file, using the current timestamp."
-  (interactive)
-  (org-roam--new-file-named (org-roam--get-new-id)))
-
-;;; Inserting org-roam links
-(defun org-roam-insert ()
-  "Insert an org-roam link."
-  (interactive)
-  (pcase org-roam-link-representation
-    ('id (org-roam--insert-id))
-    ('title (org-roam--insert-title))))
-
-(defun org-roam--insert-title ()
-  "Find `ID', and insert a relative org link to it at point."
-  (let* ((completions (mapcar (lambda (file)
-                                (list (org-roam--get-title-or-id file)
-                                      (org-roam--get-id file)))
-                              (org-roam--find-all-files)))
-         (title (completing-read "File: " completions))
-         (id (cadr (assoc title completions))))
-    (when (not id)
-      (if org-roam-timestamped-files
-          (setq id (org-roam--get-new-id)))
-        (read-string "Enter new file id: " (org-roam--title-to-id title)))
-    (let ((file-path (org-roam--get-file-path id)))
-      (unless (file-exists-p file-path)
-        (org-roam--make-file file-path title))
-      (insert (format "[[%s][%s]]"
-                      (concat "file:" file-path)
-                      (format org-roam-link-title-format title))))))
-
-(defun org-roam--insert-id ()
-  "Find `ID', and insert a relative org link to it at point."
-  (let* ((id (completing-read "File: " (mapcar #'org-roam--get-id (org-roam--find-all-files))))
-         (file-path (org-roam--get-file-path id)))
-    (unless (file-exists-p file-path)
-      (org-roam--make-file file-path))
-    (insert (format "[[%s][%s]]"
-                    (concat "file:" file-path)
-                    (format org-roam-link-id-format id)))))
-
-;;; Finding org-roam files
-(defun org-roam-find-file ()
-  "Find and open an org-roam file."
-  (interactive)
-  (let* ((completions (mapcar (lambda (file)
-                                (list (org-roam--get-title-or-id file) file))
-                              (org-roam--find-all-files)))
-         (title-or-id (completing-read "File: " completions))
-         (file-path (cadr (assoc title-or-id completions))))
-    (unless file-path
-      (let ((id (if org-roam-timestamped-files
-                    (org-roam--get-new-id)
-                  (read-string "Enter new file id: "
-                   (org-roam--title-to-id title-or-id)))))
-        (setq file-path (org-roam--get-file-path id t))))
-    (unless (file-exists-p file-path)
-      (org-roam--make-file file-path title-or-id))
-    (find-file file-path)))
-
-;;; Building the org-roam cache (asynchronously)
-(defun org-roam--build-cache-async ()
-  "Builds the cache asychronously, saving it into the org-roam caches."
-  (interactive)
-  (async-start
-   `(lambda ()
-      (require 'org)
-      (require 'org-element)
-      (require 'subr-x)                 ; temp-fix
-      (require 'cl-lib)
-      ,(async-inject-variables "org-roam-directory")
-      (let ((backward-links (make-hash-table :test #'equal))
-            (forward-links (make-hash-table :test #'equal))
-            (file-titles (make-hash-table :test #'equal)))
-        (cl-labels ((org-roam--find-files
-                     (dir)
-                     (if (file-exists-p dir)
-                         (let ((files (directory-files dir t "." t))
-                               (dir-ignore-regexp (concat "\\(?:"
-                                                          "\\."
-                                                          "\\|\\.\\."
-                                                          "\\)$"))
-                               result)
-                           (dolist (file files)
-                             (cond
-                              ((file-directory-p file)
-                               (when (not (string-match dir-ignore-regexp file))
-                                 (setq result (append (org-roam--find-files file) result))))
-                              ((and (file-readable-p file)
-                                    (string= (file-name-extension file) "org"))
-                               (setq result (cons (file-truename file) result)))))
-                           result)))
-                    (org-roam--parse-content
-                     (file)
-                     (with-temp-buffer
-                       (insert-file-contents file)
-                       (with-current-buffer (current-buffer)
-                         (org-element-map (org-element-parse-buffer) 'link
-                           (lambda (link)
-                             (let ((type (org-element-property :type link))
-                                   (path (org-element-property :path link))
-                                   (start (org-element-property :begin link)))
-                               (when (and (string= type "file")
-                                          (string= (file-name-extension path) "org"))
-                                 (goto-char start)
-                                 (let* ((element (org-element-at-point))
-                                        (content (or (org-element-property :raw-value element)
-                                                     (buffer-substring
-                                                      (or (org-element-property :content-begin element)
-                                                          (org-element-property :begin element))
-                                                      (or (org-element-property :content-end element)
-                                                          (org-element-property :end element))))))
-                                   (list :from file
-                                         :to (file-truename (expand-file-name path org-roam-directory))
-                                         :content (string-trim content))))))))))
-                    (org-roam--process-items
-                     (items)
-                     (mapcar
-                      (lambda (item)
-                        (pcase-let ((`(:from ,p-from :to ,p-to :content ,content) item))
-                          ;; Build forward-links
-                          (let ((links (gethash p-from forward-links)))
-                            (if links
-                                (puthash p-from
-                                         (if (member p-to links)
-                                             links
-                                           (cons p-to links)) forward-links)
-                              (puthash p-from (list p-to) forward-links)))
-                          ;; Build backward-links
-                          (let ((contents-hash (gethash p-to backward-links)))
-                            (if contents-hash
-                                (if-let ((contents-list (gethash p-from contents-hash)))
-                                    (let ((updated (cons content contents-list)))
-                                      (puthash p-from updated contents-hash)
-                                      (puthash p-to contents-hash backward-links))
-                                  (progn
-                                    (puthash p-from (list content) contents-hash)
-                                    (puthash p-to contents-hash backward-links)))
-                              (let ((contents-hash (make-hash-table :test #'equal)))
-                                (puthash p-from (list content) contents-hash)
-                                (puthash p-to contents-hash backward-links))))))
-                      items))
-                    (org-roam--extract-title
-                     (buffer)
-                     (with-current-buffer buffer
-                       (org-element-map
-                           (org-element-parse-buffer)
-                           'keyword
-                         (lambda (kw)
-                           (when (string= (org-element-property :key kw) "TITLE")
-                             (org-element-property :value kw)))
-                         :first-match t))))
-          (let ((org-roam-files (org-roam--find-files org-roam-directory)))
-            (mapcar #'org-roam--process-items
-                    (mapcar #'org-roam--parse-content org-roam-files))
-            (mapcar (lambda (file)
-                      (with-temp-buffer
-                        (insert-file-contents file)
-                        (when-let ((title (org-roam--extract-title (current-buffer))))
-                          (puthash file title file-titles))))
-                    org-roam-files)))
-        (list
-         :forward forward-links
-         :backward backward-links
-         :titles file-titles)))
-   (lambda (cache)
-     (setq org-roam-forward-links-cache (plist-get cache :forward))
-     (setq org-roam-backward-links-cache (plist-get cache :backward))
-     (setq org-roam-titles-cache (plist-get cache :titles))
-     (setq org-roam-cache-initialized t)
-     (message "Org-roam cache built!"))))
-
-(defun org-roam--insert-item (item)
-  "Insert `ITEM' into org-roam caches.
-
-`ITEM' is of the form: (:from from-path :to to-path :content preview-content)
-
-Before calling this function, `org-roam-cache' should be already populated."
-  (pcase-let ((`(:from ,p-from :to ,p-to :content ,content) item))
-    ;; Build forward-links
-    (let ((links (gethash p-from org-roam-forward-links-cache)))
-      (if links
-          (puthash p-from
-                   (if (member p-to links)
-                       links
-                     (cons p-to links)) org-roam-forward-links-cache)
-        (puthash p-from (list p-to) org-roam-forward-links-cache)))
-    ;; Build backward-links
-    (let ((contents-hash (gethash p-to org-roam-backward-links-cache)))
-      (if contents-hash
-          (if-let ((contents-list (gethash p-from contents-hash)))
-              (let ((updated (cons content contents-list)))
-                (puthash p-from updated contents-hash)
-                (puthash p-to contents-hash org-roam-backward-links-cache))
-            (progn
-              (puthash p-from (list content) contents-hash)
-              (puthash p-to contents-hash org-roam-backward-links-cache)))
-        (let ((contents-hash (make-hash-table :test #'equal)))
-          (puthash p-from (list content) contents-hash)
-          (puthash p-to contents-hash org-roam-backward-links-cache))))))
-
-(defun org-roam--parse-content ()
-  "Parse the current buffer, and return a list of items for processing."
-  (with-current-buffer (current-buffer)
-    (org-element-map (org-element-parse-buffer) 'link
-      (lambda (link)
-        (let ((type (org-element-property :type link))
-              (path (org-element-property :path link))
-              (start (org-element-property :begin link)))
-          (when (and (string= type "file")
-                     (string= (file-name-extension path) "org"))
-            (goto-char start)
-            (let* ((element (org-element-at-point))
-                   (content (or (org-element-property :raw-value element)
-                                (buffer-substring
-                                 (or (org-element-property :content-begin element)
-                                     (org-element-property :begin element))
-                                 (or (org-element-property :content-end element)
-                                     (org-element-property :end element))))))
-              (list :from (file-truename (buffer-file-name (current-buffer)))
-                    :to (file-truename (expand-file-name path org-roam-directory))
-                    :content (string-trim content)))))))))
-
-(defun org-roam--clear-cache-for-buffer (buffer)
-  "Remove any related links to the file for `BUFFER'.
-
-This is equivalent to removing the node from the graph."
-  (with-current-buffer (current-buffer)
-    (let ((file (file-truename (buffer-file-name buffer))))
-      ;; Step 1: Remove all existing links for file
-      (when-let ((forward-links (gethash file org-roam-forward-links-cache)))
-        ;; Delete backlinks to file
-        (dolist (link forward-links)
-          (when-let ((backward-links (gethash link org-roam-backward-links-cache)))
-            (remhash file backward-links)
-            (puthash link backward-links org-roam-backward-links-cache)))
-        ;; Clean out forward links
-        (remhash file org-roam-forward-links-cache))
-      ;; Step 2: Remove from the title cache
-      (remhash file org-roam-titles-cache))))
-
-(defun org-roam--update-cache-title (buffer)
-  "Inserts the `TITLE' of file in buffer into the cache."
-  (when-let ((title (org-roam--extract-title buffer)))
-    (puthash (file-truename (buffer-file-name buffer))
-             title
-             org-roam-titles-cache)))
-
-(defun org-roam--update-cache ()
-  "Update org-roam caches for the current buffer file."
-  (save-excursion
-    (org-roam--clear-cache-for-buffer (current-buffer))
-    ;; Insert into title cache
-    (org-roam--update-cache-title (current-buffer))
-    ;; Insert new items
-    (let ((items (org-roam--parse-content)))
-      (dolist (item items)
-        (org-roam--insert-item item)))
-    ;; Rerender buffer
-    (org-roam--maybe-update-buffer :redisplay t)))
-
-;;; Org-roam daily notes
-(defun org-roam-today ()
-  "Create the file for today."
-  (interactive)
-  (org-roam--new-file-named (format-time-string "%Y-%m-%d" (current-time))))
-
-(defun org-roam-tomorrow ()
-  "Create the file for tomorrow."
-  (interactive)
-  (org-roam--new-file-named (format-time-string "%Y-%m-%d" (time-add 86400 (current-time)))))
-
-(defun org-roam-date ()
-  "Create the file for any date using the calendar."
-  (interactive)
-  (let ((time (org-read-date nil 'to-time nil "Date:  ")))
-    (org-roam--new-file-named (format-time-string "%Y-%m-%d" time))))
-
-;;; Org-roam buffer updates
-(defun org-roam--extract-title (buffer)
-  "Extract the title from `BUFFER'."
-  (with-current-buffer buffer
-    (org-element-map
-        (org-element-parse-buffer)
-        'keyword
-      (lambda (kw)
-        (when (string= (org-element-property :key kw) "TITLE")
-          (org-element-property :value kw)))
-      :first-match t)))
-
-(defun org-roam--extract-file-title (file)
-  "Extract the title from `FILE'."
-  (with-temp-buffer
-    (insert-file-contents file)
-    (org-roam--extract-title (current-buffer))))
-
-(defun org-roam-update (file-path)
-  "Show the backlinks for given org file for file at `FILE-PATH'."
-  (org-roam--ensure-cache-built)
-  (let ((buffer-title (org-roam--get-title-or-id file-path)))
-    (with-current-buffer org-roam-buffer
-      (let ((inhibit-read-only t))
-        (erase-buffer)
-        (when (not (eq major-mode 'org-mode))
-          (org-mode))
-        (make-local-variable 'org-return-follows-link)
-        (setq org-return-follows-link t)
-        (insert
-         (propertize buffer-title 'font-lock-face 'org-document-title))
-        (if-let ((backlinks (gethash file-path org-roam-backward-links-cache)))
-            (progn
-              (insert (format "\n\n* %d Backlinks\n"
-                              (hash-table-count backlinks)))
-              (maphash (lambda (file-from contents)
-                         (insert (format "** [[file:%s][%s]]\n"
-                                         file-from
-                                         (org-roam--get-title-or-id file-from)))
-                         (dolist (content contents)
-                           (insert (concat (propertize (s-trim (s-replace "\n" " " content))
-                                                       'font-lock-face 'org-block)
-                                           "\n\n"))))
-                       backlinks))
-          (insert "\n\n* No backlinks!")))
-      (read-only-mode 1)))
-  (setq org-roam-current-file file-path))
-
-;;; Show/hide the org-roam buffer
-(define-inline org-roam--current-visibility ()
-  "Return whether the current visibility state of the org-roam buffer.
-Valid states are 'visible, 'exists and 'none."
-  (declare (side-effect-free t))
-  (inline-quote
-   (cond
-    ((get-buffer-window org-roam-buffer) 'visible)
-    ((get-buffer org-roam-buffer) 'exists)
-    (t 'none))))
-
-(defun org-roam--set-width (width)
-  "Set the width of the org-roam buffer to `WIDTH'."
-  (unless (one-window-p)
-    (let ((window-size-fixed)
-          (w (max width window-min-width)))
-      (cond
-       ((> (window-width) w)
-        (shrink-window-horizontally  (- (window-width) w)))
-       ((< (window-width) w)
-        (enlarge-window-horizontally (- w (window-width))))))))
-
-(defun org-roam--setup-buffer ()
-  "Setup the `org-roam' buffer at the `org-roam-position'."
-  (let ((window (get-buffer-window)))
-    (-> (get-buffer-create org-roam-buffer)
-        (display-buffer-in-side-window
-         `((side . ,org-roam-position)))
-        (select-window))
-    (org-roam--set-width
-     (round (* (frame-width)
-               org-roam-buffer-width)))
-    (select-window window)))
-
-(defun org-roam ()
-  "Pops up the window `org-roam-buffer' accordingly."
-  (interactive)
-  (pcase (org-roam--current-visibility)
-    ('visible (delete-window (get-buffer-window org-roam-buffer)))
-    ('exists (org-roam--setup-buffer))
-    ('none (org-roam--setup-buffer))))
-
-;;; The minor mode definition that updates the buffer
-(defun org-roam--maybe-enable ()
-  "Enable org-roam updating for file, if file is an org-roam file."
-  (when (org-roam--org-roam-file-p)
-    (org-roam--enable)))
-
-(defun org-roam--enable ()
-  "Enable org-roam updating for file.
-
-1. If the cache does not yet exist, build it asynchronously.
-2. Setup hooks for updating the cache, and the org-roam buffer."
-  (unless org-roam-cache-initialized
-    (org-roam--build-cache-async))
-  (add-hook 'post-command-hook #'org-roam--maybe-update-buffer nil t)
-  (add-hook 'after-save-hook #'org-roam--update-cache nil t))
-
-(defun org-roam--disable ()
-  "Disable org-roam updating for file.
-
-1. Remove hooks for updating the cache, and the org-roam buffer."
-  (remove-hook 'post-command-hook #'org-roam--maybe-update-buffer)
-  (remove-hook 'after-save-hook #'org-roam--update-cache))
-
-(cl-defun org-roam--maybe-update-buffer (&key redisplay)
-  "Update `org-roam-buffer' with the necessary information.
-This needs to be quick/infrequent, because this is run at
-`post-command-hook'."
-  (with-current-buffer (window-buffer)
-    (when (and (get-buffer org-roam-buffer)
-               (buffer-file-name (current-buffer))
-               (file-exists-p (file-truename (buffer-file-name (current-buffer))))
-               (or redisplay
-                   (not (string= org-roam-current-file
-                                 (file-truename (buffer-file-name (current-buffer)))))))
-      (org-roam-update (file-truename (buffer-file-name (window-buffer)))))))
-
-(define-minor-mode org-roam-mode
-  "Global minor mode to automatically update the org-roam buffer."
-  :require 'org-roam
-  (if org-roam-mode
-      (org-roam--maybe-enable)
-    (org-roam--disable)))
-
-;;; Building the Graphviz graph
-(defun org-roam-build-graph ()
-  "Build graphviz graph output."
-  (org-roam--ensure-cache-built)
-  (with-temp-buffer
-    (insert "digraph {\n")
-    (mapcar (lambda (file)
-              (insert
-               (format "  \"%s\" [URL=\"roam://%s\"];\n"
-                       (org-roam--get-id file)
-                       file)))
-            (org-roam--find-all-files))
-    (maphash
-     (lambda (from-link to-links)
-       (dolist (to-link to-links)
-         (insert (format "  \"%s\" -> \"%s\";\n"
-                         (org-roam--get-id from-link)
-                         (org-roam--get-id to-link))))
-       )
-     org-roam-forward-links-cache)
-    (insert "}")
-    (buffer-string)))
-
-(defun org-roam-show-graph ()
-  "Generate the org-roam graph in SVG format, and display it using `org-roam-graph-viewer'."
-  (interactive)
-  (unless org-roam-graphviz-executable
-    (setq org-roam-graphviz-executable (executable-find "dot")))
-  (unless org-roam-graphviz-executable
-    (user-error "Can't find graphviz executable. Please check if it is in your path"))
-  (declare (indent 0))
-  (let ((temp-dot (expand-file-name "graph.dot" temporary-file-directory))
-        (temp-graph (expand-file-name "graph.svg" temporary-file-directory))
-        (graph (org-roam-build-graph)))
-    (with-temp-file temp-dot
-      (insert graph))
-    (call-process org-roam-graphviz-executable nil 0 nil temp-dot "-Tsvg" "-o" temp-graph)
-    (call-process org-roam-graph-viewer nil 0 nil temp-graph)))
-
-
+(defcustom org-roam-list-files-commands
+  (if (member system-type '(windows-nt ms-dos cygwin))
+      nil
+    '(find fd fdfind rg))
+  "Commands that will be used to find Org-roam files.
+
+It should be a list of symbols or cons cells representing any of the following
+supported file search methods.
+
+The commands will be tried in order until an executable for a command is found.
+The Elisp implementation is used if no command in the list is found.
+
+  `find'
+    Use find as the file search method.
+    Example command:
+    find /path/to/dir -type f \( -name \"*.org\" -o -name \"*.org.gpg\" \)
+
+  `fd'
+    Use fd as the file search method.
+    Example command: fd /path/to/dir/ --type file -e \".org\" -e \".org.gpg\"
+
+  `fdfind'
+    Same as `fd'. It's an alias that used in some OSes (e.g. Debian, Ubuntu)
+
+  `rg'
+    Use ripgrep as the file search method.
+    Example command: rg /path/to/dir/ --files -g \"*.org\" -g \"*.org.gpg\"
+
+By default, `executable-find' will be used to look up the path to the
+executable. If a custom path is required, it can be specified together with the
+method symbol as a cons cell. For example: '(find (rg . \"/path/to/rg\"))."
+  :type '(set (const :tag "find" find)
+              (const :tag "fd" fd)
+              (const :tag "fdfind" fdfind)
+              (const :tag "rg" rg)
+              (const :tag "elisp" nil)))
+
+;;; Library
+(defun org-roam-file-p (&optional file)
+  "Return t if FILE is an Org-roam file, nil otherwise.
+If FILE is not specified, use the current buffer's file-path.
+
+FILE is an Org-roam file if:
+- It's located somewhere under `org-roam-directory'
+- It has a matching file extension (`org-roam-file-extensions')
+- It doesn't match excluded regexp (`org-roam-file-exclude-regexp')"
+  (let* ((path (or file (buffer-file-name (buffer-base-buffer))))
+         (ext (when path (org-roam--file-name-extension path)))
+         (ext (if (string= ext "gpg")
+                  (org-roam--file-name-extension (file-name-sans-extension path))
+                ext)))
+    (save-match-data
+      (and
+       path
+       (member ext org-roam-file-extensions)
+       (not (and org-roam-file-exclude-regexp
+                 (string-match-p org-roam-file-exclude-regexp path)))
+       (f-descendant-of-p path (expand-file-name org-roam-directory))))))
+
+(defun org-roam-list-files ()
+  "Return a list of all Org-roam files under `org-roam-directory'.
+See `org-roam-file-p' for how each file is determined to be as
+part of Org-Roam."
+  (org-roam--list-files (expand-file-name org-roam-directory)))
+
+(defun org-roam-buffer-p (&optional buffer)
+  "Return t if BUFFER is for an Org-roam file.
+If BUFFER is not specified, use the current buffer."
+  (let ((buffer (or buffer (current-buffer)))
+        path)
+    (with-current-buffer buffer
+      (and (derived-mode-p 'org-mode)
+           (setq path (buffer-file-name (buffer-base-buffer)))
+           (org-roam-file-p path)))))
+
+(defun org-roam-buffer-list ()
+  "Return a list of buffers that are Org-roam files."
+  (--filter (org-roam-buffer-p it)
+            (buffer-list)))
+
+(defun org-roam--file-name-extension (filename)
+  "Return file name extension for FILENAME.
+Like `file-name-extension', but does not strip version number."
+  (save-match-data
+    (let ((file (file-name-nondirectory filename)))
+      (if (and (string-match "\\.[^.]*\\'" file)
+               (not (eq 0 (match-beginning 0))))
+          (substring file (+ (match-beginning 0) 1))))))
+
+(defun org-roam--list-files (dir)
+  "Return all Org-roam files located recursively within DIR.
+Use external shell commands if defined in `org-roam-list-files-commands'."
+  (let (path exe)
+    (cl-dolist (cmd org-roam-list-files-commands)
+      (pcase cmd
+        (`(,e . ,path)
+         (setq path (executable-find path)
+               exe  (symbol-name e)))
+        ((pred symbolp)
+         (setq path (executable-find (symbol-name cmd))
+               exe (symbol-name cmd)))
+        (wrong-type
+         (signal 'wrong-type-argument
+                 `((consp symbolp)
+                   ,wrong-type))))
+      (when path (cl-return)))
+    (if-let* ((files (when path
+                       (let ((fn (intern (concat "org-roam--list-files-" exe))))
+                         (unless (fboundp fn) (user-error "%s is not an implemented search method" fn))
+                         (funcall fn path (format "\"%s\"" dir)))))
+              (files (seq-filter #'org-roam-file-p files))
+              (files (mapcar #'expand-file-name files))) ; canonicalize names
+        files
+      (org-roam--list-files-elisp dir))))
+
+(defun org-roam--shell-command-files (cmd)
+  "Run CMD in the shell and return a list of files.
+If no files are found, an empty list is returned."
+  (--> cmd
+       (shell-command-to-string it)
+       (ansi-color-filter-apply it)
+       (split-string it "\n")
+       (seq-filter #'s-present? it)))
+
+(defun org-roam--list-files-search-globs (exts)
+  "Given EXTS, return a list of search globs.
+E.g. (\".org\") => (\"*.org\" \"*.org.gpg\")"
+  (cl-loop for e in exts
+           append (list (format "\"*.%s\"" e)
+                        (format "\"*.%s.gpg\"" e))))
+
+(defun org-roam--list-files-find (executable dir)
+  "Return all Org-roam files under DIR, using \"find\", provided as EXECUTABLE."
+  (let* ((globs (org-roam--list-files-search-globs org-roam-file-extensions))
+         (names (s-join " -o " (mapcar (lambda (glob) (concat "-name " glob)) globs)))
+         (command (s-join " " `(,executable "-L" ,dir "-type f \\(" ,names "\\)"))))
+    (org-roam--shell-command-files command)))
+
+(defun org-roam--list-files-fd (executable dir)
+  "Return all Org-roam files under DIR, using \"fd\", provided as EXECUTABLE."
+  (let* ((globs (org-roam--list-files-search-globs org-roam-file-extensions))
+         (extensions (s-join " -e " (mapcar (lambda (glob) (substring glob 2 -1)) globs)))
+         (command (s-join " " `(,executable "-L" ,dir "--type file" ,extensions))))
+    (org-roam--shell-command-files command)))
+
+(defalias 'org-roam--list-files-fdfind #'org-roam--list-files-fd)
+
+(defun org-roam--list-files-rg (executable dir)
+  "Return all Org-roam files under DIR, using \"rg\", provided as EXECUTABLE."
+  (let* ((globs (org-roam--list-files-search-globs org-roam-file-extensions))
+         (command (s-join " " `(,executable "-L" ,dir "--files"
+                                            ,@(mapcar (lambda (glob) (concat "-g " glob)) globs)))))
+    (org-roam--shell-command-files command)))
+
+(defun org-roam--list-files-elisp (dir)
+  "Return all Org-roam files under DIR, using Elisp based implementation."
+  (let ((regex (concat "\\.\\(?:"(mapconcat
+                                  #'regexp-quote org-roam-file-extensions
+                                  "\\|" )"\\)\\(?:\\.gpg\\)?\\'"))
+        result)
+    (dolist (file (org-roam--directory-files-recursively dir regex nil nil t) result)
+      (when (and (file-readable-p file)
+                 (org-roam-file-p file))
+        (push file result)))))
+
+;;; Package bootstrap
 (provide 'org-roam)
 
-;;; org-roam.el ends here
+(cl-eval-when (load eval)
+  (require 'org-roam-db)
+  (require 'org-roam-node)
+  (require 'org-roam-capture)
+  (require 'org-roam-mode)
+  (require 'org-roam-migrate))
 
-;; Local Variables:
-;; outline-regexp: ";;;+ "
-;; End:
+;;; org-roam.el ends here

shell.nix

@@ -1,10 +0,0 @@
-let
-  pkgs = import <nixpkgs> {};
-in
-pkgs.mkShell {
-  name = "docs";
-  buildInput = with pkgs; [
-    mkdocs
-    python3Packages.alabaster
-  ];
-}

tests/roam-files/bar.org

@@ -0,0 +1,6 @@
+:PROPERTIES:
+:ID:       440795d0-70c1-4165-993d-aebd5eef7a24
+:END:
+#+title: Bar
+
+[[id:884b2341-b7fe-434d-848c-5282c0727861][Foo]]

tests/roam-files/foo.org

@@ -0,0 +1,4 @@
+:PROPERTIES:
+:ID:       884b2341-b7fe-434d-848c-5282c0727861
+:END:
+#+title: Foo

tests/roam-files/roam-exclude.org

@@ -0,0 +1,7 @@
+:PROPERTIES:
+:ID:       53fadc75-f48e-461e-be06-44a1e88b2abe
+:ROAM_EXCLUDE: t
+:END:
+#+TITLE: Excluded by Org-roam
+
+This node is excluded by declaring ~ROAM_EXCLUDE: t~.

tests/test-org-roam.el

@@ -0,0 +1,83 @@
+;;; test-org-roam.el --- 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)
+
+(describe "org-roam-list-files"
+  (before-each
+    (setq org-roam-directory (expand-file-name "tests/roam-files")
+          org-roam-db-location (expand-file-name "org-roam.db" temporary-file-directory)
+          org-roam-file-extensions '("org")
+          org-roam-file-exclude-regexp nil))
+
+  (it "gets files correctly"
+    (expect (length (org-roam-list-files))
+            :to-equal 3))
+
+  (it "respects org-roam-file-extensions"
+    (setq org-roam-file-extensions '("md"))
+    (expect (length (org-roam-list-files)) :to-equal 1)
+    (setq org-roam-file-extensions '("org" "md"))
+    (expect (length (org-roam-list-files)) :to-equal 4))
+
+  (it "respects org-roam-file-exclude-regexp"
+    (setq org-roam-file-exclude-regexp (regexp-quote "foo.org"))
+    (expect (length (org-roam-list-files)) :to-equal 2)))
+
+(describe "org-roam-db-sync"
+  (before-all
+    (setq org-roam-directory (expand-file-name "tests/roam-files")
+          org-roam-db-location (expand-file-name "org-roam.db" temporary-file-directory)
+          org-roam-file-extensions '("org")
+          org-roam-file-exclude-regexp nil)
+    (org-roam-db-sync))
+
+  (after-all
+    (org-roam-db--close)
+    (delete-file org-roam-db-location))
+
+  (it "has the correct number of files"
+    (expect (caar (org-roam-db-query [:select (funcall count) :from files]))
+            :to-equal
+            3))
+
+  (it "has the correct number of nodes"
+    (expect (caar (org-roam-db-query [:select (funcall count) :from nodes]))
+            :to-equal
+            2))
+
+  (it "has the correct number of links"
+    (expect (caar (org-roam-db-query [:select (funcall count) :from links]))
+            :to-equal
+            1))
+
+  (it "respects ROAM_EXCLUDE"
+    ;; The excluded node has ID "53fadc75-f48e-461e-be06-44a1e88b2abe"
+    (expect (mapcar #'car (org-roam-db-query [:select id :from nodes]))
+            :to-have-same-items-as
+            '("884b2341-b7fe-434d-848c-5282c0727861" "440795d0-70c1-4165-993d-aebd5eef7a24"))))
+
+(provide 'test-org-roam)
+
+;;; test-org-roam.el ends here