(feat): Implement org-roam-flow

When using gpg encrypted files it might happen (intended) that on a
certain machine there is no key to decrypt that file.  Currently an
error of type 'file-error' will be raised and the cache building
process will be aborted.  So in a certain sense org-roam will not
be functional in that case.  Furthermore, when the the cache building
process is run from the emacs initialisation it will come to a halt as
well and the user will be left with a halfworking emacs instance.

This patch changes the behaviour to just skipping over offending files
while removing them from the db at the same time.  Here an offending
file is any file that cannot be read for indexing.  As it stands this
case only works reliably for the case of missing gpg keys.

An error buffer will still show up and be prominently displayed,
besides a log to the message buffer.

Implementation note: This io error will only be caught during the
first part of the cache rebuilding ("files and headlines").  If such
an error would occur during the second part ("rebuild the rest")
another (more severe) cause might be the problem and the user better
be informed the hard way (i.e. the same behaviour as before).

.dir-locals.el

@@ -0,0 +1,6 @@
+;;; Directory Local Variables
+;;; For more information see (info "(emacs) Directory Variables")
+
+((emacs-lisp-mode
+  (eval . (require 'org-roam-dev))
+  (eval . (org-roam-dev-mode))))

.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,69 @@
+# * 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:
+      fail-fast: false
+      matrix:
+        emacs_version:
+          - snapshot
+    steps:
+    - uses: purcell/setup-emacs@master
+      with:
+        version: ${{ matrix.emacs_version }}
+
+    - uses: actions/checkout@v2
+
+    - name: Initialize sandbox
+      run: |
+        SANDBOX_DIR=$(mktemp -d) || exit 1
+        echo ::set-env name=SANDBOX_DIR::$SANDBOX_DIR
+        ./makem.sh -vv --sandbox $SANDBOX_DIR --install-deps --install-linters
+
+    # The "all" rule is not used, because it treats compilation warnings
+    # as failures, so linting and testing are run as separate steps.
+
+    # org-roam-compat is excluded from linting because it contains
+    # symbols/aliases from other packages
+    - name: Lint
+      continue-on-error: false
+      run: ./makem.sh -vv --sandbox $SANDBOX_DIR --exclude org-roam-compat.el lint
+
+    - name: Test
+      if: always()  # Run test even if linting fails.
+      run: ./makem.sh -vv --sandbox $SANDBOX_DIR test
+
+# Local Variables:
+# eval: (outline-minor-mode)
+# End:

.gitignore

@@ -0,0 +1,15 @@
+/.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/

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,269 @@
+# Changelog
+
+## 1.2.2 (TBD)
+
+### Breaking Changes
+
+### Features
+
+- [#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
+
+### Bugfixes
+
+## 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: -->

Makefile

@@ -0,0 +1,70 @@
+# * makem.sh/Makefile --- Script to aid building and testing Emacs Lisp packages
+
+# This Makefile is from the makem.sh repo: <https://github.com/alphapapa/makem.sh>.
+
+# * Arguments
+
+# For consistency, we use only var=val options, not hyphen-prefixed options.
+
+# NOTE: I don't like duplicating the arguments here and in makem.sh,
+# but I haven't been able to find a way to pass arguments which
+# conflict with Make's own arguments through Make to the script.
+# Using -- doesn't seem to do it.
+
+ifdef install-deps
+	INSTALL_DEPS = "--install-deps"
+endif
+ifdef install-linters
+	INSTALL_LINTERS = "--install-linters"
+endif
+
+ifdef sandbox
+	ifeq ($(sandbox), t)
+		SANDBOX = --sandbox
+	else
+		SANDBOX = --sandbox $(sandbox)
+	endif
+endif
+
+ifdef debug
+	DEBUG = "--debug"
+endif
+
+# ** Verbosity
+
+# Since the "-v" in "make -v" gets intercepted by Make itself, we have
+# to use a variable.
+
+verbose = $(v)
+
+ifneq (,$(findstring vv,$(verbose)))
+	VERBOSE = "-vv"
+else ifneq (,$(findstring v,$(verbose)))
+	VERBOSE = "-v"
+endif
+
+# * Rules
+
+# TODO: Handle cases in which "test" or "tests" are called and a
+# directory by that name exists, which can confuse Make.
+
+%:
+	@./makem.sh $(DEBUG) $(VERBOSE) $(SANDBOX) $(INSTALL_DEPS) $(INSTALL_LINTERS) $(@)
+
+.DEFAULT: init
+init:
+	@./makem.sh $(DEBUG) $(VERBOSE) $(SANDBOX) $(INSTALL_DEPS) $(INSTALL_LINTERS)
+
+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,127 @@
-[![Documentation Status](https://readthedocs.org/projects/org-roam/badge/?version=latest)](https://org-roam.readthedocs.io/en/latest/?badge=latest)
+[![License GPL 3][badge-license]](http://www.gnu.org/licenses/gpl-3.0.txt)
+[![GitHub Release](https://img.shields.io/github/v/release/org-roam/org-roam)](https://img.shields.io/github/v/release/org-roam/org-roam)
+[![MELPA](https://melpa.org/packages/org-roam-badge.svg)](https://melpa.org/#/org-roam)
 
-Org-roam is a rudimentary [Roam][roamresearch] replica built around
-the all-powerful [Org-mode][org]. 
+## Synopsis
 
-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. 
+> **NOTE:** Org-roam builds upon Emacs and Org-mode, both of which are intricate
+> tools that require time investment for mastery. This makes Org-roam less
+> friendly for beginners, but extremely powerful for those familiar with the
+> ecosystem, or willing to invest effort in it.
 
-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 is a [Roam][roamresearch] replica built on top of the
+all-powerful [Org-mode][org].
 
-For more documentation, see [the documentation page](https://org-roam.readthedocs.io/en/latest/).
+Org-roam is a solution for effortless non-hierarchical note-taking
+with Org-mode. With Org-roam, notes flow naturally, making note-taking
+fun and easy. Org-roam should also work as a plug-and-play solution
+for anyone already using Org-mode for their personal wiki.
 
-## Understanding Roam
+Org-roam aims to implement the core features of Roam, leveraging the
+mature ecosystem around Org-mode where possible. Eventually, we hope
+to further introduce features enabled by the Emacs ecosystem.
 
-To understand more about Roam, I recommend the following links:
+[@technovangelist](https://github.com/technovangelist/) has produced a video
+describing Org-roam and the concepts behind it:
 
--   [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)
+[![Making Connections in your Notes](http://img.youtube.com/vi/Lg61ocfxk3c/0.jpg)](http://www.youtube.com/watch?v=Lg61ocfxk3c "Making Connections in your Notes")
 
-## Project Status
+Important links:
 
-As of February 2020, it is in a very early stage of development. 
+- **[Documentation][docs]**
+- **[Discourse][discourse]**
+- **[Slack][slack]**
 
 ## A Preview
 
-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.
+Here's a screencast of Org-roam. The `org-roam-buffer` (window on the
+right) shows backlinks for the active Org-roam buffer (window on the
+left), as well as the surrounding content in the backlink file. The
+database is built once, and updated incrementally. The graph is
+generated from the link structure, and can be used to navigate to the
+respective files.
 
 ![img](doc/images/org-roam-graph.gif)
 
-## Knowledge Bases using Org-Roam
+## Installation
+
+You can install `org-roam` using `package.el`:
+
+```
+M-x package-install RET org-roam RET
+```
+
+Here's a sample configuration with using `use-package`:
+
+```emacs-lisp
+(use-package org-roam
+      :ensure t
+      :hook
+      (after-init . org-roam-mode)
+      :custom
+      (org-roam-directory "/path/to/org-files/")
+      :bind (:map org-roam-mode-map
+              (("C-c n l" . org-roam)
+               ("C-c n f" . org-roam-find-file)
+               ("C-c n g" . org-roam-graph-show))
+              :map org-mode-map
+              (("C-c n i" . org-roam-insert))
+              (("C-c n I" . org-roam-insert-immediate))))
+```
+
+`org-roam-graph` by default expects to find the `dot` executable
+from the `graphviz` package in the `exec-path`.
+Ensure `graphviz` is installed and found if you want to use this
+feature or customize your configuration for `org-roam-graph` to use a
+different tool.
+
+For more detailed installation and configuration instructions (including for
+Doom and Spacemacs users), please see [the
+documentation][docs].
+
+## Frequently-asked Questions
+
+Q: How do I create a note whose title already matches one of the candidates (e.g. creating `bar` when `barricade` already exists)?
+
+A: With `ivy`, you need to press `C-M-j` to use the current input instead of the nearest candidate. (Source: [`ivy`’s
+  FAQ](https://github.com/abo-abo/swiper#frequently-asked-questions))
+
+## Getting Help
+
+Before creating a new topic/issue, please be mindful of our time and ensure
+that it has not already been addressed on
+[GitHub][issues] or on
+[Discourse][discourse].
+
+- If you are new to Emacs and have problem setting up Org-roam, please ask your question on [Slack, channel #how-do-i][slack].
+- For quick questions, please ask them on [Slack, channel #troubleshooting][slack].
+- If something is not working as it should, or if you would like to suggest a new feature, please [create a new issue][issues].
+- If you have questions about your workflow with the slip-box method, please find a relevant topic on [Discourse][discourse], or create a new one.
+
+## Knowledge Bases using Org-roam
 
 - [Jethro Kuan](https://braindump.jethro.dev/)
   ([Source](https://github.com/jethrokuan/braindump/tree/master/org))
 
+## Changelog
+
+A changelog is being maintained [here](CHANGELOG.md)
+
 ## 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/
+[badge-license]: https://img.shields.io/badge/license-GPL_3-green.svg
+[docs]: https://www.orgroam.com/manual/
+[discourse]: https://org-roam.discourse.group/
+[slack]: https://join.slack.com/t/orgroam/shared_invite/zt-deoqamys-043YQ~s5Tay3iJ5QRI~Lxg
+[issues]: https://github.com/org-roam/org-roam/issues

default.mk

@@ -0,0 +1,106 @@
+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-buffer.el
+ELS += org-roam-capture.el
+ELS += org-roam-compat.el
+ELS += org-roam-completion.el
+ELS += org-roam-dailies.el
+ELS += org-roam-db.el
+ELS += org-roam.el
+ELS += org-roam-graph.el
+ELS += org-roam-macs.el
+ELS += 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@quelch.name>

doc/Makefile

@@ -0,0 +1,130 @@
+-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: 
+	@printf "Generating org-roam/*.html\n"
+	@$(MAKEINFO) --html $(MANUAL_HTML_ARGS) org-roam.texi
+	mv org-roam manual
+	cp -r assets manual
+	cp -r images manual
+
+%.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,442 @@
+/* Import Inter font */
+/* More info at https://github.com/xz/fonts */
+@import url("https://fonts.xz.style/serve/inter.css");
+
+:root {
+  --nc-font-sans: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
+    Oxygen, Ubuntu, Cantarell, "Open Sans", "Helvetica Neue", sans-serif,
+    "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
+  --nc-font-mono: "Courier New", Courier, "Ubuntu Mono", "Liberation Mono",
+    monospace;
+  --nc-tx-1: #000000;
+  --nc-tx-2: #1a1a1a;
+  --nc-bg-1: #ffffff;
+  --nc-bg-2: #f6f8fa;
+  --nc-bg-3: #e5e7eb;
+  --nc-lk-1: #0070f3;
+  --nc-lk-2: #0366d6;
+  --nc-lk-tx: #ffffff;
+  --nc-ac-1: #79ffe1;
+  --nc-ac-tx: #0c4047;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --nc-tx-1: #ffffff;
+    --nc-tx-2: #eeeeee;
+    --nc-bg-1: #000000;
+    --nc-bg-2: #111111;
+    --nc-bg-3: #222222;
+    --nc-lk-1: #3291ff;
+    --nc-lk-2: #0070f3;
+    --nc-lk-tx: #ffffff;
+    --nc-ac-1: #7928ca;
+    --nc-ac-tx: #ffffff;
+  }
+}
+
+* {
+  /* Reset margins and padding */
+  margin: 0;
+  padding: 0;
+}
+
+address,
+area,
+article,
+aside,
+audio,
+blockquote,
+datalist,
+details,
+dl,
+fieldset,
+figure,
+form,
+input,
+iframe,
+img,
+meter,
+nav,
+ol,
+optgroup,
+option,
+output,
+p,
+pre,
+progress,
+ruby,
+section,
+table,
+textarea,
+ul,
+video {
+  /* Margins for most elements */
+  margin-bottom: 1rem;
+}
+
+html,
+input,
+select,
+button {
+  /* Set body font family and some finicky elements */
+  font-family: var(--nc-font-sans);
+}
+
+body {
+  /* Center body in page */
+  margin: 0 auto;
+  max-width: 750px;
+  padding: 2rem;
+  border-radius: 6px;
+  overflow-x: hidden;
+  background: var(--nc-bg-1);
+
+  /* Main body text */
+  color: var(--nc-tx-2);
+  font-size: 1.03rem;
+  line-height: 1.5;
+}
+
+::selection {
+  /* Set background color for selected text */
+  background: var(--nc-ac-1);
+  color: var(--nc-ac-tx);
+}
+
+p {
+  margin-bottom: 1rem;
+}
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  line-height: 1;
+  color: var(--nc-tx-1);
+  padding-top: 0.875rem;
+}
+
+h1,
+h2,
+h3 {
+  color: var(--nc-tx-1);
+  padding-bottom: 2px;
+  margin-bottom: 8px;
+  border-bottom: 1px solid var(--nc-bg-2);
+}
+
+h4,
+h5,
+h6 {
+  margin-bottom: 0.3rem;
+}
+
+h1 {
+  font-size: 2.25rem;
+}
+
+h2 {
+  font-size: 1.85rem;
+}
+
+h3 {
+  font-size: 1.55rem;
+}
+
+h4 {
+  font-size: 1.25rem;
+}
+
+h5 {
+  font-size: 1rem;
+}
+
+h6 {
+  font-size: 0.875rem;
+}
+
+a {
+  color: var(--nc-lk-1);
+}
+
+a:hover {
+  color: var(--nc-lk-2);
+}
+
+abbr:hover {
+  /* Set the '?' cursor while hovering an abbreviation */
+  cursor: help;
+}
+
+blockquote {
+  padding: 1.5rem;
+  background: var(--nc-bg-2);
+  border-left: 5px solid var(--nc-bg-3);
+}
+
+abbr {
+  cursor: help;
+}
+
+blockquote *:last-child {
+  padding-bottom: 0;
+  margin-bottom: 0;
+}
+
+header {
+  background: var(--nc-bg-2);
+  border-bottom: 1px solid var(--nc-bg-3);
+  padding: 2rem 1.5rem;
+
+  /* This sets the right and left margins to cancel out the body's margins. It's width is still the same, but the background stretches across the page's width. */
+
+  margin: -2rem calc(0px - (50vw - 50%)) 2rem;
+
+  /* Shorthand for:
+
+	margin-top: -2rem;
+	margin-bottom: 2rem;
+
+	margin-left: calc(0px - (50vw - 50%));
+	margin-right: calc(0px - (50vw - 50%)); */
+
+  padding-left: calc(50vw - 50%);
+  padding-right: calc(50vw - 50%);
+}
+
+header h1,
+header h2,
+header h3 {
+  padding-bottom: 0;
+  border-bottom: 0;
+}
+
+header > *:first-child {
+  margin-top: 0;
+  padding-top: 0;
+}
+
+header > *:last-child {
+  margin-bottom: 0;
+}
+
+.button,
+button,
+input[type="submit"],
+input[type="reset"],
+input[type="button"] {
+  font-size: 1rem;
+  display: inline-block;
+  padding: 6px 12px;
+  text-align: center;
+  text-decoration: none;
+  white-space: nowrap;
+  background: var(--nc-lk-1);
+  color: var(--nc-lk-tx);
+  border: 0;
+  border-radius: 4px;
+  box-sizing: border-box;
+  cursor: pointer;
+  color: var(--nc-lk-tx);
+}
+
+.button[disabled],
+button[disabled],
+input[type="submit"][disabled],
+input[type="reset"][disabled],
+input[type="button"][disabled] {
+  cursor: default;
+  opacity: 0.5;
+
+  /* Set the [X] cursor while hovering a disabled link */
+  cursor: not-allowed;
+}
+
+.button:focus,
+.button:hover,
+button:focus,
+button:hover,
+input[type="submit"]:focus,
+input[type="submit"]:hover,
+input[type="reset"]:focus,
+input[type="reset"]:hover,
+input[type="button"]:focus,
+input[type="button"]:hover {
+  background: var(--nc-lk-2);
+}
+
+code,
+pre,
+kbd,
+samp {
+  /* Set the font family for monospaced elements */
+  font-family: var(--nc-font-mono);
+}
+
+code,
+samp,
+kbd,
+pre {
+  /* The main preformatted style. This is changed slightly across different cases. */
+  background: var(--nc-bg-2);
+  border: 1px solid var(--nc-bg-3);
+  border-radius: 4px;
+  padding: 3px 6px;
+  font-size: 0.9rem;
+}
+
+kbd {
+  /* Makes the kbd element look like a keyboard key */
+  border-bottom: 3px solid var(--nc-bg-3);
+}
+
+pre {
+  padding: 1rem 1.4rem;
+  max-width: 100%;
+  overflow: auto;
+}
+
+pre code {
+  /* When <code> is in a <pre>, reset it's formatting to blend in */
+  background: inherit;
+  font-size: inherit;
+  color: inherit;
+  border: 0;
+  padding: 0;
+  margin: 0;
+}
+
+code pre {
+  /* When <pre> is in a <code>, reset it's formatting to blend in */
+  display: inline;
+  background: inherit;
+  font-size: inherit;
+  color: inherit;
+  border: 0;
+  padding: 0;
+  margin: 0;
+}
+
+details {
+  /* Make the <details> look more "clickable" */
+  padding: 0.6rem 1rem;
+  background: var(--nc-bg-2);
+  border: 1px solid var(--nc-bg-3);
+  border-radius: 4px;
+}
+
+summary {
+  /* Makes the <summary> look more like a "clickable" link with the pointer cursor */
+  cursor: pointer;
+  font-weight: bold;
+}
+
+details[open] {
+  /* Adjust the <details> padding while open */
+  padding-bottom: 0.75rem;
+}
+
+details[open] summary {
+  /* Adjust the <details> padding while open */
+  margin-bottom: 6px;
+}
+
+details[open] > *:last-child {
+  /* Resets the bottom margin of the last element in the <details> while <details> is opened. This prevents double margins/paddings. */
+  margin-bottom: 0;
+}
+
+dt {
+  font-weight: bold;
+}
+
+dd::before {
+  /* Add an arrow to data table definitions */
+  content: "→ ";
+}
+
+hr {
+  /* Reset the border of the <hr> separator, then set a better line */
+  border: 0;
+  border-bottom: 1px solid var(--nc-bg-3);
+  margin: 1rem auto;
+}
+
+fieldset {
+  margin-top: 1rem;
+  padding: 2rem;
+  border: 1px solid var(--nc-bg-3);
+  border-radius: 4px;
+}
+
+legend {
+  padding: auto 0.5rem;
+}
+
+textarea {
+  /* Don't let the <textarea> extend off the screen naturally or when dragged by the user */
+  max-width: 100%;
+}
+
+ol,
+ul {
+  /* Replace the browser default padding */
+  padding-left: 2rem;
+}
+
+li {
+  margin-top: 0.4rem;
+}
+
+ul ul,
+ol ul,
+ul ol,
+ol ol {
+  margin-bottom: 0;
+}
+
+mark {
+  padding: 3px 6px;
+  background: var(--nc-ac-1);
+  color: var(--nc-ac-tx);
+}
+
+textarea,
+select,
+input {
+  padding: 6px 12px;
+  margin-bottom: 0.5rem;
+  background: var(--nc-bg-2);
+  color: var(--nc-tx-2);
+
+  /* Set a border of the same color as the main background. It isn't visible on idle, but prevents the cell from growing in size when a darker border is set on focus. */
+  border: 1px solid var(--nc-bg-2);
+  border-radius: 4px;
+  box-shadow: none;
+  box-sizing: border-box;
+}
+
+textarea:focus,
+select:focus,
+input[type]:focus {
+  border: 1px solid var(--nc-bg-3);
+
+  /* Reset any browser default outlines */
+  outline: 0;
+}
+
+img {
+  max-width: 100%;
+}
+
+/* Customizations */
+.menu-comment {
+  font-weight: bold;
+  border: 0;
+  margin: 0;
+  padding: 0;
+  font-size: 1.2rem;
+}

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,175 @@
+<!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/">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 class="row">
+          <a
+            class="content footer-links"
+            href="https://github.com/org-roam/company-org-roam"
+            >company-org-roam</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)

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-buffer.el

@@ -0,0 +1,302 @@
+;;; org-roam-buffer.el --- Metadata buffer -*- coding: utf-8; lexical-binding: t; -*-
+
+;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
+
+;; Author: Jethro Kuan <jethrokuan95@gmail.com>
+;; URL: https://github.com/org-roam/org-roam
+;; Keywords: org-mode, roam, convenience
+;; Version: 1.2.1
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.0"))
+
+;; 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 the org-roam-buffer functionality for org-roam
+;;; Code:
+;;;; Library Requires
+(eval-when-compile (require 'subr-x))
+(require 'cl-lib)
+(require 'dash)
+(require 's)
+
+(defvar org-roam-directory)
+(defvar org-link-frame-setup)
+(defvar org-return-follows-link)
+(defvar org-roam-backlinks-mode)
+(defvar org-roam-last-window)
+(defvar org-ref-cite-types) ;; in org-ref-core.el
+(defvar org-roam-mode)
+
+(declare-function org-roam-db--ensure-built   "org-roam-db")
+(declare-function org-roam--extract-ref       "org-roam")
+(declare-function org-roam--get-title-or-slug "org-roam")
+(declare-function org-roam--get-backlinks     "org-roam")
+(declare-function org-roam-backlinks-mode     "org-roam")
+(declare-function org-roam-mode               "org-roam")
+(declare-function org-roam--find-file         "org-roam")
+
+(defcustom org-roam-buffer-position 'right
+  "Position of `org-roam' buffer.
+Valid values are
+ * left,
+ * right,
+ * top,
+ * bottom."
+  :type '(choice (const left)
+                 (const right)
+                 (const top)
+                 (const bottom))
+  :group 'org-roam)
+
+(defcustom org-roam-buffer-width 0.33
+  "Width of `org-roam' buffer.
+Has an effect if and only if `org-roam-buffer-position' is `left' or `right'."
+  :type 'number
+  :group 'org-roam)
+
+(defcustom org-roam-buffer-height 0.27
+  "Height of `org-roam' buffer.
+Has an effect if and only if `org-roam-buffer-position' is `top' or `bottom'."
+  :type 'number
+  :group 'org-roam)
+
+
+(defcustom org-roam-buffer "*org-roam*"
+  "Org-roam buffer name."
+  :type 'string
+  :group 'org-roam)
+
+(defcustom org-roam-buffer-prepare-hook '(org-roam-buffer--insert-title
+                                          org-roam-buffer--insert-backlinks
+                                          org-roam-buffer--insert-ref-links)
+  "Hook run in the `org-roam-buffer' before it is displayed."
+  :type 'hook
+  :group 'org-roam)
+
+(defcustom org-roam-buffer-window-parameters nil
+  "Additional window parameters for the `org-roam-buffer' side window.
+For example: (setq org-roam-buffer-window-parameters '((no-other-window . t)))"
+  :type '(alist)
+  :group 'org-roam)
+
+(defvar org-roam-buffer--current nil
+  "Currently displayed file in `org-roam' buffer.")
+
+(defun org-roam-buffer--find-file (file)
+  "Open FILE in the window `org-roam' was called from."
+  (if (and org-roam-last-window (window-valid-p org-roam-last-window))
+      (progn (with-selected-window org-roam-last-window
+               (org-roam--find-file file))
+             (select-window org-roam-last-window))
+    (org-roam--find-file file)))
+
+(defun org-roam-buffer--insert-title ()
+  "Insert the org-roam-buffer title."
+  (insert (propertize (org-roam--get-title-or-slug
+                       (buffer-file-name org-roam-buffer--current))
+                       'font-lock-face
+                       'org-document-title)))
+
+(defun org-roam-buffer--pluralize (string number)
+  "Conditionally pluralize STRING if NUMBER is above 1."
+  (let ((l (pcase number
+             ((pred (listp)) (length number))
+             ((pred (integerp)) number)
+             (wrong-type (signal 'wrong-type-argument
+                                 `((listp integerp)
+                                   ,wrong-type))))))
+    (concat string (when (> l 1) "s"))))
+
+(defun org-roam-buffer--insert-ref-links ()
+  "Insert ref backlinks for the current buffer."
+  (when-let ((ref (cdr (with-temp-buffer
+                        (insert-buffer-substring org-roam-buffer--current)
+                        (org-roam--extract-ref)))))
+    (if-let* ((key-backlinks (org-roam--get-backlinks ref))
+              (grouped-backlinks (--group-by (nth 0 it) key-backlinks)))
+        (progn
+          (insert (let ((l (length key-backlinks)))
+                    (format "\n\n* %d %s\n"
+                            l (org-roam-buffer--pluralize "Ref Backlink" l))))
+          (dolist (group grouped-backlinks)
+            (let ((file-from (car group))
+                  (bls (cdr group)))
+              (insert (format "** [[file:%s][%s]]\n"
+                              file-from
+                              (org-roam--get-title-or-slug file-from)))
+              (dolist (backlink bls)
+                (pcase-let ((`(,file-from _ ,props) backlink))
+                  (insert (propertize (plist-get props :content)
+                           'help-echo "mouse-1: visit backlinked note"
+                           'file-from file-from
+                           'file-from-point (plist-get props :point)))
+                  (insert "\n\n"))))))
+      (insert "\n\n* No ref backlinks!"))))
+
+(defun org-roam-buffer--insert-backlinks ()
+  "Insert the org-roam-buffer backlinks string for the current buffer."
+  (if-let* ((file-path (buffer-file-name org-roam-buffer--current))
+            (backlinks (org-roam--get-backlinks file-path))
+            (grouped-backlinks (--group-by (nth 0 it) backlinks)))
+      (progn
+        (insert (let ((l (length backlinks)))
+                     (format "\n\n* %d %s\n"
+                             l (org-roam-buffer--pluralize "Backlink" l))))
+        (dolist (group grouped-backlinks)
+          (let ((file-from (car group))
+                (bls (cdr group)))
+            (insert (format "** [[file:%s][%s]]\n"
+                            file-from
+                            (org-roam--get-title-or-slug file-from)))
+            (dolist (backlink bls)
+              (pcase-let ((`(,file-from _ ,props) backlink))
+                (insert "*** "
+                        (if-let ((outline (plist-get props :outline)))
+                            (string-join outline " > ")
+                          "Top")
+                        "\n"
+                        (propertize
+                         (s-trim (s-replace "\n" " "
+                                            (plist-get props :content)))
+                         'help-echo "mouse-1: visit backlinked note"
+                         'file-from file-from
+                         'file-from-point (plist-get props :point))
+                        "\n\n"))))))
+    (insert "\n\n* No backlinks!")))
+
+(defun org-roam-buffer-update ()
+  "Update the `org-roam-buffer'."
+  (org-roam-db--ensure-built)
+  (let* ((source-org-roam-directory org-roam-directory))
+    (with-current-buffer org-roam-buffer
+      ;; When dir-locals.el is used to override org-roam-directory,
+      ;; org-roam-buffer should have a different local org-roam-directory and
+      ;; default-directory, as relative links are relative from the overridden
+      ;; org-roam-directory.
+      (setq-local org-roam-directory source-org-roam-directory)
+      (setq-local default-directory source-org-roam-directory)
+      ;; Locally overwrite the file opening function to re-use the
+      ;; last window org-roam was called from
+      (setq-local org-link-frame-setup
+                  (cons '(file . org-roam--find-file) org-link-frame-setup))
+      (let ((inhibit-read-only t))
+        (erase-buffer)
+        (unless (eq major-mode 'org-mode)
+          (org-mode))
+        (unless org-roam-backlinks-mode
+          (org-roam-backlinks-mode))
+        (make-local-variable 'org-return-follows-link)
+        (setq org-return-follows-link t)
+        (run-hooks 'org-roam-buffer-prepare-hook)
+        (read-only-mode 1)))))
+
+
+(cl-defun org-roam-buffer--update-maybe (&key redisplay)
+  "Reconstructs `org-roam-buffer'.
+This needs to be quick or infrequent, because this is run at
+`post-command-hook'.  If REDISPLAY, force an update of
+`org-roam-buffer'."
+  (let ((buffer (window-buffer)))
+    (when (and (or redisplay
+                   (not (eq org-roam-buffer--current buffer)))
+               (eq 'visible (org-roam-buffer--visibility))
+               (buffer-local-value 'buffer-file-truename buffer))
+      (setq org-roam-buffer--current buffer)
+      (org-roam-buffer-update))))
+
+;;;; Toggling the org-roam buffer
+(define-inline org-roam-buffer--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-buffer--set-width (width)
+  "Set the width of `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-buffer--set-height (height)
+  "Set the height of `org-roam-buffer' to `HEIGHT'."
+  (unless (one-window-p)
+    (let ((window-size-fixed)
+          (h (max height window-min-height)))
+      (cond
+       ((> (window-height) h)
+        (shrink-window  (- (window-height) h)))
+       ((< (window-height) h)
+        (enlarge-window (- h (window-height))))))))
+
+(defun org-roam-buffer--get-create ()
+  "Set up the `org-roam' buffer at `org-roam-buffer-position'."
+  (let ((position
+         (if (member org-roam-buffer-position '(right left top bottom))
+             org-roam-buffer-position
+           (let ((text-quoting-style 'grave))
+             (lwarn '(org-roam) :error
+                    "Invalid org-roam-buffer-position: %s. Defaulting to \\='right"
+                    org-roam-buffer-position))
+           'right)))
+    (save-selected-window
+      (-> (get-buffer-create org-roam-buffer)
+          (display-buffer-in-side-window
+           `((side . ,position)
+             (window-parameters . ,org-roam-buffer-window-parameters)))
+          (select-window))
+      (pcase position
+        ((or 'right 'left)
+         (org-roam-buffer--set-width
+          (round (* (frame-width)  org-roam-buffer-width))))
+        ((or 'top  'bottom)
+         (org-roam-buffer--set-height
+          (round (* (frame-height) org-roam-buffer-height))))))))
+
+(defun org-roam-buffer-activate ()
+  "Activate display of the `org-roam-buffer'."
+  (interactive)
+  (unless org-roam-mode (org-roam-mode))
+  (setq org-roam-last-window (get-buffer-window))
+  (org-roam-buffer--get-create))
+
+(defun org-roam-buffer-deactivate ()
+  "Deactivate display of the `org-roam-buffer'."
+  (interactive)
+  (setq org-roam-last-window (get-buffer-window))
+  (delete-window (get-buffer-window org-roam-buffer)))
+
+(defun org-roam-buffer-toggle-display ()
+  "Toggle display of the `org-roam-buffer'."
+  (interactive)
+  (pcase (org-roam-buffer--visibility)
+    ('visible (org-roam-buffer-deactivate))
+    ((or 'exists 'none) (org-roam-buffer-activate))))
+
+(provide 'org-roam-buffer)
+
+;;; org-roam-buffer.el ends here

org-roam-capture.el

@@ -0,0 +1,550 @@
+;;; org-roam-capture.el --- Capture functionality -*- coding: utf-8; lexical-binding: t; -*-
+
+;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
+
+;; Author: Jethro Kuan <jethrokuan95@gmail.com>
+;; URL: https://github.com/org-roam/org-roam
+;; Keywords: org-mode, roam, convenience
+;; Version: 1.2.1
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.0"))
+
+;; 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 capture functionality for org-roam
+;;; Code:
+;;;; Library Requires
+(require 'org-capture)
+(require 'org-roam-macs)
+(require 'dash)
+(require 's)
+(require 'cl-lib)
+
+;; Declarations
+(defvar org-roam-encrypt-files)
+(defvar org-roam-directory)
+(defvar org-roam-mode)
+(defvar org-roam-title-to-slug-function)
+(declare-function  org-roam--get-title-path-completions "org-roam")
+(declare-function  org-roam--get-ref-path-completions   "org-roam")
+(declare-function  org-roam--file-path-from-id          "org-roam")
+(declare-function  org-roam--find-file                  "org-roam")
+(declare-function  org-roam--format-link                "org-roam")
+(declare-function  org-roam-mode                        "org-roam")
+(declare-function  org-roam-completion--completing-read "org-roam-completion")
+
+(defvar org-roam-capture--file-name-default "%<%Y%m%d%H%M%S>"
+  "The default file name format for Org-roam templates.")
+
+(defvar org-roam-capture--header-default "#+title: ${title}\n"
+  "The default capture header for Org-roam templates.")
+
+(defvar org-roam-capture--file-path nil
+  "The file path for the Org-roam capture.
+This variable is set during the Org-roam capture process.")
+
+(defvar org-roam-capture--info nil
+  "An alist 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.")
+
+(defvar org-roam-capture--context nil
+  "A symbol, that reflects the context for obtaining the exact point in a file.
+This variable is populated dynamically, and is only active during
+an Org-roam capture process.
+
+The `title' context is used in `org-roam-insert' and
+`org-roam-find-file', where the capture process is triggered upon
+trying to create a new file without that `title'.
+
+The `ref' context is used by `org-roam-protocol', where the
+capture process is triggered upon trying to find or create a new
+note with the given `ref'.")
+
+(defvar org-roam-capture-additional-template-props nil
+  "Additional props to be added to the Org-roam template.")
+
+(defconst org-roam-capture--template-keywords '(:file-name :head)
+  "Keywords used in `org-roam-capture-templates' specific to Org-roam.")
+
+(defcustom org-roam-capture-templates
+  '(("d" "default" plain (function org-roam-capture--get-point)
+     "%?"
+     :file-name "%<%Y%m%d%H%M%S>-${slug}"
+     :head "#+title: ${title}\n"
+     :unnarrowed t))
+  "Capture templates for Org-roam.
+The Org-roam capture-templates  builds on the default behaviours of
+`org-capture-templates' by expanding them in 3 areas:
+
+1. Template-expansion capabilities are extended with additional
+   custom syntax. See `org-roam-capture--fill-template' for more
+   details.
+
+2. The `:file-name' key is added, which defines the naming format
+   to use when creating new notes. This file-name is relative to
+   `org-roam-directory', and is without the file-extension.
+
+3. The `:head' key is added, which contains the template that is
+   inserted upon the creation of a new file. This is where you
+   your note metadata should go.
+
+Each template should have the following structure:
+
+\(KEY DESCRIPTION `plain' `(function org-roam-capture--get-point)'
+  TEMPLATE
+  `:file-name' FILENAME-FORMAT
+  `:head' HEADER-FORMAT
+  `:unnarrowed t'
+  OPTIONS-PLIST)
+
+The elements of a template-entry and their placement are the same
+as in `org-capture-templates', except that the entry type must
+always be the symbol `plain', and that the target must always be
+the list `(function org-roam-capture--get-point)'.
+
+Org-roam requires the plist elements `:file-name' and `:head' to
+be present, and it’s recommended that `:unnarrowed' be set to t."
+  :group 'org-roam
+  ;; Adapted from `org-capture-templates'
+  :type
+  '(repeat
+    (choice :value ("d" "default" plain (function org-roam-capture--get-point)
+                    "%?"
+                    :file-name "%<%Y%m%d%H%M%S>-${slug}"
+                    :head "#+title: ${title}\n"
+                    :unnarrowed t)
+            (list :tag "Multikey description"
+                  (string :tag "Keys       ")
+                  (string :tag "Description"))
+            (list :tag "Template entry"
+                  (string :tag "Keys              ")
+                  (string :tag "Description       ")
+                  (const :format "" plain)
+                  (const :format "" (function org-roam-capture--get-point))
+                  (choice :tag "Template          "
+                          (string :tag "String"
+                                  :format "String:\n            \
+Template string   :\n%v")
+                          (list :tag "File"
+                                (const :format "" file)
+                                (file :tag "Template file     "))
+                          (list :tag "Function"
+                                (const :format "" function)
+                                (function :tag "Template function ")))
+                  (const :format "File name format  :" :file-name)
+                  (string :format " %v" :value "#+title: ${title}\n")
+                  (const :format "Header format     :" :head)
+                  (string :format "\n%v" :value "%<%Y%m%d%H%M%S>-${slug}")
+                  (const :format "" :unnarrowed) (const :format "" t)
+                  (plist :inline t
+                         :tag "Options"
+                         ;; Give the most common options as checkboxes
+                         :options
+                         (((const :format "%v " :prepend) (const t))
+                          ((const :format "%v " :immediate-finish) (const t))
+                          ((const :format "%v " :jump-to-captured) (const t))
+                          ((const :format "%v " :empty-lines) (const 1))
+                          ((const :format "%v " :empty-lines-before) (const 1))
+                          ((const :format "%v " :empty-lines-after) (const 1))
+                          ((const :format "%v " :clock-in) (const t))
+                          ((const :format "%v " :clock-keep) (const t))
+                          ((const :format "%v " :clock-resume) (const t))
+                          ((const :format "%v " :time-prompt) (const t))
+                          ((const :format "%v " :tree-type) (const week))
+                          ((const :format "%v " :table-line-pos) (string))
+                          ((const :format "%v " :kill-buffer) (const t))))))))
+
+(defcustom org-roam-capture-immediate-template
+  (append (car org-roam-capture-templates) '(:immediate-finish t))
+  "Capture template to use for immediate captures in Org-roam.
+This is a single template, so do not enclose it into a list.
+See `org-roam-capture-templates' for details on templates."
+  :group 'org-roam
+  ;; Adapted from `org-capture-templates'
+  :type
+  '(list :tag "Template entry"
+         :value ("d" "default" plain (function org-roam-capture--get-point)
+                 "%?"
+                 :file-name "%<%Y%m%d%H%M%S>-${slug}"
+                 :head "#+title: ${title}\n"
+                 :unnarrowed t
+                 :immediate-finish t)
+         (string :tag "Keys              ")
+         (string :tag "Description       ")
+         (const :format "" plain)
+         (const :format "" (function org-roam-capture--get-point))
+         (choice :tag "Template          "
+                 (string :tag "String"
+                         :format "String:\n            \
+Template string   :\n%v")
+                 (list :tag "File"
+                       (const :format "" file)
+                       (file :tag "Template file     "))
+                 (list :tag "Function"
+                       (const :format "" function)
+                       (function :tag "Template function ")))
+         (const :format "File name format  :" :file-name)
+         (string :format " %v" :value "#+title: ${title}\n")
+         (const :format "Header format     :" :head)
+         (string :format "\n%v" :value "%<%Y%m%d%H%M%S>-${slug}")
+         (const :format "" :unnarrowed) (const :format "" t)
+         (const :format "" :immediate-finish) (const :format "" t)
+         (plist :inline t
+                :tag "Options"
+                ;; Give the most common options as checkboxes
+                :options
+                (((const :format "%v " :prepend) (const t))
+                 ((const :format "%v " :jump-to-captured) (const t))
+                 ((const :format "%v " :empty-lines) (const 1))
+                 ((const :format "%v " :empty-lines-before) (const 1))
+                 ((const :format "%v " :empty-lines-after) (const 1))
+                 ((const :format "%v " :clock-in) (const t))
+                 ((const :format "%v " :clock-keep) (const t))
+                 ((const :format "%v " :clock-resume) (const t))
+                 ((const :format "%v " :time-prompt) (const t))
+                 ((const :format "%v " :tree-type) (const week))
+                 ((const :format "%v " :table-line-pos) (string))
+                 ((const :format "%v " :kill-buffer) (const t))))))
+
+(defcustom org-roam-capture-ref-templates
+  '(("r" "ref" plain (function org-roam-capture--get-point)
+     "%?"
+     :file-name "${slug}"
+     :head "#+title: ${title}\n#+roam_key: ${ref}\n"
+     :unnarrowed t))
+  "The Org-roam templates used during a capture from the roam-ref protocol.
+Details on how to specify for the template is given in `org-roam-capture-templates'."
+  :group 'org-roam
+  ;; Adapted from `org-capture-templates'
+  :type
+  '(repeat
+    (choice :value ("d" "default" plain (function org-roam-capture--get-point)
+                    "%?"
+                    :file-name "${slug}"
+                    :head "#+title: ${title}\n#+roam_key: ${ref}\n"
+                    :unnarrowed t)
+            (list :tag "Multikey description"
+                  (string :tag "Keys       ")
+                  (string :tag "Description"))
+            (list :tag "Template entry"
+                  (string :tag "Keys              ")
+                  (string :tag "Description       ")
+                  (const :format "" plain)
+                  (const :format "" (function org-roam-capture--get-point))
+                  (choice :tag "Template          "
+                          (string :tag "String"
+                                  :format "String:\n            \
+Template string   :\n%v")
+                          (list :tag "File"
+                                (const :format "" file)
+                                (file :tag "Template file     "))
+                          (list :tag "Function"
+                                (const :format "" function)
+                                (function :tag "Template function ")))
+                  (const :format "File name format  :" :file-name)
+                  (string :format " %v" :value "#+title: ${title}\n")
+                  (const :format "Header format     :" :head)
+                  (string :format "\n%v" :value "%<%Y%m%d%H%M%S>-${slug}")
+                  (const :format "" :unnarrowed) (const :format "" t)
+                  (plist :inline t
+                         :tag "Options"
+                         ;; Give the most common options as checkboxes
+                         :options
+                         (((const :format "%v " :prepend) (const t))
+                          ((const :format "%v " :immediate-finish) (const t))
+                          ((const :format "%v " :jump-to-captured) (const t))
+                          ((const :format "%v " :empty-lines) (const 1))
+                          ((const :format "%v " :empty-lines-before) (const 1))
+                          ((const :format "%v " :empty-lines-after) (const 1))
+                          ((const :format "%v " :clock-in) (const t))
+                          ((const :format "%v " :clock-keep) (const t))
+                          ((const :format "%v " :clock-resume) (const t))
+                          ((const :format "%v " :time-prompt) (const t))
+                          ((const :format "%v " :tree-type) (const week))
+                          ((const :format "%v " :table-line-pos) (string))
+                          ((const :format "%v " :kill-buffer) (const t))))))))
+
+(defun org-roam-capture-p ()
+  "Return t if the current capture process is an Org-roam capture.
+This function is to only be called when org-capture-plist is
+valid for the capture (i.e. initialization, and finalization of
+the capture)."
+  (plist-get org-capture-plist :org-roam))
+
+(defun org-roam-capture--get (keyword)
+  "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))))
+
+;; FIXME: Pending upstream patch
+;; https://orgmode.org/list/87h7tv9pkm.fsf@hidden/T/#u
+;;
+;; Org-capture's behaviour right now is that `org-capture-plist' is valid only
+;; during the initialization of the Org-capture buffer. The value of
+;; `org-capture-plist' is saved into buffer-local `org-capture-current-plist'.
+;; However, the value for that particular capture is no longer accessible for
+;; hooks in `org-capture-after-finalize-hook', since the capture buffer has been
+;; cleaned up.
+;;
+;; This advice restores the global `org-capture-plist' during finalization, so
+;; the plist is valid during both initialization and finalization of the
+;; capture.
+(defun org-roam-capture--update-plist (&optional _)
+  "Update global plist from local var."
+  (setq org-capture-plist org-capture-current-plist))
+
+(advice-add 'org-capture-finalize :before #'org-roam-capture--update-plist)
+
+(defun org-roam-capture--finalize ()
+  "Finalize the `org-roam-capture' process."
+  (let* ((finalize (org-roam-capture--get :finalize))
+         ;; In case any regions were shielded before, unshield them
+         (region (when-let ((region (org-roam-capture--get :region)))
+                   (org-roam-unshield-region (car region) (cdr region))))
+         (beg (car region))
+         (end (cdr region)))
+    (unless org-note-abort
+      (pcase finalize
+        ('find-file
+         (when-let ((file-path (org-roam-capture--get :file-path)))
+           (org-roam--find-file file-path)
+           (run-hooks 'org-roam-capture-after-find-file-hook)))
+        ('insert-link
+         (when-let* ((mkr (org-roam-capture--get :insert-at))
+                     (buf (marker-buffer mkr)))
+           (with-current-buffer buf
+             (when region
+               (delete-region (car region) (cdr region)))
+             (let ((path (org-roam-capture--get :file-path))
+                   (desc (org-roam-capture--get :link-description)))
+               (if (eq (point) (marker-position mkr))
+                   (insert (org-roam--format-link path desc))
+                 (org-with-point-at mkr
+                   (insert (org-roam--format-link path desc))))))))))
+    (when region
+      (set-marker beg nil)
+      (set-marker end nil))
+    (org-roam-capture--save-file-maybe)
+    (remove-hook 'org-capture-after-finalize-hook #'org-roam-capture--finalize)))
+
+(defun org-roam-capture--install-finalize ()
+  "Install `org-roam-capture--finalize' if the capture is an Org-roam capture."
+  (when (org-roam-capture-p)
+    (add-hook 'org-capture-after-finalize-hook #'org-roam-capture--finalize)))
+
+(add-hook 'org-capture-prepare-finalize-hook #'org-roam-capture--install-finalize)
+
+(defun org-roam-capture--fill-template (str)
+  "Expand the template STR, returning the string.
+This is an extension of org-capture's template expansion.
+
+First, it expands ${var} occurrences in STR, using `org-roam-capture--info'.
+If there is a ${var} with no matching var in the alist, the value
+of var is prompted for via `completing-read'.
+
+Next, it expands the remaining template string using
+`org-capture-fill-template'."
+  (-> str
+      (s-format (lambda (key)
+                  (or (s--aget org-roam-capture--info key)
+                      (when-let ((val (completing-read (format "%s: " key) nil)))
+                        (push (cons key val) org-roam-capture--info)
+                        val))) nil)
+      (org-capture-fill-template)))
+
+(defun org-roam-capture--save-file-maybe ()
+  "Save the file conditionally.
+The file is saved if the original value of :no-save is not t and
+`org-note-abort' is not t. It is added to
+`org-capture-after-finalize-hook'."
+  (cond
+   ((and (org-roam-capture--get :new-file)
+         org-note-abort)
+    (with-current-buffer (org-capture-get :buffer)
+      (set-buffer-modified-p nil)
+      (kill-buffer)))
+   ((and (not (org-roam-capture--get :orig-no-save))
+         (not org-note-abort))
+    (with-current-buffer (org-capture-get :buffer)
+      (save-buffer)))))
+
+(defun org-roam-capture--new-file ()
+  "Return the path to the new file during an Org-roam capture.
+
+This function reads the file-name attribute of the currently
+active Org-roam template.
+
+If the file path already exists, it throw an error.
+
+Else, to insert the header content in the file, `org-capture'
+prepends the `:head' property of the Org-roam capture template.
+
+To prevent the creation of a new file if the capture process is
+aborted, we do the following:
+
+1. Save the original value of the capture template's :no-save.
+
+2. Set the capture template's :no-save to t.
+
+3. Add a function on `org-capture-before-finalize-hook' that saves
+the file if the original value of :no-save is not t and
+`org-note-abort' is not t."
+  (let* ((name-templ (or (org-roam-capture--get :file-name)
+                         org-roam-capture--file-name-default))
+         (new-id (s-trim (org-roam-capture--fill-template
+                          name-templ)))
+         (file-path (org-roam--file-path-from-id new-id))
+         (roam-head (or (org-roam-capture--get :head)
+                        org-roam-capture--header-default))
+         (org-template (org-capture-get :template))
+         (roam-template (concat roam-head org-template)))
+    (unless (file-exists-p file-path)
+      (make-directory (file-name-directory file-path) t)
+      (org-roam-capture--put :orig-no-save (org-capture-get :no-save)
+                             :new-file t)
+      (org-capture-put :template
+                       ;; Fixes org-capture-place-plain-text throwing 'invalid search bound'
+                       ;; when both :unnarowed t and "%?" is missing from the template string;
+                       ;; may become unnecessary when the upstream bug is fixed
+                       (if (s-contains-p "%?" roam-template)
+                           roam-template
+                         (concat roam-template "%?"))
+                       :type 'plain
+                       :no-save t))
+    file-path))
+
+(defun org-roam-capture--get-point ()
+  "Return exact point to file for org-capture-template.
+The file to use is dependent on the context:
+
+If the search is via title, it is assumed that the file does not
+yet exist, and Org-roam will attempt to create new file.
+
+If the search is via daily notes, 'time will be passed via
+`org-roam-capture--info'. This is used to alter the default time
+in `org-capture-templates'.
+
+If the search is via ref, it is matched against the Org-roam database.
+If there is no file with that ref, a file with that ref is created.
+
+This function is used solely in Org-roam's capture templates: see
+`org-roam-capture-templates'."
+  (let ((file-path (pcase org-roam-capture--context
+                     ('capture
+                      (or (cdr (assoc 'file org-roam-capture--info))
+                          (org-roam-capture--new-file)))
+                     ('title
+                      (org-roam-capture--new-file))
+                     ('dailies
+                      (org-capture-put :default-time (cdr (assoc 'time org-roam-capture--info)))
+                      (org-roam-capture--new-file))
+                     ('ref
+                      (let ((completions (org-roam--get-ref-path-completions))
+                            (ref (cdr (assoc 'ref org-roam-capture--info))))
+                        (if-let ((pl (cdr (assoc ref completions))))
+                            (plist-get pl :path)
+                          (org-roam-capture--new-file))))
+                     (_ (error "Invalid org-roam-capture-context")))))
+    (org-capture-put :template
+                     (org-roam-capture--fill-template (org-capture-get :template)))
+    (org-roam-capture--put :file-path file-path)
+    (while org-roam-capture-additional-template-props
+      (let ((prop (pop org-roam-capture-additional-template-props))
+            (val (pop org-roam-capture-additional-template-props)))
+        (org-roam-capture--put prop val)))
+    (set-buffer (org-capture-target-buffer file-path))
+    (widen)
+    (goto-char (point-max))))
+
+(defun org-roam-capture--convert-template (template)
+  "Convert TEMPLATE from Org-roam syntax to `org-capture-templates' syntax."
+  (pcase template
+    (`(,_key ,_description) template)
+    (`(,key ,description ,type ,target . ,rest)
+     (let ((converted `(,key ,description ,type ,target
+                             ,(unless (keywordp (car rest)) (pop rest))))
+           org-roam-plist
+           options)
+       (while rest
+         (let* ((key (pop rest))
+                (val (pop rest))
+                (custom (member key org-roam-capture--template-keywords)))
+           (push val (if custom org-roam-plist options))
+           (push key (if custom org-roam-plist options))))
+       (append converted options `(:org-roam ,org-roam-plist))))
+    (_ (user-error "Invalid capture template format: %s" template))))
+
+(defcustom org-roam-capture-after-find-file-hook nil
+  "Hook that is run right after an Org-roam capture process is finalized.
+Suitable for moving point."
+  :group 'org-roam
+  :type 'hook)
+
+(defcustom org-roam-capture-function #'org-capture
+  "Function that is invoked to start the `org-capture' process."
+  :group 'org-roam
+  :type 'function)
+
+(defun org-roam-capture--capture (&optional goto keys)
+  "Create a new file, and return the path to the edited file.
+The templates are defined at `org-roam-capture-templates'.  The
+GOTO and KEYS argument have the same functionality as
+`org-capture'."
+  (let* ((org-capture-templates (mapcar #'org-roam-capture--convert-template org-roam-capture-templates))
+         (one-template-p (= (length org-capture-templates) 1))
+         org-capture-templates-contexts)
+    (when one-template-p
+      (setq keys (caar org-capture-templates)))
+    (if (or one-template-p
+            (eq org-roam-capture-function 'org-capture))
+        (org-capture goto keys)
+      (funcall-interactively org-roam-capture-function))))
+
+;;;###autoload
+(defun org-roam-capture ()
+  "Launches an `org-capture' process for a new or existing note.
+This uses the templates defined at `org-roam-capture-templates'."
+  (interactive)
+  (unless org-roam-mode (org-roam-mode))
+  (let* ((completions (org-roam--get-title-path-completions))
+         (title-with-keys (org-roam-completion--completing-read "File: "
+                                                                completions))
+         (res (cdr (assoc title-with-keys completions)))
+         (title (or (plist-get res :title) title-with-keys))
+         (file-path (plist-get res :path)))
+    (let ((org-roam-capture--info (list (cons 'title title)
+                                        (cons 'slug (funcall org-roam-title-to-slug-function title))
+                                        (cons 'file file-path)))
+          (org-roam-capture--context 'capture))
+      (condition-case err
+          (org-roam-capture--capture)
+        (error (user-error "%s.  Please adjust `org-roam-capture-templates'"
+                           (error-message-string err)))))))
+
+(provide 'org-roam-capture)
+
+;;; org-roam-capture.el ends here

org-roam-compat.el

@@ -0,0 +1,108 @@
+;;; org-roam-compat.el --- Compatibility Code -*- coding: utf-8; lexical-binding: t; -*-
+
+;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
+
+;; Author: Jethro Kuan <jethrokuan95@gmail.com>
+;; URL: https://github.com/org-roam/org-roam
+;; Keywords: org-mode, roam, convenience
+;; Version: 1.2.1
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.0"))
+
+;; This file is NOT part of GNU Emacs.
+
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation; either version 3, or (at your option)
+;; any later version.
+;;
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+;;
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs; see the file COPYING.  If not, write to the
+;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+;; Boston, MA 02110-1301, USA.
+
+;;; Commentary:
+;;
+;; This file contains code needed for backward compatibility with older Emacsen
+;; and previous versions of org-roam.
+;;
+;;; Code:
+;;;; Library Requires
+
+;;; Obsolete aliases (remove after next major release)
+;;;; Functions
+(define-obsolete-function-alias 'org-roam--capture-get-point 'org-roam-capture--get-point
+  "org-roam 1.0.0")
+(define-obsolete-function-alias 'org-roam-build-cache 'org-roam-db-build-cache
+  "org-roam 1.0.0")
+(define-obsolete-function-alias 'org-roam-sql         'org-roam-db-query
+  "org-roam 1.0.0")
+(define-obsolete-function-alias 'org-roam--get-db     'org-roam-db--get
+  "org-roam 1.0.0")
+(define-obsolete-function-alias 'org-roam--db-clear   'org-roam-db--clear
+  "org-roam 1.0.0")
+(define-obsolete-function-alias 'org-roam-show-graph  'org-roam-graph-show
+  "org-roam 1.0.0")
+(define-obsolete-function-alias 'org-roam--maybe-update-buffer
+  'org-roam-buffer--update-maybe "org-roam 1.0.0")
+(define-obsolete-function-alias 'org-roam--current-visibility
+  'org-roam-buffer--visibility "org-roam 1.0.0")
+(define-obsolete-function-alias 'org-roam-update         'org-roam-buffer-update
+  "org-roam 1.0.0")
+(define-obsolete-function-alias 'org-roam--set-width     'org-roam-buffer--set-width
+  "org-roam 1.0.0")
+(define-obsolete-function-alias 'org-roam--set-height    'org-roam-buffer--set-height
+  "org-roam 1.0.0")
+(define-obsolete-function-alias 'org-roam--set-up-buffer 'org-roam-buffer--get-create
+  "org-roam 1.0.0")
+(define-obsolete-function-alias 'org-roam-today 'org-roam-dailies-today
+  "org-roam 1.0.0")
+(define-obsolete-function-alias 'org-roam-tomorrow 'org-roam-dailies-tomorrow
+  "org-roam 1.0.0")
+(define-obsolete-function-alias 'org-roam-yesterday 'org-roam-dailies-yesterday
+  "org-roam 1.0.0")
+(define-obsolete-function-alias 'org-roam-date 'org-roam-dailies-date
+  "org-roam 1.0.0")
+(define-obsolete-function-alias 'org-roam-graph-show  'org-roam-graph
+  "org-roam 1.0.0")
+(define-obsolete-function-alias 'org-roam-graph-build 'org-roam-graph
+  "org-roam 1.0.0")
+(define-obsolete-function-alias 'org-roam-find-index 'org-roam-jump-to-index
+  "org-roam 1.1.0")
+(define-obsolete-function-alias 'org-roam--pluralize 'org-roam-buffer--pluralize
+  "org-roam 1.1.0")
+(define-obsolete-function-alias 'org-roam--capture 'org-roam-capture--capture
+  "org-roam 1.1.0")
+(define-obsolete-function-alias 'org-roam-db--maybe-update 'org-roam-db--update-maybe
+  "org-roam 1.1.0")
+(define-obsolete-function-alias 'org-roam-db--clear 'org-roam-db-clear
+  "org-roam 1.2.0")
+
+(when (version< (org-version) "9.3")
+  (defalias 'org-link-make-string 'org-make-link-string))
+
+;;;; Variables
+(define-obsolete-variable-alias 'org-roam-graphviz-extra-options
+  'org-roam-graph-extra-config "org-roam 1.0.0")
+(define-obsolete-variable-alias 'org-roam-grapher-extra-options
+  'org-roam-graph-extra-config "org-roam 1.0.0")
+(define-obsolete-variable-alias 'org-roam-graph-node-shape
+  'org-roam-graph-node-extra-config "org-roam 1.0.0")
+(define-obsolete-variable-alias 'org-roam--db-connection
+  'org-roam-db--connection "org-roam 1.0.0")
+(define-obsolete-variable-alias 'org-roam--current-buffer
+  'org-roam-buffer--current "org-roam 1.0.0")
+(define-obsolete-variable-alias 'org-roam-date-title-format
+  'org-roam-dailies-capture-templates "org-roam 1.0.0")
+(define-obsolete-variable-alias 'org-roam-date-filename-format
+  'org-roam-dailies-capture-templates "org-roam 1.0.0")
+(make-obsolete-variable 'org-roam-buffer-no-delete-other-windows
+  'org-roam-buffer-window-parameters "org-roam 1.1.1")
+
+(provide 'org-roam-compat)
+
+;;; org-roam-compat.el ends here

org-roam-completion.el

@@ -0,0 +1,111 @@
+;;; org-roam-completion.el --- Completion features -*- coding: utf-8; lexical-binding: t; -*-
+
+;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
+
+;; Author: Jethro Kuan <jethrokuan95@gmail.com>
+;; URL: https://github.com/org-roam/org-roam
+;; Keywords: org-mode, roam, convenience
+;; Version: 1.2.1
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.0"))
+
+;; 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 completion for org-roam.
+;;; Code:
+;;;; Library Requires
+(require 'cl-lib)
+(require 's)
+
+(defvar helm-pattern)
+(declare-function helm "ext:helm")
+(declare-function helm-make-source "ext:helm-source" (name class &rest args) t)
+
+(defcustom org-roam-completion-system 'default
+  "The completion system to be used by `org-roam'."
+  :type '(radio
+          (const :tag "Default" default)
+          (const :tag "Ido" ido)
+          (const :tag "Ivy" ivy)
+          (const :tag "Helm" helm)
+          (function :tag "Custom function"))
+  :group 'org-roam)
+
+(defun org-roam-completion--helm-candidate-transformer (candidates _source)
+  "Transforms CANDIDATES for Helm-based completing read.
+SOURCE is not used."
+  (let ((prefix (propertize "[?] "
+                            'face 'helm-ff-prefix)))
+    (cons (propertize helm-pattern
+                      'display (concat prefix helm-pattern))
+          candidates)))
+
+(cl-defun org-roam-completion--completing-read (prompt choices &key
+                                                       require-match initial-input
+                                                       action)
+  "Present a PROMPT with CHOICES and optional INITIAL-INPUT.
+If REQUIRE-MATCH is t, the user must select one of the CHOICES.
+Return user choice."
+  (let (res)
+    (setq res
+          (cond
+           ((eq org-roam-completion-system 'ido)
+            (let ((candidates (mapcar #'car choices)))
+              (ido-completing-read prompt candidates nil require-match initial-input)))
+           ((eq org-roam-completion-system 'default)
+            (completing-read prompt choices nil require-match initial-input))
+           ((eq org-roam-completion-system 'ivy)
+            (if (fboundp 'ivy-read)
+                (ivy-read prompt choices
+                          :initial-input initial-input
+                          :require-match require-match
+                          :action (prog1 action
+                                    (setq action nil))
+                          :caller 'org-roam--completing-read)
+              (user-error "Please install ivy from \
+https://github.com/abo-abo/swiper")))
+           ((eq org-roam-completion-system 'helm)
+            (unless (and (fboundp 'helm)
+                         (fboundp 'helm-make-source))
+              (user-error "Please install helm from \
+https://github.com/emacs-helm/helm"))
+            (let ((source (helm-make-source prompt 'helm-source-sync
+                            :candidates (mapcar #'car choices)
+                            :filtered-candidate-transformer
+                            (and (not require-match)
+                                 #'org-roam-completion--helm-candidate-transformer)))
+                  (buf (concat "*org-roam "
+                               (s-downcase (s-chop-suffix ":" (s-trim prompt)))
+                               "*")))
+              (or (helm :sources source
+                        :action (if action
+                                    (prog1 action
+                                      (setq action nil))
+                                  #'identity)
+                        :prompt prompt
+                        :input initial-input
+                        :buffer buf)
+                  (keyboard-quit))))))
+    (if action
+        (funcall action res)
+      res)))
+
+(provide 'org-roam-completion)
+
+;;; org-roam-completion.el ends here

org-roam-dailies.el

@@ -0,0 +1,138 @@
+;;; org-roam-dailies.el --- Daily notes for Org-roam -*- coding: utf-8; lexical-binding: t; -*-
+;;;
+;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
+
+;; Author: Jethro Kuan <jethrokuan95@gmail.com>
+;; URL: https://github.com/org-roam/org-roam
+;; Keywords: org-mode, roam, convenience
+;; Version: 1.2.1
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.0"))
+
+;; 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 functionality for creating daily notes. This is a
+;; concept borrowed from Roam Research.
+;;
+;;; Code:
+;;; Library Requires
+(require 'org-capture)
+(require 'org-roam-capture)
+(require 'org-roam-macs)
+
+(defcustom org-roam-dailies-capture-templates
+  '(("d" "daily" plain (function org-roam-capture--get-point)
+     ""
+     :immediate-finish t
+     :file-name "%<%Y-%m-%d>"
+     :head "#+title: %<%Y-%m-%d>"))
+  "Capture templates for daily notes in Org-roam."
+  :group 'org-roam
+  ;; Adapted from `org-capture-templates'
+  :type
+  '(repeat
+    (choice :value ("d" "daily" plain (function org-roam-capture--get-point)
+                    ""
+                    :immediate-finish t
+                    :file-name "%<%Y-%m-%d>"
+                    :head "#+title: %<%Y-%m-%d>")
+            (list :tag "Multikey description"
+                  (string :tag "Keys       ")
+                  (string :tag "Description"))
+            (list :tag "Template entry"
+                  (string :tag "Keys              ")
+                  (string :tag "Description       ")
+                  (const :format "" plain)
+                  (const :format "" (function org-roam-capture--get-point))
+                  (choice :tag "Template          "
+                          (string :tag "String"
+                                  :format "String:\n            \
+Template string   :\n%v")
+                          (list :tag "File"
+                                (const :format "" file)
+                                (file :tag "Template file     "))
+                          (list :tag "Function"
+                                (const :format "" function)
+                                (function :tag "Template function ")))
+                  (const :format "" :immediate-finish) (const :format "" t)
+                  (const :format "File name format  :" :file-name)
+                  (string :format " %v" :value "#+title: ${title}\n")
+                  (const :format "Header format     :" :head)
+                  (string :format "\n%v" :value "%<%Y%m%d%H%M%S>-${slug}")
+                  (plist :inline t
+                         :tag "Options"
+                         ;; Give the most common options as checkboxes
+                         :options
+                         (((const :format "%v " :prepend) (const t))
+                          ((const :format "%v " :jump-to-captured) (const t))
+                          ((const :format "%v " :empty-lines) (const 1))
+                          ((const :format "%v " :empty-lines-before) (const 1))
+                          ((const :format "%v " :empty-lines-after) (const 1))
+                          ((const :format "%v " :clock-in) (const t))
+                          ((const :format "%v " :clock-keep) (const t))
+                          ((const :format "%v " :clock-resume) (const t))
+                          ((const :format "%v " :time-prompt) (const t))
+                          ((const :format "%v " :tree-type) (const week))
+                          ((const :format "%v " :table-line-pos) (string))
+                          ((const :format "%v " :kill-buffer) (const t))
+                          ((const :format "%v " :unnarrowed) (const t))))))))
+
+;; Declarations
+(defvar org-roam-mode)
+(declare-function org-roam--file-path-from-id "org-roam")
+(declare-function org-roam-mode               "org-roam")
+
+(defun org-roam-dailies--file-for-time (time)
+  "Create and find file for TIME."
+  (let ((org-roam-capture-templates org-roam-dailies-capture-templates)
+        (org-roam-capture--info (list (cons 'time time)))
+        (org-roam-capture--context 'dailies))
+    (setq org-roam-capture-additional-template-props (list :finalize 'find-file))
+    (org-roam--with-template-error 'org-roam-dailies-capture-templates
+      (org-roam-capture--capture))))
+
+(defun org-roam-dailies-today ()
+  "Create and find the daily note for today."
+  (interactive)
+  (unless org-roam-mode (org-roam-mode))
+  (org-roam-dailies--file-for-time (current-time)))
+
+(defun org-roam-dailies-tomorrow (n)
+  "Create and find the daily note for tomorrow.
+With numeric argument N, use N days in the future."
+  (interactive "p")
+  (unless org-roam-mode (org-roam-mode))
+  (org-roam-dailies--file-for-time (time-add (* n 86400) (current-time))))
+
+(defun org-roam-dailies-yesterday (n)
+  "Create and find the file for yesterday.
+With numeric argument N, use N days in the past."
+  (interactive "p")
+  (unless org-roam-mode (org-roam-mode))
+  (org-roam-dailies-tomorrow (- n)))
+
+(defun org-roam-dailies-date ()
+  "Create the file for any date using the calendar interface."
+  (interactive)
+  (let ((time (org-read-date nil 'to-time nil "Date:  ")))
+    (org-roam-dailies--file-for-time time)))
+
+(provide 'org-roam-dailies)
+
+;;; org-roam-dailies.el ends here

org-roam-db.el

@@ -0,0 +1,552 @@
+;;; org-roam-db.el --- Org-roam database API -*- coding: utf-8; lexical-binding: t; -*-
+
+;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
+
+;; Author: Jethro Kuan <jethrokuan95@gmail.com>
+;; URL: https://github.com/org-roam/org-roam
+;; Keywords: org-mode, roam, convenience
+;; Version: 1.2.1
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.0"))
+
+;; 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 is provides the underlying database api to org-roam
+;;
+;;; Code:
+;;;; Library Requires
+(eval-when-compile (require 'subr-x))
+(require 'emacsql)
+(require 'emacsql-sqlite3)
+(require 'seq)
+(require 'org-roam-macs)
+
+(defvar org-roam-directory)
+(defvar org-roam-verbose)
+(defvar org-roam-file-name)
+
+(declare-function org-roam--org-roam-file-p                "org-roam")
+(declare-function org-roam--extract-titles                 "org-roam")
+(declare-function org-roam--extract-ref                    "org-roam")
+(declare-function org-roam--extract-tags                   "org-roam")
+(declare-function org-roam--extract-headlines              "org-roam")
+(declare-function org-roam--extract-links                  "org-roam")
+(declare-function org-roam--list-all-files                 "org-roam")
+(declare-function org-roam--path-to-slug                   "org-roam")
+(declare-function org-roam--file-name-extension            "org-roam")
+(declare-function org-roam-buffer--update-maybe            "org-roam-buffer")
+
+;;;; Options
+(defcustom org-roam-db-location nil
+  "The full path to file where the Org-roam database is stored.
+If this is non-nil, the Org-roam sqlite database is saved here.
+
+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 large, heavy operations like `org-roam-db-build-cache',
+many GC operations happen because of the large number of
+temporary structures generated (e.g. parsed ASTs). Temporarily
+increasing `gc-cons-threshold' will help reduce the number of GC
+operations, at the cost of temporary memory usage.
+
+This defaults to the original value of `gc-cons-threshold', but
+tweaking this number may lead to better overall performance. For
+example, to reduce the number of GCs, one may set it to a large
+value like `most-positive-fixnum'."
+  :type 'int
+  :group 'org-roam)
+
+(defconst org-roam-db--version 7)
+
+(defvar org-roam-db--connection (make-hash-table :test #'equal)
+  "Database connection to Org-roam database.")
+
+;;;; Core Functions
+(defun org-roam-db--get ()
+  "Return the sqlite db file."
+  (or org-roam-db-location
+      (expand-file-name "org-roam.db" org-roam-directory)))
+
+(defun org-roam-db--get-connection ()
+  "Return the database connection, if any."
+  (gethash (file-truename org-roam-directory)
+           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* ((db-file (org-roam-db--get))
+           (init-db (not (file-exists-p db-file))))
+      (make-directory (file-name-directory db-file) t)
+      (let ((conn (emacsql-sqlite3 db-file)))
+        (set-process-query-on-exit-flag (emacsql-process conn) nil)
+        (puthash (file-truename 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--update-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)
+(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."
+  (if  (stringp sql)
+      (emacsql (org-roam-db) (apply #'format sql args))
+    (apply #'emacsql (org-roam-db) sql args)))
+
+;;;; Schemata
+(defconst org-roam-db--table-schemata
+  '((files
+     [(file :unique :primary-key)
+      (hash :not-null)
+      (meta :not-null)])
+
+    (headlines
+     [(id :unique :primary-key)
+      (file :not-null)])
+
+    (links
+     [(from :not-null)
+      (to :not-null)
+      (type :not-null)
+      (properties :not-null)])
+
+    (tags
+     [(file :unique :primary-key)
+      (tags)])
+
+    (titles
+     [(file :not-null)
+      title])
+
+    (refs
+     [(ref :unique :not-null)
+      (file :not-null)
+      (type :not-null)])))
+
+(defun org-roam-db--init (db)
+  "Initialize database DB with the correct schema and user version."
+  (emacsql-with-transaction db
+    (pcase-dolist (`(,table . ,schema) org-roam-db--table-schemata)
+      (emacsql db [:create-table $i1 $S2] table schema))
+    (emacsql db (format "PRAGMA user_version = %s" org-roam-db--version))))
+
+(defun org-roam-db--update-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-build-cache 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
+;;;;; Initialization
+(defun org-roam-db--initialized-p ()
+  "Whether the Org-roam cache has been initialized."
+  (and (file-exists-p (org-roam-db--get))
+       (> (caar (org-roam-db-query [:select (funcall count) :from titles]))
+          0)))
+
+(defun org-roam-db--ensure-built ()
+  "Ensures that Org-roam cache is built."
+  (unless (org-roam-db--initialized-p)
+    (error "[Org-roam] your cache isn't built yet! Please run org-roam-db-build-cache")))
+
+;;;;; Clearing
+(defun org-roam-db-clear ()
+  "Clears all entries in the Org-roam cache."
+  (interactive)
+  (when (file-exists-p (org-roam-db--get))
+    (dolist (table (mapcar #'car org-roam-db--table-schemata))
+      (org-roam-db-query `[:delete :from ,table]))))
+
+(defun org-roam-db--clear-file (&optional filepath)
+  "Remove any related links to the file at FILEPATH.
+This is equivalent to removing the node from the graph."
+  (let ((file (file-truename (or filepath
+                                 (buffer-file-name (buffer-base-buffer))))))
+    (dolist (table (mapcar #'car org-roam-db--table-schemata))
+      (org-roam-db-query `[:delete :from ,table
+                           :where (= ,(if (eq table 'links) 'from 'file) $s1)]
+                         file))))
+
+;;;;; Insertion
+(defun org-roam-db--insert-meta (file hash meta)
+  "Insert HASH and META for a FILE into the Org-roam cache."
+  (org-roam-db-query
+   [:insert :into files
+    :values $v1]
+   (list (vector file hash meta))))
+
+(defun org-roam-db--insert-links (links)
+  "Insert LINKS into the Org-roam cache."
+  (org-roam-db-query
+   [:insert :into links
+    :values $v1]
+   links))
+
+(defun org-roam-db--insert-titles (file titles)
+  "Insert TITLES for a FILE into the Org-roam cache."
+  (org-roam-db-query
+   [:insert :into titles
+    :values $v1]
+   (mapcar (lambda (title)
+             (vector file title)) titles)))
+
+(defun org-roam-db--insert-headlines (headlines)
+  "Insert HEADLINES into the Org-roam cache.
+Returns t if the insertion was successful, nil otherwise.
+Insertions can fail when there is an ID conflict."
+  (condition-case nil
+      (progn
+        (org-roam-db-query
+           [:insert :into headlines
+            :values $v1]
+           headlines)
+        t)
+    (error
+     (unless (listp headlines)
+       (setq headlines (list headlines)))
+     (lwarn '(org-roam) :error
+            (format "Duplicate IDs in %s, one of:\n\n%s\n\nskipping..."
+                    (aref (car headlines) 1)
+                    (string-join (mapcar (lambda (hl)
+                                           (aref hl 0)) headlines) "\n")))
+     nil)))
+
+(defun org-roam-db--insert-tags (file tags)
+  "Insert TAGS for a FILE into the Org-roam cache."
+  (org-roam-db-query
+   [:insert :into tags
+    :values $v1]
+   (list (vector file tags))))
+
+(defun org-roam-db--insert-ref (file ref)
+  "Insert REF for FILE into the Org-roam cache.
+Returns t if successful, and nil otherwise.
+Insertions can fail if the key is already in the database."
+  (let ((key (cdr ref))
+        (type (car ref)))
+    (condition-case nil
+        (progn
+         (org-roam-db-query
+          [:insert :into refs :values $v1]
+          (list (vector key file type)))
+         t)
+      (error
+       (lwarn '(org-roam) :error
+              (format "Duplicate ref %s in:\n\nA: %s\nB: %s\n\nskipping..."
+                      key
+                      file
+                      (caar (org-roam-db-query
+                             [:select file :from refs
+                              :where (= ref $v1)]
+                             (vector key)))))
+       nil))))
+
+;;;;; Fetching
+(defun org-roam-db--get-current-files ()
+  "Return a hash-table of file to the hash of its file contents."
+  (let* ((current-files (org-roam-db-query [:select * :from files]))
+         (ht (make-hash-table :test #'equal)))
+    (dolist (row current-files)
+      (puthash (car row) (cadr row) ht))
+    ht))
+
+(defun org-roam-db--get-titles (file)
+  "Return the titles of FILE from the cache."
+  (caar (org-roam-db-query [:select [title] :from titles
+                            :where (= file $s1)
+                            :limit 1]
+                           file)))
+
+(defun org-roam-db--connected-component (file)
+  "Return all files reachable from/connected to FILE, including the file itself.
+If the file does not have any connections, nil is returned."
+  (let* ((query "WITH RECURSIVE
+                   links_of(file, link) AS
+                     (WITH filelinks AS (SELECT * FROM links WHERE \"type\" = '\"file\"'),
+                           citelinks AS (SELECT * FROM links
+                                                  JOIN refs ON links.\"to\" = refs.\"ref\"
+                                                            AND links.\"type\" = '\"cite\"')
+                      SELECT \"from\", \"to\" FROM filelinks UNION
+                      SELECT \"to\", \"from\" FROM filelinks UNION
+                      SELECT \"file\", \"from\" FROM citelinks UNION
+                      SELECT \"from\", \"file\" FROM citelinks),
+                   connected_component(file) AS
+                     (SELECT link FROM links_of WHERE file = $s1
+                      UNION
+                      SELECT link FROM links_of JOIN connected_component USING(file))
+                   SELECT * FROM connected_component;")
+         (files (mapcar 'car-safe (emacsql (org-roam-db) query file))))
+    files))
+
+(defun org-roam-db--links-with-max-distance (file max-distance)
+  "Return all files connected to FILE in at most MAX-DISTANCE steps.
+This includes the file itself. If the file does not have any
+connections, nil is returned."
+  (let* ((query "WITH RECURSIVE
+                   links_of(file, link) AS
+                     (WITH filelinks AS (SELECT * FROM links WHERE \"type\" = '\"file\"'),
+                           citelinks AS (SELECT * FROM links
+                                                  JOIN refs ON links.\"to\" = refs.\"ref\"
+                                                            AND links.\"type\" = '\"cite\"')
+                      SELECT \"from\", \"to\" FROM filelinks UNION
+                      SELECT \"to\", \"from\" FROM filelinks UNION
+                      SELECT \"file\", \"from\" FROM citelinks UNION
+                      SELECT \"from\", \"file\" FROM citelinks),
+                   -- Links are traversed in a breadth-first search.  In order to calculate the
+                   -- distance of nodes and to avoid following cyclic links, the visited nodes
+                   -- are tracked in 'trace'.
+                   connected_component(file, trace) AS
+                     (VALUES($s1, json_array($s1))
+                      UNION
+                      SELECT lo.link, json_insert(cc.trace, '$[' || json_array_length(cc.trace) || ']', lo.link) FROM
+                      connected_component AS cc JOIN links_of AS lo USING(file)
+                      WHERE (
+                        -- Avoid cycles by only visiting each file once.
+                        (SELECT count(*) FROM json_each(cc.trace) WHERE json_each.value == lo.link) == 0
+                        -- Note: BFS is cut off early here.
+                        AND json_array_length(cc.trace) < ($s2 + 1)))
+                   SELECT DISTINCT file, min(json_array_length(trace)) AS distance
+                   FROM connected_component GROUP BY file ORDER BY distance;")
+         ;; In principle the distance would be available in the second column.
+         (files (mapcar 'car-safe (emacsql (org-roam-db) query file max-distance))))
+    files))
+
+(defun org-roam-db--file-hash (&optional file-path)
+  "Compute the hash of FILE-PATH, a file or current buffer."
+  (let* ((file-p (and file-path))
+         (file-path (or file-path
+                        (buffer-file-name (current-buffer))))
+         (encrypted-p (and file-path
+                           (string= (org-roam--file-name-extension file-path)
+                                    "gpg"))))
+    (cond ((and encrypted-p file-p)
+           (with-temp-buffer
+             (set-buffer-multibyte nil)
+             (insert-file-contents-literally file-path)
+             (secure-hash 'sha1 (current-buffer))))
+          (file-p
+           (with-temp-buffer
+             (insert-file-contents file-path)
+             (secure-hash 'sha1 (current-buffer))))
+          (t
+           (secure-hash 'sha1 (current-buffer))))))
+
+;;;;; Updating
+(defun org-roam-db--update-meta ()
+  "Update the metadata of the current buffer into the cache."
+  (let* ((file (file-truename (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 [:delete :from files
+                        :where (= file $s1)]
+                       file)
+    (org-roam-db--insert-meta file hash (list :atime atime :mtime mtime))))
+
+(defun org-roam-db--update-titles ()
+  "Update the title of the current buffer into the cache."
+  (let* ((file (file-truename (buffer-file-name)))
+         (titles (or (org-roam--extract-titles)
+                     (list (org-roam--path-to-slug file)))))
+    (org-roam-db-query [:delete :from titles
+                        :where (= file $s1)]
+                       file)
+    (org-roam-db--insert-titles file titles)))
+
+(defun org-roam-db--update-tags ()
+  "Update the tags of the current buffer into the cache."
+  (let ((file (file-truename (buffer-file-name)))
+        (tags (org-roam--extract-tags)))
+    (org-roam-db-query [:delete :from tags
+                        :where (= file $s1)]
+                       file)
+    (when tags
+      (org-roam-db--insert-tags file tags))))
+
+(defun org-roam-db--update-refs ()
+  "Update the ref of the current buffer into the cache."
+  (let ((file (file-truename (buffer-file-name))))
+    (org-roam-db-query [:delete :from refs
+                        :where (= file $s1)]
+                       file)
+    (when-let ((ref (org-roam--extract-ref)))
+      (org-roam-db--insert-ref file ref))))
+
+(defun org-roam-db--update-links ()
+  "Update the file links of the current buffer in the cache."
+  (let ((file (file-truename (buffer-file-name))))
+    (org-roam-db-query [:delete :from links
+                        :where (= from $s1)]
+                       file)
+    (when-let ((links (org-roam--extract-links)))
+      (org-roam-db--insert-links links))))
+
+(defun org-roam-db--update-headlines ()
+  "Update the file headlines of the current buffer into the cache."
+  (let* ((file (file-truename (buffer-file-name))))
+    (org-roam-db-query [:delete :from headlines
+                        :where (= file $s1)]
+                       file)
+    (when-let ((headlines (org-roam--extract-headlines)))
+      (org-roam-db--insert-headlines headlines))))
+
+(defun org-roam-db--update-file (&optional file-path)
+  "Update Org-roam cache for FILE-PATH."
+  (when (org-roam--org-roam-file-p file-path)
+    (let ((buf (or (and file-path
+                        (find-file-noselect file-path t))
+                   (current-buffer))))
+      (with-current-buffer buf
+        (save-excursion
+          (emacsql-with-transaction (org-roam-db)
+            (org-roam-db--update-meta)
+            (org-roam-db--update-tags)
+            (org-roam-db--update-titles)
+            (org-roam-db--update-refs)
+            (org-roam-db--update-headlines)
+            (org-roam-db--update-links))
+          (org-roam-buffer--update-maybe :redisplay t))))))
+
+(defun org-roam-db-build-cache (&optional force)
+  "Build the cache for `org-roam-directory'.
+If FORCE, force a rebuild of the cache from scratch."
+  (interactive "P")
+  (when force (delete-file (org-roam-db--get)))
+  (org-roam-db--close) ;; Force a reconnect
+  (org-roam-db) ;; To initialize the database, no-op if already initialized
+  (let* ((gc-cons-threshold org-roam-db-gc-threshold)
+         (org-roam-files (org-roam--list-all-files))
+         (current-files (org-roam-db--get-current-files))
+         (file-count 0)
+         (headline-count 0)
+         (link-count 0)
+         (tag-count 0)
+         (title-count 0)
+         (ref-count 0)
+         (deleted-count 0))
+    (emacsql-with-transaction (org-roam-db)
+      ;; Two-step building
+      ;; First step: Rebuild files and headlines
+      (dolist (file org-roam-files)
+        (let* ((attr (file-attributes file))
+               (atime (file-attribute-access-time attr))
+               (mtime (file-attribute-modification-time attr)))
+          (let ((contents-hash (org-roam-db--file-hash file)))
+            (unless (string= (gethash file current-files)
+                             contents-hash)
+              (condition-case nil
+                  (org-roam--with-temp-buffer file
+                    (org-roam-db--clear-file file)
+                    (org-roam-db-query
+                     [:insert :into files
+                      :values $v1]
+                     (vector file contents-hash (list :atime atime :mtime mtime)))
+                    (setq file-count (1+ file-count))
+                    (when-let ((headlines (org-roam--extract-headlines file)))
+                      (when (org-roam-db--insert-headlines headlines)
+                        (setq headline-count (1+ headline-count)))))
+                (file-error
+                 (setq org-roam-files (remove file org-roam-files))
+                 (org-roam-db--clear-file file)
+                 (lwarn '(org-roam) :warning
+                        "Skipping unreadable file while building cache: %s" file)))))))
+      ;; Second step: Rebuild the rest
+      (dolist (file org-roam-files)
+        (let ((contents-hash (org-roam-db--file-hash file)))
+          (unless (string= (gethash file current-files)
+                           contents-hash)
+            (org-roam--with-temp-buffer file
+             (when-let (links (org-roam--extract-links file))
+               (org-roam-db-query
+                [:insert :into links
+                 :values $v1]
+                links)
+               (setq link-count (1+ link-count)))
+             (when-let (tags (org-roam--extract-tags file))
+               (org-roam-db-query
+                [:insert :into tags
+                 :values $v1]
+                (vector file tags))
+               (setq tag-count (1+ tag-count)))
+             (let ((titles (or (org-roam--extract-titles)
+                               (list (org-roam--path-to-slug file)))))
+               (org-roam-db--insert-titles file titles)
+               (setq title-count (+ title-count (length titles))))
+             (when-let* ((ref (org-roam--extract-ref)))
+               (when (org-roam-db--insert-ref file ref)
+                 (setq ref-count (1+ ref-count))))))
+          (remhash file current-files)))
+      (dolist (file (hash-table-keys current-files))
+        ;; These files are no longer around, remove from cache...
+        (org-roam-db--clear-file file)
+        (setq deleted-count (1+ deleted-count))))
+    (org-roam-message "files: Δ%s, headlines: Δ%s, links: Δ%s, tags: Δ%s, titles: Δ%s, refs: Δ%s, deleted: Δ%s"
+                      file-count
+                      headline-count
+                      link-count
+                      tag-count
+                      title-count
+                      ref-count
+                      deleted-count)))
+
+(provide 'org-roam-db)
+
+;;; org-roam-db.el ends here

org-roam-dev.el

@@ -0,0 +1,46 @@
+;;; org-roam-dev.el --- Org-roam development code -mode -*- coding: utf-8; lexical-binding: t; -*-
+
+;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
+
+;; Author: Jethro Kuan <jethrokuan95@gmail.com>
+;; URL: https://github.com/org-roam/org-roam
+;; Keywords: org-mode, roam, convenience
+;; Version: 1.2.1
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.0"))
+
+;; 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 code for org-roam developers.
+;; It is intended to be loaded before editing org-roam source files.
+;; It ensures consistent application of various developer settings.
+;;
+;;; Code:
+(require 'emacsql)
+
+;;;###autoload
+(define-minor-mode org-roam-dev-mode
+  "Minor mode for setting the dev environment of Org-roam."
+  :lighter " ORD"
+  (when org-roam-dev-mode
+    (emacsql-fix-vector-indentation)
+    (setq-local sentence-end-double-space nil)))
+
+(provide 'org-roam-dev)
+;;; org-roam-dev.el ends here

org-roam-doctor.el

@@ -0,0 +1,308 @@
+;;; org-roam-doctor.el --- Linter for Org-roam files -*- coding: utf-8; lexical-binding: t; -*-
+;;
+;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
+
+;; Author: Jethro Kuan <jethrokuan95@gmail.com>
+;; URL: https://github.com/jethrokuan/org-roam
+;; Keywords: org-mode, roam, convenience
+;; Version: 1.2.1
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.0"))
+
+;; 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 `org-roam-doctor', a utility for diagnosing and fixing
+;; Org-roam files. Running `org-roam-doctor' launches a list of checks defined
+;; by `org-roam-doctor--checkers'. Every checker is an instance of
+;; `org-roam-doctor-checker'.
+;;
+;; Each checker is given the Org parse tree (AST), and is expected to return a
+;; list of errors. The checker can also provide "actions" for auto-fixing errors
+;; (see `org-roam-doctor--remove-link' for an example).
+;;
+;; The UX experience is inspired by both org-lint and checkdoc, and their code
+;; is heavily referenced.
+;;
+;;; Code:
+;; Library Requires
+(require 'cl-lib)
+(require 'org)
+(require 'org-element)
+(require 's)
+(require 'dash)
+(require 'org-roam-macs)
+
+(declare-function org-roam-insert "org-roam")
+(declare-function org-roam--get-roam-buffers "org-roam")
+(declare-function org-roam--list-all-files "org-roam")
+(declare-function org-roam--org-roam-file-p "org-roam")
+(declare-function org-roam--str-to-list "org-roam")
+(declare-function org-roam-mode "org-roam")
+
+(defvar org-roam-verbose)
+(defvar org-roam-mode)
+
+(cl-defstruct (org-roam-doctor-checker (:copier nil))
+  (name 'missing-checker-name)
+  (description "")
+  (actions nil))
+
+(defconst org-roam-doctor--checkers
+  (list
+   (make-org-roam-doctor-checker
+    :name 'org-roam-doctor-broken-links
+    :description "Fix broken links."
+    :actions '(("d" . ("Unlink" . org-roam-doctor--remove-link))
+               ("r" . ("Replace link" . org-roam-doctor--replace-link))
+               ("R" . ("Replace link (keep label)" . org-roam-doctor--replace-link-keep-label))))
+   (make-org-roam-doctor-checker
+    :name 'org-roam-doctor-check-roam-props
+    :description "Check #+roam_* properties.")
+   (make-org-roam-doctor-checker
+    :name 'org-roam-doctor-check-tags
+    :description "Check #+roam_tags.")
+   (make-org-roam-doctor-checker
+    :name 'org-roam-doctor-check-alias
+    :description "Check #+roam_alias.")))
+
+(defconst org-roam-doctor--supported-roam-properties
+  '("roam_tags" "roam_alias" "roam_key")
+  "List of supported Org-roam properties.")
+
+(defun org-roam-doctor-check-roam-props (ast)
+  "Checker for detecting invalid #+roam_* properties.
+AST is the org-element parse tree."
+  (let (reports)
+    (org-element-map ast 'keyword
+      (lambda (kw)
+        (let ((key (org-element-property :key kw)))
+          (when (and (string-prefix-p "ROAM_" key t)
+                     (not (member (downcase key) org-roam-doctor--supported-roam-properties)))
+            (push
+             `(,(org-element-property :begin kw)
+               ,(concat "Possible mispelled key: "
+                        (prin1-to-string key)
+                        "\nOrg-roam supports the following keys: "
+                        (s-join ", " org-roam-doctor--supported-roam-properties)))
+             reports)))))
+    reports))
+
+(defun org-roam-doctor-check-tags (ast)
+  "Checker for detecting invalid #+roam_tags.
+AST is the org-element parse tree."
+  (let (reports)
+    (org-element-map ast 'keyword
+      (lambda (kw)
+        (when (string-collate-equalp (org-element-property :key kw) "roam_tags" nil t)
+          (let ((tags (org-element-property :value kw)))
+            (condition-case nil
+                (org-roam--str-to-list tags)
+              (error
+               (push
+                `(,(org-element-property :begin kw)
+                  ,(concat "Unable to parse tags: "
+                           tags
+                           (when (s-contains? "," tags)
+                             "\nCheck that your tags are not comma-separated.")))
+                reports)))))))
+    reports))
+
+(defun org-roam-doctor-check-alias (ast)
+  "Checker for detecting invalid #+roam_alias.
+AST is the org-element parse tree."
+  (let (reports)
+    (org-element-map ast 'keyword
+      (lambda (kw)
+        (when (string-collate-equalp (org-element-property :key kw) "roam_alias" nil t)
+          (let ((aliases (org-element-property :value kw)))
+            (condition-case nil
+              (org-roam--str-to-list aliases)
+              (error
+               (push
+                `(,(org-element-property :begin kw)
+                  ,(concat "Unable to parse aliases: "
+                           aliases
+                           (when (s-contains? "," aliases)
+                             "\nCheck that your aliases are not comma-separated.")))
+                reports)))))))
+    reports))
+
+(defun org-roam-doctor-broken-links (ast)
+  "Checker for detecting broken links.
+AST is the org-element parse tree."
+  (let (reports)
+    (org-element-map ast 'link
+      (lambda (l)
+        (when (equal "file" (org-element-property :type l))
+          (let ((file (org-element-property :path l)))
+            (or (file-exists-p file)
+                (file-remote-p file)
+                (push
+                 `(,(org-element-property :begin l)
+                   ,(format (if (org-element-lineage l '(link))
+                                "Link to non-existent image file \"%s\"\
+ in link description"
+                              "Link to non-existent local file \"%s\"")
+                            file))
+                 reports))))))
+    reports))
+
+(defun org-roam-doctor--check (buffer checkers)
+  "Check BUFFER for errors.
+CHECKERS is the list of checkers used."
+  (with-current-buffer buffer
+    (save-excursion
+      (goto-char (point-min))
+      (let* ((ast (org-element-parse-buffer))
+             (errors (sort (cl-mapcan
+                            (lambda (c)
+                              (mapcar
+                               (lambda (report)
+                                 (list (set-marker (make-marker) (car report))
+                                       (nth 1 report) c))
+                               (save-excursion
+                                 (funcall
+                                  (org-roam-doctor-checker-name c)
+                                  ast))))
+                            checkers)
+                           #'car-less-than-car)))
+        (dolist (e errors)
+          (pcase-let ((`(,m ,msg ,checker) e))
+            (switch-to-buffer buffer)
+            (goto-char m)
+            (org-reveal)
+            (undo-boundary)
+            (org-roam-doctor--resolve msg checker)
+            (set-marker m nil)))
+        errors))))
+
+;;; Actions
+(defun org-roam-doctor--recursive-edit ()
+  "Launch into a recursive edit."
+  (message "When you're done editing press C-M-c to continue.")
+  (recursive-edit))
+
+(defun org-roam-doctor--skip ()
+  "Skip the current error."
+  (org-roam-message "Skipping..."))
+
+(defun org-roam-doctor--replace-link ()
+  "Replace the current link with a new link."
+  (save-match-data
+    (unless (org-in-regexp org-link-bracket-re 1)
+      (user-error "No link at point"))
+    (let ((orig (buffer-string))
+          (p (point)))
+      (condition-case nil
+          (save-excursion
+            (replace-match "")
+            (org-roam-insert))
+        (quit (progn
+                (replace-buffer-contents orig)
+                (goto-char p)))))))
+
+(defun org-roam-doctor--replace-link-keep-label ()
+  "Replace the current link with a new link, keeping the current link's label."
+  (save-match-data
+    (unless (org-in-regexp org-link-bracket-re 1)
+      (user-error "No link at point"))
+    (let ((orig (buffer-string))
+          (p (point)))
+      (condition-case nil
+          (save-excursion
+            (let ((label (if (match-end 2)
+                             (match-string-no-properties 2)
+                           (org-link-unescape (match-string-no-properties 1)))))
+              (replace-match "")
+              (org-roam-insert nil nil label)))
+        (quit (progn
+                (replace-buffer-contents orig)
+                (goto-char p)))))))
+
+(defun org-roam-doctor--remove-link ()
+  "Unlink the text at point."
+  (unless (org-in-regexp org-link-bracket-re 1)
+    (user-error "No link at point"))
+  (save-excursion
+    (let ((label (if (match-end 2)
+                     (match-string-no-properties 2)
+                   (org-link-unescape (match-string-no-properties 1)))))
+      (delete-region (match-beginning 0) (match-end 0))
+      (insert label))))
+
+(defun org-roam-doctor--resolve (msg checker)
+  "Resolve an error.
+MSG is the error that was found, which is displayed in a help buffer.
+CHECKER is a org-roam-doctor checker instance."
+  (let ((actions (org-roam-doctor-checker-actions checker))
+        c)
+    (push '("e" . ("Edit" . org-roam-doctor--recursive-edit)) actions)
+    (push '("s" . ("Skip" . org-roam-doctor--skip)) actions)
+    (with-output-to-temp-buffer "*Org-roam-doctor Help*"
+      (mapc #'princ
+            (list "Error message:\n   " msg "\n\n"))
+      (dolist (action actions)
+        (princ (format "[%s]: %s\n"
+                       (car action)
+                       (cadr action))))
+      (princ "\n\n"))
+    (shrink-window-if-larger-than-buffer
+     (get-buffer-window "*Org-roam-doctor Help*"))
+    (message "Press key for command:")
+    (unwind-protect
+        (progn
+          (cl-loop
+           do (setq c (char-to-string (read-char-exclusive)))
+           until (assoc c actions)
+           do (message "Please enter a valid key for command:"))
+          (funcall (cddr (assoc c actions)))
+          (redisplay))
+      (when (get-buffer-window "*Org-roam-doctor Help*")
+        (delete-window (get-buffer-window "*Org-roam-doctor Help*"))
+        (kill-buffer "*Org-roam-doctor Help*")))))
+
+;;;###autoload
+(defun org-roam-doctor (&optional checkall)
+  "Perform a check on the current buffer to ensure cleanliness.
+If CHECKALL, run the check for all Org-roam files."
+  (interactive "P")
+  (unless org-roam-mode (org-roam-mode))
+  (let ((files (if checkall
+                  (org-roam--list-all-files)
+                (unless (org-roam--org-roam-file-p)
+                  (user-error "Not in an org-roam file"))
+                `(,(buffer-file-name)))))
+    (org-roam-doctor-start files org-roam-doctor--checkers)))
+
+(defun org-roam-doctor-start (files checkers)
+  "Lint FILES using CHECKERS."
+  (save-window-excursion
+    (let ((existing-buffers (org-roam--get-roam-buffers)))
+      (dolist (f files)
+        (let ((buf (find-file-noselect f)))
+          (org-roam-doctor--check buf checkers)
+          (unless (memq buf existing-buffers)
+            (save-buffer buf)
+            (kill-buffer buf))))))
+  (org-roam-message "Linting completed."))
+
+(provide 'org-roam-doctor)
+
+;;; org-roam-doctor.el ends here

org-roam-faces.el

@@ -0,0 +1,67 @@
+;;; org-roam-faces.el --- Face definitions -*- coding: utf-8; lexical-binding: t; -*-
+
+;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
+
+;; Author: Jethro Kuan <jethrokuan95@gmail.com>
+;; URL: https://github.com/org-roam/org-roam
+;; Keywords: org-mode, roam, convenience
+;; Version: 1.2.1
+;; Package-Requires: ((emacs "26.1"))
+
+;; This file is NOT part of GNU Emacs.
+
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation; either version 3, or (at your option)
+;; any later version.
+;;
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+;;
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs; see the file COPYING.  If not, write to the
+;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+;; Boston, MA 02110-1301, USA.
+
+;;; Commentary:
+
+;; This file contains the face definitions for Org-roam.
+
+;;; Code:
+
+(defgroup org-roam-faces nil
+  "Faces used by Org-roam."
+  :group 'org-roam
+  :group 'faces)
+
+;;; Definitions
+(defface org-roam-link
+  '((t :inherit org-link))
+  "Face for Org-roam links."
+  :group 'org-roam-faces)
+
+(defface org-roam-link-current
+  '((t :inherit org-link))
+  "Face for Org-roam links pointing to the current buffer."
+  :group 'org-roam-faces)
+
+(defface org-roam-link-invalid
+  '((t :inherit (error org-link)))
+  "Face for Org-roam links that are not valid.
+This face is used for links without a destination."
+  :group 'org-roam-faces)
+
+(defface org-roam-link-shielded
+  '((t :inherit (warning org-link)))
+  "Face for Org-roam links that are shielded.
+This face is used on the region target by `org-roam-insertion'
+during an `org-roam-capture'."
+  :group 'org-roam-faces)
+
+;;; _
+
+(provide 'org-roam-faces)
+
+;;; org-roam-faces.el ends here

org-roam-graph.el

@@ -0,0 +1,308 @@
+;;; org-roam-graph.el --- Graphing API -*- coding: utf-8; lexical-binding: t; -*-
+
+;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
+
+;; Author: Jethro Kuan <jethrokuan95@gmail.com>
+;; URL: https://github.com/org-roam/org-roam
+;; Keywords: org-mode, roam, convenience
+;; Version: 1.2.1
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.0"))
+
+;; 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 graphing functionality for org-roam.
+;;
+;;; Code:
+(require 'xml) ;xml-escape-string
+(require 's)   ;s-truncate, s-replace
+(require 'org-roam-macs)
+(require 'org-roam-db)
+
+;;;; Declarations
+(defvar org-roam-directory)
+(defvar org-roam-mode)
+(declare-function org-roam--org-roam-file-p  "org-roam")
+(declare-function org-roam--path-to-slug     "org-roam")
+(declare-function org-roam-mode              "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-extra-config nil
+  "Extra options passed to graphviz.
+Example:
+ '((\"rankdir\" . \"LR\"))"
+  :type '(alist)
+  :group 'org-roam)
+
+(defcustom org-roam-graph-node-extra-config
+  '(("shape"      . "underline")
+    ("style"      . "rounded,filled")
+    ("fillcolor"  . "#EEEEEE")
+    ("color"      . "#C9C9C9")
+    ("fontcolor"  . "#111111"))
+  "Extra options for graphviz nodes.
+Example:
+ '((\"color\" . \"skyblue\"))"
+  :type '(alist)
+  :group 'org-roam)
+
+(defcustom org-roam-graph-edge-extra-config
+  '(("color" . "#333333"))
+  "Extra options for graphviz edges.
+Example:
+ '((\"dir\" . \"back\"))"
+  :type '(alist)
+  :group 'org-roam)
+
+(defcustom org-roam-graph-edge-cites-extra-config '(("color" . "red"))
+  "Extra options for graphviz edges for citation links.
+Example:
+ '((\"dir\" . \"back\"))"
+  :type '(alist)
+  :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)
+
+(defcustom org-roam-graph-exclude-matcher nil
+  "Matcher for excluding nodes from the generated graph.
+Any nodes and links for file paths matching this string is
+excluded from the graph.
+
+If value is a string, the string is the only matcher.
+
+If value is a list, all file paths matching any of the strings
+are excluded."
+  :type '(choice
+          (string :tag "Matcher")
+          (list :tag "Matchers"))
+  :group 'org-roam)
+
+;;;; Functions
+(defun org-roam-graph--expand-matcher (col &optional negate where)
+  "Return the exclusion regexp from `org-roam-graph-exclude-matcher'.
+COL is the symbol to be matched against.  if NEGATE, add :not to sql query.
+set WHERE to true if WHERE query already exists."
+  (let ((matchers (pcase org-roam-graph-exclude-matcher
+                    ('nil nil)
+                    ((pred stringp) `(,(concat "%" org-roam-graph-exclude-matcher "%")))
+                    ((pred listp) (mapcar (lambda (m)
+                                            (concat "%" m "%"))
+                                          org-roam-graph-exclude-matcher))
+                    (_ (error "Invalid org-roam-graph-exclude-matcher"))))
+        res)
+    (dolist (match matchers)
+      (if where
+          (push :and res)
+        (push :where res)
+        (setq where t))
+      (push col res)
+      (when negate
+        (push :not res))
+      (push :like res)
+      (push match res))
+    (nreverse res)))
+
+(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--dot (node-query)
+  "Build the graphviz dot string for NODE-QUERY.
+The Org-roam database titles table is read, to obtain the list of titles.
+The links table is then read to obtain all directed links, and formatted
+into a digraph."
+  (org-roam-db--ensure-built)
+  (org-roam--with-temp-buffer nil
+    (let* ((nodes (org-roam-db-query node-query))
+           (edges-query
+            `[:with selected :as [:select [file] :from ,node-query]
+              :select :distinct [to from] :from links
+              :where (and (in to selected) (in from selected))])
+           (edges-cites-query
+            `[:with selected :as [:select [file] :from ,node-query]
+              :select :distinct [file from]
+              :from links :inner :join refs :on (and (= links:to refs:ref)
+                                                     (= links:type "cite")
+                                                     (= refs:type "cite"))
+              :where (and (in file selected) (in from selected))])
+           (edges       (org-roam-db-query edges-query))
+           (edges-cites (org-roam-db-query edges-cites-query)))
+      (insert "digraph \"org-roam\" {\n")
+      (dolist (option org-roam-graph-extra-config)
+        (insert (org-roam-graph--dot-option option) ";\n"))
+      (dolist (attribute '("node" "edge"))
+        (insert (format " %s [%s];\n" attribute
+                        (mapconcat (lambda (var)
+                                     (org-roam-graph--dot-option var nil "\""))
+                                   (symbol-value
+                                    (intern (concat "org-roam-graph-" attribute "-extra-config")))
+                                   ","))))
+      (dolist (node nodes)
+        (let* ((file (xml-escape-string (car node)))
+               (title (or (cadr node)
+                          (org-roam--path-to-slug file)))
+               (shortened-title (pcase org-roam-graph-shorten-titles
+                                  (`truncate (s-truncate org-roam-graph-max-title-length title))
+                                  (`wrap (s-word-wrap org-roam-graph-max-title-length title))
+                                  (_ title)))
+               (shortened-title (org-roam-string-quote shortened-title))
+               (title (org-roam-string-quote title))
+               (node-properties
+                `(("label"   . ,shortened-title)
+                  ("URL"     . ,(concat "org-protocol://roam-file?file=" (url-hexify-string file)))
+                  ("tooltip" . ,(xml-escape-string title)))))
+          (insert
+           (format "  \"%s\" [%s];\n" file
+                   (mapconcat (lambda (n)
+                                (org-roam-graph--dot-option n nil "\""))
+                              node-properties ",")))))
+      (dolist (edge edges)
+        (insert (apply #'format `("  \"%s\" -> \"%s\";\n"
+                                  ,@(mapcar #'xml-escape-string edge)))))
+      (insert (format "  edge [%s];\n"
+                      (mapconcat #'org-roam-graph--dot-option
+                                 org-roam-graph-edge-cites-extra-config ",")))
+      (dolist (edge edges-cites)
+        (insert (apply #'format `("  \"%s\" -> \"%s\";\n"
+                                  ,@(mapcar #'xml-escape-string edge)))))
+      (insert "}")
+      (buffer-string))))
+
+(defun org-roam-graph--build (&optional node-query callback)
+  "Generate a graph showing the relations between nodes in NODE-QUERY.
+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* ((node-query (or node-query
+                         `[:select [file title] :from titles
+                           ,@(org-roam-graph--expand-matcher 'file t)
+                           :group :by file]))
+         (graph      (org-roam-graph--dot node-query))
+         (temp-dot   (make-temp-file "graph." nil ".dot" graph))
+         (temp-graph (make-temp-file "graph." nil ".svg")))
+    (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 "-Tsvg" "-o" ,temp-graph)
+     :sentinel (when callback
+                 (lambda (process _event)
+                   (when (= 0 (process-exit-status process))
+                     (funcall callback temp-graph)))))))
+
+(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)))))
+
+(defun org-roam-graph--build-connected-component (file &optional max-distance callback)
+  "Build a graph of nodes connected to FILE.
+If MAX-DISTANCE is non-nil, limit nodes to MAX-DISTANCE steps.
+CALLBACK is passed to `org-roam-graph--build'."
+  (let* ((file (file-truename file))
+         (files (or (if (and max-distance (>= max-distance 0))
+                        (org-roam-db--links-with-max-distance file max-distance)
+                      (org-roam-db--connected-component file))
+                    (list file)))
+         (query `[:select [file title]
+                  :from titles
+                  :where (in file [,@files])]))
+    (org-roam-graph--build query callback)))
+
+;;;; Commands
+;;;###autoload
+(defun org-roam-graph (&optional arg file node-query)
+  "Build and possibly display a graph for FILE from NODE-QUERY.
+If FILE is nil, default to current buffer's file name.
+ARG may be any of the following values:
+  - nil       show the graph.
+  - `\\[universal-argument]'     show the graph for FILE.
+  - `\\[universal-argument]' N   show the graph for FILE limiting nodes to N steps.
+  - `\\[universal-argument] \\[universal-argument]' build the graph.
+  - `\\[universal-argument]' -   build the graph for FILE.
+  - `\\[universal-argument]' -N  build the graph for FILE limiting nodes to N steps."
+  (interactive "P")
+  (unless org-roam-mode (org-roam-mode))
+  (let ((file (or file (buffer-file-name (buffer-base-buffer)))))
+    (unless (or (not arg) (equal arg '(16)))
+      (unless file
+        (user-error "Cannot build graph for nil file. Is current buffer visiting a file?"))
+      (unless (org-roam--org-roam-file-p file)
+        (user-error "\"%s\" is not an org-roam file" file)))
+    (pcase arg
+      ('nil            (org-roam-graph--build node-query #'org-roam-graph--open))
+      ('(4)            (org-roam-graph--build-connected-component file nil #'org-roam-graph--open))
+      ((pred integerp) (org-roam-graph--build-connected-component file (abs arg) (when (>= arg 0) #'org-roam-graph--open)))
+      ('(16)           (org-roam-graph--build node-query))
+      ('-              (org-roam-graph--build-connected-component file))
+      (_ (user-error "Unrecognized ARG: %s" arg)))))
+
+(provide 'org-roam-graph)
+
+;;; org-roam-graph.el ends here

org-roam-macs.el

@@ -0,0 +1,104 @@
+;;; org-roam-macs.el --- Macros/utility functions -*- coding: utf-8; lexical-binding: t; -*-
+
+;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
+
+;; Author: Jethro Kuan <jethrokuan95@gmail.com>
+;; URL: https://github.com/org-roam/org-roam
+;; Keywords: org-mode, roam, convenience
+;; Version: 1.2.1
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite3 "1.0.0"))
+
+;; 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 implements macros and utility functions used throughout
+;; org-roam.
+;;
+;;
+;;; Code:
+;;;; Library Requires
+(require 'dash)
+
+(defvar org-roam-verbose)
+
+(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 `org-roam-temp-file-name' to file 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)
+               (org-mode-hook nil))
+           (org-mode)
+           (when ,file
+             (insert-file-contents ,file)
+             (setq-local org-roam-file-name ,file))
+           ,@body)))))
+
+(defmacro org-roam--with-template-error (templates &rest body)
+  "Eval BODY, and point to TEMPLATES on error.
+Provides more informative error messages so that users know where
+to look.
+
+\(fn TEMPLATES BODY...)"
+  (declare (debug (form body)) (indent 1))
+  `(condition-case err
+       ,@body
+     (error (user-error "%s.  Please adjust `%s'"
+                        (error-message-string err)
+                        ,templates))))
+
+(defun org-roam-message (format-string &rest args)
+  "Pass FORMAT-STRING and ARGS to `message' when `org-roam-verbose' is t."
+  (when org-roam-verbose
+    (apply #'message `(,(concat "(org-roam) " format-string) ,@args))))
+
+(defun org-roam-string-quote (str)
+  "Quote STR."
+  (->> str
+       (s-replace "\\" "\\\\")
+       (s-replace "\"" "\\\"")))
+
+;;; Shielding regions
+(defun org-roam-shield-region (beg end)
+  "Shield REGION against modifications.
+REGION must be a cons-cell containing the marker to the region
+beginning and maximum values."
+  (when (and beg end)
+    (add-text-properties beg end
+                           '(font-lock-face org-roam-link-shielded
+                                            read-only t)
+                           (marker-buffer beg))
+    (cons beg end)))
+
+(defun org-roam-unshield-region (beg end)
+  "Unshield the shielded REGION."
+  (when (and beg end)
+    (let ((inhibit-read-only t))
+      (remove-text-properties beg end
+                              '(font-lock-face org-roam-link-shielded
+                                               read-only t)
+                              (marker-buffer beg)))
+    (cons beg end)))
+
+(provide 'org-roam-macs)
+
+;;; org-roam-macs.el ends here

org-roam-protocol.el

@@ -0,0 +1,91 @@
+;;; org-roam-protocol.el --- Protocol handler for roam:// links  -*- coding: utf-8; lexical-binding: t; -*-
+
+;; Copyright © 2020 Jethro Kuan <jethrokuan95@gmail.com>
+;; Author: Jethro Kuan <jethrokuan95@gmail.com>
+;; URL: https://github.com/org-roam/org-roam
+;; Keywords: org-mode, roam, convenience
+;; Version: 1.2.1
+;; Package-Requires: ((emacs "26.1") (org "9.3"))
+
+;; 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:
+;;
+;; We extend org-protocol, adding custom Org-roam handlers. The setup
+;; instructions for `org-protocol' can be found in org-protocol.el.
+;;
+;; We define 2 protocols:
+;;
+;; 1. "roam-file": This protocol simply opens the file given by the FILE key
+;; 2. "roam-ref": This protocol creates or opens a note with the given REF
+;;
+;;; Code:
+(require 'org-protocol)
+(require 'org-roam)
+
+;;;; Functions
+(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())"
+  (when-let* ((alist (org-roam--plist-to-alist info))
+              (decoded-alist (mapcar (lambda (k.v)
+                                       (let ((key (car k.v))
+                                             (val (cdr k.v)))
+                                         (cons key (org-link-decode val)))) alist)))
+    (unless (assoc 'ref decoded-alist)
+      (error "No ref key provided"))
+    (when-let ((title (cdr (assoc 'title decoded-alist))))
+      (push (cons 'slug (funcall org-roam-title-to-slug-function title)) decoded-alist))
+    (let* ((org-roam-capture-templates org-roam-capture-ref-templates)
+           (org-roam-capture--context 'ref)
+           (org-roam-capture--info decoded-alist)
+           (template (cdr (assoc 'template decoded-alist))))
+      (raise-frame)
+      (org-roam--with-template-error 'org-roam-capture-ref-templates
+        (org-roam-capture--capture nil template))
+      (org-roam-message "Item captured.")))
+  nil)
+
+(defun org-roam-protocol-open-file (info)
+  "This handler simply opens the file with emacsclient.
+
+INFO is an alist 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-file?file=/path/to/file.org"
+  (when-let ((file (plist-get info :file)))
+    (raise-frame)
+    (org-roam--find-file file))
+  nil)
+
+(push '("org-roam-ref"  :protocol "roam-ref"   :function org-roam-protocol-open-ref)
+      org-protocol-protocol-alist)
+(push '("org-roam-file"  :protocol "roam-file"   :function org-roam-protocol-open-file)
+      org-protocol-protocol-alist)
+
+(provide 'org-roam-protocol)
+
+;;; org-roam-protocol.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/alias.org

@@ -0,0 +1,2 @@
+#+roam_alias: "a1" "a 2"
+#+title: t1

tests/roam-files/bar.org

@@ -0,0 +1,3 @@
+#+title: Bar
+
+This is file bar. Bar links to [[file:nested/bar.org][Nested Bar]].

tests/roam-files/base.org

@@ -0,0 +1 @@
+#+title: Base

tests/roam-files/foo.org

@@ -0,0 +1,8 @@
+#+title: Foo
+
+This is the foo file. It contains a link to [[file:bar.org][Bar]].
+
+To make the tests more robust, here are some arbitrary links:
+
+- [[https:google.com][Google]]
+- [[mailto:foo@john.com][mail to foo]]

tests/roam-files/headlines/headline.org

@@ -0,0 +1,14 @@
+#+TITLE: Headline
+
+* Headline 1
+:PROPERTIES:
+:ID:       e84d0630-efad-4017-9059-5ef917908823
+:END:
+
+* No headline here
+Oops.
+
+* Headline 2
+:PROPERTIES:
+:ID:       801b58eb-97e2-435f-a33e-ff59a2f0c213
+:END:

tests/roam-files/nested/bar.org

@@ -0,0 +1,3 @@
+#+title: Nested Bar
+
+This file is nested, 1 level deeper. It links to both [[file:../foo.org][Foo]] and [[file:foo.org][Nested Foo]].

tests/roam-files/nested/deeply/deeply_nested_file.org

@@ -0,0 +1 @@
+#+title: Deeply Nested File

tests/roam-files/nested/foo.org

@@ -0,0 +1,3 @@
+#+title: Nested Foo
+
+This file has no links.

tests/roam-files/no-title.org

@@ -0,0 +1,5 @@
+no title in this file :O
+
+links to itself, with no title: [[file:no-title.org][no-title]]
+
+* Headline title

tests/roam-files/tags/no_tag.org

@@ -0,0 +1,3 @@
+#+title: Tagless File
+
+This file has no tags, and should not yield any tags on extracting via ~#+roam_tags~.

tests/roam-files/tags/tag.org

@@ -0,0 +1,4 @@
+#+roam_tags: "t1" "t2 with space" t3
+#+title: Tags
+
+This file is used to test functionality for =(org-roam--extract-tags)=

tests/roam-files/titles/aliases.org

@@ -0,0 +1 @@
+#+roam_alias: "roam" "alias"

tests/roam-files/titles/combination.org

@@ -0,0 +1,4 @@
+#+title: TITLE PROP
+#+roam_alias: "roam" "alias"
+
+* Headline

tests/roam-files/titles/headline.org

@@ -0,0 +1 @@
+* Headline

tests/roam-files/titles/title.org

@@ -0,0 +1 @@
+#+title: Title

tests/roam-files/unlinked.org

@@ -0,0 +1,3 @@
+#+title: Unlinked
+
+Nothing links here :(

tests/roam-files/web_ref.org

@@ -0,0 +1 @@
+#+roam_key: https://google.com/

tests/test-org-roam-perf.el

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

tests/test-org-roam.el

@@ -0,0 +1,327 @@
+;;; 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)
+(require 'dash)
+
+(defun test-org-roam--abs-path (file-path)
+  "Get absolute FILE-PATH from `org-roam-directory'."
+  (file-truename (expand-file-name file-path org-roam-directory)))
+
+(defun test-org-roam--find-file (path)
+  "PATH."
+  (let ((path (test-org-roam--abs-path path)))
+    (make-directory (file-name-directory path) t)
+    (find-file path)))
+
+(defvar test-org-roam-directory (file-truename (concat default-directory "tests/roam-files"))
+  "Directory containing org-roam test org files.")
+
+(defun test-org-roam--init ()
+  "."
+  (let ((original-dir test-org-roam-directory)
+        (new-dir (expand-file-name (make-temp-name "org-roam") temporary-file-directory)))
+    (copy-directory original-dir new-dir)
+    (setq org-roam-directory new-dir)
+    (org-roam-mode +1)
+    (sleep-for 2)))
+
+(defun test-org-roam--teardown ()
+  (org-roam-mode -1)
+  (delete-file (org-roam-db--get))
+  (org-roam-db--close))
+
+(describe "org-roam--str-to-list"
+  (it "nil"
+    (expect (org-roam--str-to-list nil)
+            :to-be
+            nil))
+  (it "\"multi word\" prop 123"
+    (expect (org-roam--str-to-list "\"multi word\" prop 123")
+            :to-equal
+            '("multi word" "prop" "123")))
+  (it "prop \"multi word\" 123"
+    (expect (org-roam--str-to-list "\"multi word\" prop 123")
+            :to-equal
+            '("multi word" "prop" "123")))
+  (it "errors on bad input"
+    (expect (org-roam--str-to-list 1)
+            :to-throw)
+    (expect (org-roam--str-to-list "\"hello")
+            :to-throw)))
+
+(describe "Title extraction"
+  :var (org-roam-title-sources)
+  (before-all
+    (test-org-roam--init))
+
+  (after-all
+    (test-org-roam--teardown))
+
+  (cl-flet
+      ((test (fn file)
+             (let ((buf (find-file-noselect
+                         (test-org-roam--abs-path file))))
+               (with-current-buffer buf
+                 (funcall fn)))))
+    (it "extracts title from title property"
+      (expect (test #'org-roam--extract-titles-title
+                    "titles/title.org")
+              :to-equal
+              '("Title"))
+      (expect (test #'org-roam--extract-titles-title
+                    "titles/aliases.org")
+              :to-equal
+              nil)
+      (expect (test #'org-roam--extract-titles-title
+                    "titles/headline.org")
+              :to-equal
+              nil)
+      (expect (test #'org-roam--extract-titles-title
+                    "titles/combination.org")
+              :to-equal
+              '("TITLE PROP")))
+
+    (it "extracts alias"
+      (expect (test #'org-roam--extract-titles-alias
+                    "titles/title.org")
+              :to-equal
+              nil)
+      (expect (test #'org-roam--extract-titles-alias
+                    "titles/aliases.org")
+              :to-equal
+              '("roam" "alias"))
+      (expect (test #'org-roam--extract-titles-alias
+                    "titles/headline.org")
+              :to-equal
+              nil)
+      (expect (test #'org-roam--extract-titles-alias
+                    "titles/combination.org")
+              :to-equal
+              '("roam" "alias")))
+
+    (it "extracts headlines"
+      (expect (test #'org-roam--extract-titles-alias
+                    "titles/title.org")
+              :to-equal
+              nil)
+      (expect (test #'org-roam--extract-titles-headline
+                    "titles/aliases.org")
+              :to-equal
+              nil)
+      (expect (test #'org-roam--extract-titles-headline
+                    "titles/headline.org")
+              :to-equal
+              '("Headline"))
+      (expect (test #'org-roam--extract-titles-headline
+                    "titles/combination.org")
+              :to-equal
+              '("Headline")))
+
+    (describe "uses org-roam-title-sources correctly"
+      (it "'((title headline) alias)"
+        (expect (let ((org-roam-title-sources '((title headline) alias)))
+                  (test #'org-roam--extract-titles
+                        "titles/combination.org"))
+                :to-equal
+                '("TITLE PROP" "roam" "alias")))
+      (it "'((headline title) alias)"
+        (expect (let ((org-roam-title-sources '((headline title) alias)))
+                  (test #'org-roam--extract-titles
+                        "titles/combination.org"))
+                :to-equal
+                '("Headline" "roam" "alias")))
+      (it "'(headline alias title)"
+        (expect (let ((org-roam-title-sources '(headline alias title)))
+                  (test #'org-roam--extract-titles
+                        "titles/combination.org"))
+                :to-equal
+                '("Headline" "roam" "alias" "TITLE PROP"))))))
+
+(describe "Tag extraction"
+  :var (org-roam-tag-sources)
+  (before-all
+    (test-org-roam--init))
+
+  (after-all
+    (test-org-roam--teardown))
+
+  (cl-flet
+      ((test (fn file)
+             (let* ((fname (test-org-roam--abs-path file))
+                    (buf (find-file-noselect fname)))
+               (with-current-buffer buf
+                 (funcall fn fname)))))
+    (it "extracts from prop"
+      (expect (test #'org-roam--extract-tags-prop
+                    "tags/tag.org")
+              :to-equal
+              '("t1" "t2 with space" "t3"))
+      (expect (test #'org-roam--extract-tags-prop
+                    "tags/no_tag.org")
+              :to-equal
+              nil))
+
+    (it "extracts from all directories"
+      (expect (test #'org-roam--extract-tags-all-directories
+                    "base.org")
+              :to-equal
+              nil)
+      (expect (test #'org-roam--extract-tags-all-directories
+                    "tags/tag.org")
+              :to-equal
+              '("tags"))
+      (expect (test #'org-roam--extract-tags-all-directories
+                    "nested/deeply/deeply_nested_file.org")
+              :to-equal
+              '("nested" "deeply")))
+
+    (it "extracts from last directory"
+      (expect (test #'org-roam--extract-tags-last-directory
+                    "base.org")
+              :to-equal
+              nil)
+      (expect (test #'org-roam--extract-tags-last-directory
+                    "tags/tag.org")
+              :to-equal
+              '("tags"))
+      (expect (test #'org-roam--extract-tags-last-directory
+                    "nested/deeply/deeply_nested_file.org")
+              :to-equal
+              '("deeply")))
+
+    (it "extracts from first directory"
+      (expect (test #'org-roam--extract-tags-first-directory
+                    "base.org")
+              :to-equal
+              nil)
+      (expect (test #'org-roam--extract-tags-first-directory
+                    "tags/tag.org")
+              :to-equal
+              '("tags"))
+      (expect (test #'org-roam--extract-tags-first-directory
+                    "nested/deeply/deeply_nested_file.org")
+              :to-equal
+              '("nested")))
+
+    (describe "uses org-roam-tag-sources correctly"
+      (it "'(prop)"
+        (expect (let ((org-roam-tag-sources '(prop)))
+                  (test #'org-roam--extract-tags
+                        "tags/tag.org"))
+                :to-equal
+                '("t1" "t2 with space" "t3")))
+      (it "'(prop all-directories)"
+        (expect (let ((org-roam-tag-sources '(prop all-directories)))
+                  (test #'org-roam--extract-tags
+                        "tags/tag.org"))
+                :to-equal
+                '("t1" "t2 with space" "t3" "tags"))))))
+
+(describe "Headline extraction"
+  (before-all
+    (test-org-roam--init))
+
+  (after-all
+    (test-org-roam--teardown))
+
+  (cl-flet
+      ((test (fn file)
+             (let* ((fname (test-org-roam--abs-path file))
+                    (buf (find-file-noselect fname)))
+               (with-current-buffer buf
+                 (funcall fn fname)))))
+    (it "extracts headlines"
+      (expect (test #'org-roam--extract-headlines
+                    "headlines/headline.org")
+              :to-equal
+              `(["e84d0630-efad-4017-9059-5ef917908823" ,(test-org-roam--abs-path "headlines/headline.org")]
+                ["801b58eb-97e2-435f-a33e-ff59a2f0c213" ,(test-org-roam--abs-path "headlines/headline.org")])))))
+
+;;; Tests
+(xdescribe "org-roam-db-build-cache"
+  (before-each
+    (test-org-roam--init))
+
+  (after-each
+    (test-org-roam--teardown))
+
+  (it "initializes correctly"
+    ;; Cache
+    (expect (caar (org-roam-db-query [:select (funcall count) :from files])) :to-be 8)
+    (expect (caar (org-roam-db-query [:select (funcall count) :from links])) :to-be 5)
+    (expect (caar (org-roam-db-query [:select (funcall count) :from titles])) :to-be 8)
+    (expect (caar (org-roam-db-query [:select (funcall count) :from titles
+                                      :where titles :is-null])) :to-be 1)
+    (expect (caar (org-roam-db-query [:select (funcall count) :from refs])) :to-be 1)
+
+    ;; Links
+    (expect (caar (org-roam-db-query [:select (funcall count) :from links
+                                      :where (= from $s1)]
+                                     (test-org-roam--abs-path "foo.org"))) :to-be 1)
+    (expect (caar (org-roam-db-query [:select (funcall count) :from links
+                                      :where (= from $s1)]
+                                     (test-org-roam--abs-path "nested/bar.org"))) :to-be 2)
+
+    ;; Links -- File-to
+    (expect (caar (org-roam-db-query [:select (funcall count) :from links
+                                      :where (= to $s1)]
+                                     (test-org-roam--abs-path "nested/foo.org"))) :to-be 1)
+    (expect (caar (org-roam-db-query [:select (funcall count) :from links
+                                      :where (= to $s1)]
+                                     (test-org-roam--abs-path "nested/bar.org"))) :to-be 1)
+    (expect (caar (org-roam-db-query [:select (funcall count) :from links
+                                      :where (= to $s1)]
+                                     (test-org-roam--abs-path "unlinked.org"))) :to-be 0)
+    ;; TODO Test titles
+    (expect (org-roam-db-query [:select * :from titles])
+            :to-have-same-items-as
+            (list (list (test-org-roam--abs-path "alias.org")
+                        (list "t1" "a1" "a 2"))
+                  (list (test-org-roam--abs-path "bar.org")
+                        (list "Bar"))
+                  (list (test-org-roam--abs-path "foo.org")
+                        (list "Foo"))
+                  (list (test-org-roam--abs-path "nested/bar.org")
+                        (list "Nested Bar"))
+                  (list (test-org-roam--abs-path "nested/foo.org")
+                        (list "Nested Foo"))
+                  (list (test-org-roam--abs-path "no-title.org")
+                        (list "Headline title"))
+                  (list (test-org-roam--abs-path "web_ref.org") nil)
+                  (list (test-org-roam--abs-path "unlinked.org")
+                        (list "Unlinked"))))
+
+    (expect (org-roam-db-query [:select * :from refs])
+            :to-have-same-items-as
+            (list (list "https://google.com/" (test-org-roam--abs-path "web_ref.org") "website")))
+
+    ;; Expect rebuilds to be really quick (nothing changed)
+    (expect (org-roam-db-build-cache)
+            :to-equal
+            (list :files 0 :links 0 :tags 0 :titles 0 :refs 0 :deleted 0))))
+
+(provide 'test-org-roam)
+
+;;; test-org-roam.el ends here