nroam is a supplementary package for org-roam that replaces the backlink side buffer of Org-roam. Instead, it displays org-roam backlinks at the end of org-roam buffers.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

320 lines
11 KiB

;;; nroam.el --- Org-roam backlinks within org-mode buffers -*- lexical-binding: t; -*-
;; Copyright (C) 2021 Nicolas Petton
;; Author: Nicolas Petton <>
;; URL:
;; Keywords: outlines, convenience
;; Version: 0.0.1
;; Package-Requires: ((emacs "26.1") (org-roam "1.2.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 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
;; 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 <>.
;;; Commentary:
;; nroam is a supplementary package for org-roam that replaces the backlink side
;; buffer of Org-roam. Instead, it displays org-roam backlinks at the end of
;; org-roam buffers.
;; To setup nroam for all org-roam buffers, evaluate the following:
;; (add-hook 'org-mode-hook #'nroam-setup-maybe)
;;; Code:
(require 'org-roam)
(require 'org-roam-buffer)
(require 'org-element)
(require 'org-capture)
(require 'seq)
(require 'subr-x)
(require 'bookmark)
(defun nroam--handle-org-capture (&rest _)
"Setup the `org-capture' buffer.
Nroam sections need to be pruned as they are in read-only,
otherwise `org-capture' will fail to insert the capture
(when-let ((buf (org-capture-get :buffer)))
(with-current-buffer buf
(advice-add 'org-capture-place-template :before #'nroam--handle-org-capture)
(defcustom nroam-sections
"List of functions to be called to insert sections in nroam buffers."
:group 'nroam
:type '(repeat function))
(defvar-local nroam-start-marker nil)
(defvar-local nroam-end-marker nil)
(defvar nroam-work-buffer " *nroam-work*")
(defmacro with-nroam-markers (&rest body)
"Evaluate BODY.
Make the region inserted by BODY read-only, and marked with
`nroam-start-marker' and `nroam-end-marker'."
(declare (indent 0) (debug t))
`(let ((beg (point)))
(set-marker nroam-start-marker (point))
(put-text-property beg (1+ beg) 'front-sticky '(read-only))
(put-text-property beg (point) 'read-only t)
(set-marker nroam-end-marker (point))))
(defvar nroam-mode-map
(let ((map (make-sparse-keymap)))
(define-key map (kbd "C-c C-c") #'nroam-ctrl-c-ctrl-c)
(define-key map (kbd "RET") #'nroam-return)
(defun nroam-setup-maybe ()
"Setup nroam for the current buffer iff an org-roam buffer."
(when (nroam--org-roam-file-p)
(define-minor-mode nroam-mode
"Show nroam sections at the end of org-roam buffers."
:lighter "nroam"
:keymap nroam-mode-map
(if nroam-mode
(add-hook 'before-save-hook #'nroam--prune nil t)
(add-hook 'after-save-hook #'nroam--update-maybe nil t)
(remove-hook 'before-save-hook #'nroam--prune t)
(remove-hook 'after-save-hook #'nroam--update-maybe t)
(defun nroam-ctrl-c-ctrl-c ()
"Update the sections for the current buffer, or fallback to `org-ctrl-c-ctrl-c'."
(if (nroam--point-at-section-p)
(call-interactively (if org-capture-mode
(defun nroam-return ()
"Open nroam link at point, or fallback to `org-return'."
(if (nroam--point-at-section-p)
(call-interactively #'org-return)))
(defun nroam-update ()
"Update org-roam sections for the current buffer."
(defun nroam-backlinks-section ()
"Insert org-roam backlinks for the current buffer."
(let* ((backlinks (nroam--get-backlinks))
(groups (seq-reverse (nroam--group-backlinks backlinks))))
(nroam--insert-backlinks-heading (seq-length backlinks))
(nroam--do-separated-by-newlines #'nroam--insert-backlink-group groups)
(defun nroam--org-roam-file-p ()
"Return non-nil if the current buffer is an org-roam buffer."
(defun nroam--init-work-buffer ()
"Initiate nroam hidden buffer."
(get-buffer-create nroam-work-buffer)
(with-current-buffer nroam-work-buffer
(defun nroam--point-at-section-p ()
"Return non-hil if point if on the backlinks section."
(when (nroam--sections-inserted-p)
(when-let* ((beg (marker-position nroam-start-marker))
(end (marker-position nroam-end-marker)))
(<= beg (point) end))))
(defun nroam--update-maybe ()
"Update backlinks when in nroam-mode."
(when nroam-mode
(defun nroam--setup-markers ()
"Setup the current buffer with markers for nroam."
(unless (nroam--sections-inserted-p)
(setq nroam-start-marker (make-marker))
(setq nroam-end-marker (make-marker)))))
(defun nroam--sections-inserted-p ()
"Return non-nil if the current buffer has nroam sections inserted."
(and (markerp nroam-start-marker)
(marker-position nroam-start-marker)))
(defun nroam--prune ()
"Remove nroam sections from the current buffer."
(let ((inhibit-read-only t))
(goto-char (point-min))
(when (nroam--sections-inserted-p)
(delete-region nroam-start-marker nroam-end-marker))))))
(defun nroam--insert ()
"Insert nroam sections in the current buffer."
(let ((p (point-max)))
(goto-char p)
(unless (bobp)
(nroam--do-separated-by-newlines #'funcall nroam-sections))
(when (nroam--sections-inserted-p)
(narrow-to-region p (point-max))
(defun nroam--get-backlinks ()
"Return a list of backlinks for the current buffer."
(if-let* ((file-path (buffer-file-name (current-buffer)))
(titles (org-roam--extract-titles)))
(org-roam--get-backlinks (cons file-path titles))))
(defun nroam--group-backlinks (backlinks)
"Return BACKLINKS grouped by source file."
(seq-group-by #'car backlinks))
(defun nroam--insert-backlinks-heading (count)
"Insert the heading for the backlinks section with a COUNT."
(insert (if (= count 0)
"* No linked reference\n"
(format "* %s %s\n"
(nroam--pluralize count "linked reference")))))
(defun nroam--insert-backlink-group (group)
"Insert all backlinks in GROUP."
(let ((file (car group))
(backlinks (cdr group)))
(insert (format "** %s\n"
(org-roam-db--get-title file)
(nroam--do-separated-by-newlines #'nroam--insert-backlink backlinks)))
(defun nroam--insert-backlink (backlink)
"Insert a link to the org-roam BACKLINK."
(nroam--insert-source-content backlink))
(defun nroam--insert-source-content (backlink)
"Insert the source element where BACKLINK is defined."
(seq-let (file _ props) backlink
(when-let* ((point (plist-get props :point))
(elt (nroam--crawl-source file point))
(type (car elt))
(content (string-trim (cdr elt)))
(beg (point)))
(pcase type
('headline (progn
(org-paste-subtree 3 (nroam--fix-links content file))
(goto-char (point-max))))
(_ (insert (nroam--fix-links content file))))
(set-text-properties beg (point)
`(nroam-link t file ,file point ,point))
(insert "\n")))))
(defun nroam--crawl-source (file point)
"Return the source element in FILE at POINT."
(with-current-buffer nroam-work-buffer
(insert-file-contents file nil nil nil 'replace)
(goto-char point)
(let ((elt (org-element-at-point)))
(let ((begin (org-element-property :begin elt))
(end (org-element-property :end elt))
(type (org-element-type elt)))
`(,type . ,(buffer-substring begin end))))))
(defun nroam--fix-links (content origin)
"Correct all relative links in CONTENT from ORIGIN.
Temporary fix until `org-roam' v2 is out."
(org-roam-buffer-expand-links content origin))
(defun nroam--follow-link ()
"Follow backlink at point."
(when (get-text-property (point) 'nroam-link)
(let ((file (get-text-property (point) 'file))
(point (get-text-property (point) 'point)))
(org-open-file file t)
(goto-char point))))
(defun nroam--hide-drawers ()
"Fold all drawers starting at POINT in the current buffer."
;; Taken from `org-hide-drawer-all'.
(while (re-search-forward org-drawer-regexp nil t)
(let* ((pair (get-char-property-and-overlay (line-beginning-position)
(o (cdr-safe pair)))
(if (overlayp o) (goto-char (overlay-end o)) ;invisible drawer
(pcase (get-char-property-and-overlay (point) 'invisible)
(`(outline . ,o) (goto-char (overlay-end o))) ;already folded
(let* ((drawer (org-element-at-point))
(type (org-element-type drawer)))
(when (memq type '(drawer property-drawer))
(org-hide-drawer-toggle t nil drawer)
;; Make sure to skip drawer entirely or we might flag it
;; another time when matching its ending line with
;; `org-drawer-regexp'.
(goto-char (org-element-property :end drawer)))))))))))
(defun nroam--pluralize (n thing)
"Pluralize the string THING if N>1."
(format "%s%s"
(if (> n 1) "s" "")))
(defun nroam--ensure-empty-line ()
"Insert a newline character if the buffer does not end with a newline."
(let ((inhibit-read-only t))
(goto-char (point-max))
(unless (eq ?\n (char-before (1- (point)))) (insert "\n"))))
(defun nroam--do-separated-by-newlines (function sequence)
"Apply FUNCTION to each element of SEQUENCE.
Insert a single newline between each call to FUNCTION."
(seq-do-indexed (lambda (item index)
(unless (= index 0)
(funcall function item))
(provide 'nroam)
;;; nroam.el ends here