Skip to content

Latest commit

 

History

History
143 lines (95 loc) · 6.56 KB

README.org

File metadata and controls

143 lines (95 loc) · 6.56 KB

org-node-fakeroam

MELPA MELPA Stable

Intro

This package can be used in one of two ways: purely to speed up some parts of org-roam, or to use it side-by-side with org-node.

Either way, org-node-cache-mode must be enabled, and it’s a good idea to go through the following config.

Getting started

Let’s ensure that the underlying org-id system knows about the same files org-roam knows about. You’d think it would, but that isn’t a given!

There exists a command M-x org-roam-update-org-id-locations, but it only snapshots org-roam’s current state of information. Better to edit the following setting so it includes your org-roam-directory. Supposing that is “~/org”:

(setq org-node-extra-id-dirs '("~/org/"))

Run M-x org-node-reset, or restart Emacs.

Interop

These settings help you feel at home trying any org-node command:

(setq org-node-creation-fn #'org-node-fakeroam-new-via-roam-capture)
(setq org-node-slug-fn #'org-node-fakeroam-slugify-via-roam)
(setq org-node-datestamp-format "%Y%m%d%H%M%S-")

Bonus setup

Speeding up the backlinks buffer

Enable this mode:

(org-node-fakeroam-fast-render-mode) ;; build the Roam buffer faster

Optionally, you can further improve the experience by persisting on disk all the preview snippets.

(setq org-node-fakeroam-fast-render-persist t)

The only reason it’s not done by default is that it stores potentially world-readable text under “~/.emacs.d”, and it’s up to you to judge if that’s a problem.

You might think that this only matters to someone who often restarts Emacs, but the nature of notes is such that you can go months between revisits of a given note, and it’s so nice for the buffer to still be instant instead of only near-instant. YMMV; maybe your device is beefy enough anyway.

Speeding up the org-roam DB

If big files are slow to save, this section is for you. We will turn off some org-roam stuff and instruct it to look up org-node tables.

PROVISO: if you use the org-ref package, stop and reconsider! As mentioned on the main README, the org-node tables only collect a subset of org-ref v3 citations.

First, let’s stop the org-roam-db-autosync-mode from doing anything on save. Either turn it off, or apply the following settings.

(setq org-roam-db-update-on-save nil) ;; don't update DB on save, not needed
(setq org-roam-link-auto-replace nil) ;; don't look for "roam:" links on save

If you turn it off, you may want to enable the following mode. The autosync mode did a lot of unrelated things under one umbrella, such as this, which refreshes the visible Roam buffer when point moves into a different entry or the buffer changes.

(org-node-fakeroam-redisplay-mode) ;; autorefresh the Roam buffer

Now for the magic trick. Enable one or both of the following modes.

(org-node-fakeroam-jit-backlinks-mode) ;; skip DB for Roam buffer
(org-node-fakeroam-db-feed-mode) ;; keep Roam DB up to date

What do they do? First, the JIT-Backlinks-Mode will generate backlinks for the Roam buffer out of org-node’s tables, so that no DB is needed for this purpose.

Second, the DB-Feed-Mode keeps the org-roam DB up to date, by writing to it on save. Use it if you have various Roam extensions that need the DB. It should be pretty fast, but still not ideal in large files. (contributions welcome)

If you do not need the DB, I recommend skipping this last one. Then it will be good to delete the outdated org-roam.db file, due to a Roam hack mentioned in the org-node README.

Misc

Tip: Rebuilding the Roam DB

If you often have reason to full-reset the DB, there is a faster command. Benchmark on my device:

  • C-u M-x org-roam-db-sync: 179 seconds
  • M-x org-node-fakeroam-db-rebuild: 6 seconds

Fair warning: a couple of data points will differ.

  • (As mentioned earlier) Not all org-ref citations are picked up
  • Files’ recorded content-hash will be the blank string “”
  • Files’ recorded atime will be copied from the mtime
  • Each node will record its PROPERTIES drawer as it exists on disk, but not implicit properties like CATEGORY or TIMESTAMP_IA

This is a place where I request contributions, since 6 seconds still seems a lot slower than it needs to be. I envisioned running this function on every save – that’s obviously not possible yet. The bottleneck seems to be in how EmacSQL is being called.

Tip: On very slow filesystems

I hear that on Termux on Android, filesystem access can be so slow that it’s a pain to cycle dailies with org-roam (11 seconds just to goto next daily!).

Good news. You can override some functions to make them look up org-node tables and avoid the filesystem:

(advice-add #'org-roam-list-files :override
            #'org-node-fakeroam-list-files)

(advice-add #'org-roam-dailies--list-files :override
            #'org-node-fakeroam-list-dailies)

(advice-add #'org-roam-dailies--daily-note-p :override
            #'org-node-fakeroam-daily-note-p)

Tips on configuring org-roam

These tips have nothing to do with this package in specific, but it’s stuff I’d have liked to know.

Word-wrap in the org-roam buffer

If you don’t hard-wrap text but prefer visual-line-mode or similar, you have to enable such modes yourself – it sensibly doesn’t inherit your Org hooks (org-roam#1862):

(add-hook 'org-roam-mode-hook #'visual-line-mode)

Collapse sections by default

If you prefer the org-roam buffer to start in collapsed state:

(add-to-list 'org-roam-buffer-postrender-functions
             #'magit-section-show-level-2)