ci: Build manual preview on PRs

Not as convenient as a deploy preview, but better than nothing.

Link: https://github.com/orgs/community/discussions/7730

.github/workflows/docs.yml

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

.github/workflows/test.yml

@@ -1,7 +1,4 @@
-# * 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>.
@@ -23,7 +20,7 @@
 
 # * Code:
 
-name: "CI"
+name: CI
 on:
   pull_request:
   push:
@@ -47,10 +44,10 @@ jobs:
         with:
           version: ${{ matrix.emacs_version }}
 
-      - uses: actions/checkout@v2
-
       - name: Install Eldev
-        run: curl -fsSL https://raw.github.com/org-roam/org-roam/master/github-eldev | sh
+        uses: emacs-eldev/setup-eldev@v1
+
+      - uses: actions/checkout@v4
 
       - name: Install dependencies
         run: make prepare
@@ -60,6 +57,28 @@ jobs:
 
       - name: Test
         run: make test
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install deps
+        run: sudo apt install texinfo
+
+      - name: Build docs
+        run: make html
+
+      - name: Upload
+        uses: actions/upload-artifact@v4
+        with:
+          name: Docs
+          if-no-files-found: error
+          # TODO: optimize images
+          path: |
+            doc/
+            !doc/images/
+
 # Local Variables:
 # eval: (outline-minor-mode)
 # End:

.github/workflows/tidy-issues.yml

@@ -0,0 +1,93 @@
+name: 'Manage stale/dormant issues and PRs'
+
+on:
+  schedule:
+    - cron: '0 1 * * *'  # Daily at 1 AM UTC
+  workflow_dispatch:  # Allow this to be run manually
+    inputs:
+      dry_run:
+        description: 'Dry run: Show what would happen without making changes'
+        required: false
+        default: 'false'
+        type: boolean
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      # Handle stale issues/PRs
+      - name: Mark/close stale issues and PRs
+        uses: actions/stale@v9
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+          # Dry run setting
+          debug-only: ${{ github.event.inputs.dry_run == 'true' }}
+
+          # Messages
+          stale-issue-message: |
+            📅 **Stale Issue Notice**
+
+            This issue has been automatically marked as stale because it has not had recent activity for **6 months**.
+
+            **⏰ This issue will be closed in 2 weeks** if no further activity occurs.
+
+            **To keep this issue open:**
+            - Comment on this issue
+            - Reference it in a commit or PR
+            - Add new information or updates
+
+            Thank you for your contributions to org-roam! 🙏
+
+          close-issue-message: |
+            🔒 **Issue Automatically Closed**
+
+            This issue was automatically closed due to **6 months of inactivity** followed by 2 weeks notice.
+
+            **To reopen:**
+            - If still relevant, comment below and we'll reopen
+            - Or create a new issue with updated information
+
+            If this issue is not reopened in 2 weeks, it will be locked.
+            
+            This helps keep our issue tracker focused and manageable.
+
+          stale-pr-message: |
+            📅 **Stale Pull Request Notice**
+
+            This pull request has been automatically marked as stale because it has not had recent activity for **6 months**.
+
+            **⏰ This PR will be closed in 2 weeks** if no further activity occurs.
+
+            **To keep this PR open:**
+            - Push new commits
+            - Comment with updates
+            - Rebase on latest main branch
+
+            Thank you for your contributions to org-roam! 🙏
+
+          close-pr-message: |
+            🔒 **Pull Request Automatically Closed**
+
+            This pull request was automatically closed due to **6 months of inactivity** followed by 2 weeks notice.
+
+          # Timing (6 months + 2 weeks)
+          days-before-stale: 182  # ~6 months
+          days-before-close: 14   # 2 weeks notice
+
+          # Performance
+          operations-per-run: 1000
+
+      # Show dry run summary
+      - name: Dry run summary
+        if: github.event.inputs.dry_run == 'true'
+        run: |
+          echo "🧪 DRY RUN COMPLETED"
+          echo "This was a dry run - no actual changes were made."
+          echo "Check the action logs above to see what would have happened."
+          echo ""
+          echo "To run for real:"
+          echo "1. Go to Actions tab"
+          echo "2. Click 'Run workflow'"
+          echo "3. Leave 'Dry run mode' unchecked"
+          echo "4. Click 'Run workflow'"

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 2.3.1 (2025-06-26)
+
+* (fix): Use correct type specifications to suppress warnings by @okomestudio in https://github.com/org-roam/org-roam/pull/2522
+* perf: suppress extra org features in the temp buffer by @dustinfarris in https://github.com/org-roam/org-roam/pull/2524
+
 ## 2.3.0 (2025-05-24)
 
 * (perf)node-read: filter before map to candidate by @russmatney in https://github.com/org-roam/org-roam/pull/2168

Makefile

@@ -1,6 +1,7 @@
 .PHONY: clean
 clean:
 	eldev clean all
+	$(MAKE) -C doc clean
 
 .PHONY: prepare
 prepare:
@@ -14,16 +15,17 @@ lint:
 test:
 	eldev -C --unstable -T test
 
+.PHONY: docs
 docs:
-	make -C doc all
+	$(MAKE) -C doc
 
+.PHONY: html
 html:
-	make -C doc html-dir
+	$(MAKE) -C doc html
 
+.PHONY: install
 install: install-docs
 
-install-docs: docs
+.PHONY: install-docs
-	make -C doc install-docs
+install-docs:
-
+	$(MAKE) -C doc install
-install-info: info
-	make -C doc install-info

README.md

@@ -151,12 +151,9 @@ In both of the cases you will need to ensure that you have all the required
 dependencies. These include:
 
 - dash
-- f
-- s
 - org (9.6 is the minimum required version!)
 - emacsql
 - magit-section
-- filenotify-recursive
 
 After installing the package, you will need to properly setup `load-path` to the
 package:

default.mk

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

doc/AUTHORS.md

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

doc/Makefile

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

doc/org-roam.org

@@ -1,23 +1,25 @@
 #+title: Org-roam User Manual
 #+author: Jethro Kuan
 #+email: jethrokuan95@gmail.com
-#+date: 2020-2025
+#+date: 2020-{{{year}}}
 #+language: en
 
-#+texinfo_deffn: t
 #+texinfo_dir_category: Emacs
-#+texinfo_dir_title: Org-roam: (org-roam).
+#+texinfo_dir_name: Org-roam: (org-roam).
 #+texinfo_dir_desc: Roam Research for Emacs.
-#+subtitle: for version 2.3.0
+#+subtitle: for {{{version}}}
 
 #+options: H:4 num:3 toc:nil creator:t ':t
 #+property: header-args :eval never
+#+macro: version (eval (concat "version " (or (getenv "VERSION") (if-let* ((tag (ignore-errors (car (process-lines "git" "describe" "--tags" "--dirty=-devel" "--abbrev=0"))))) (replace-regexp-in-string "^v" "" tag) "<unknown>"))))
+#+macro: year (eval (format-time-string "%Y"))
 #+texinfo: @noindent
 
-This manual is for Org-roam version 2.3.0.
+This manual is for Org-roam {{{version}}}.
 
 #+BEGIN_QUOTE
-Copyright (C) 2020-2025 Jethro Kuan <jethrokuan95@gmail.com>
+Copyright (C) 2020-{{{year}}} Jethro Kuan <jethrokuan95@gmail.com> and the
+Org-roam contributors
 
 You can redistribute this document and/or modify it under the terms of the GNU
 General Public License as published by the Free Software Foundation, either
@@ -220,8 +222,6 @@ You now have Org-roam installed. However, you don't necessarily have the
 dependencies that it requires. These include:
 
 - dash
-- f
-- s
 - org
 - emacsql
 - magit-section
@@ -378,7 +378,7 @@ Node selection is achieved via the ~completing-read~ interface, typically
 through ~org-roam-node-read~. The presentation of these nodes are governed by
 ~org-roam-node-display-template~.
 
-- Variable: org-roam-node-display-template
+- Variable: org-roam-node-display-template ::
 
   Configures display formatting for Org-roam node.
 
@@ -458,7 +458,7 @@ additionally trying to process these links. Use
 ~org-roam-db-extra-links-elements~ to specify which additional Org AST element
 types to consider.
 
-- Variable: org-roam-db-extra-links-elements
+- Variable: org-roam-db-extra-links-elements ::
 
   The list of Org element types to include for parsing by Org-roam.
 
@@ -472,7 +472,7 @@ property drawers. For example, we would not want ~ROAM_REFS~ links to be
 self-referential. Hence, to exclude specific keys, we use
 ~org-roam-db-extra-links-exclude-keys~.
 
-- Variable: org-roam-db-extra-links-exclude-keys
+- Variable: org-roam-db-extra-links-exclude-keys ::
 
   Keys to ignore when mapping over links.
 
@@ -491,7 +491,7 @@ However, depending on how large your Org files are, database updating can be a
 slow operation. You can disable the automatic updating of the database by
 setting ~org-roam-db-update-on-save~ to ~nil~.
 
-- Variable: org-roam-db-update-on-save
+- Variable: org-roam-db-update-on-save ::
 
 If t, update the Org-roam database upon saving the file. Disable this if your
 files are large and updating the database is slow.
@@ -513,14 +513,14 @@ two main commands to use here:
 To bring up a buffer that tracks the current node at point, call ~M-x
 org-roam-buffer-toggle~.
 
-- Function: org-roam-buffer-toggle
+- Function: org-roam-buffer-toggle ::
 
   Toggle display of the ~org-roam-buffer~.
 
 To bring up a buffer that's dedicated for a specific node, call ~M-x
 org-roam-buffer-display-dedicated~.
 
-- Function: org-roam-buffer-display-dedicated
+- Function: org-roam-buffer-display-dedicated ::
 
   Launch node dedicated Org-roam buffer without visiting the node itself.
 
@@ -649,12 +649,12 @@ To assign an alias to a node, add the "ROAM_ALIASES" property to the node:
 
 Alternatively, Org-roam provides some functions to add or remove aliases.
 
-- Function: org-roam-alias-add alias
+- Function: org-roam-alias-add alias ::
 
   Add ALIAS to the node at point. When called interactively, prompt for the
   alias to add.
 
-- Function: org-roam-alias-remove
+- Function: org-roam-alias-remove ::
 
   Remove an alias from the node at point.
 
@@ -696,12 +696,12 @@ key and a URL at the same time.
 
 Org-roam also provides some functions to add or remove refs.
 
-- Function: org-roam-ref-add ref
+- Function: org-roam-ref-add ref ::
 
   Add REF to the node at point. When called interactively, prompt for the
   ref to add.
 
-- Function: org-roam-ref-remove
+- Function: org-roam-ref-remove ::
 
   Remove a ref from the node at point.
 
@@ -798,7 +798,7 @@ to ~t~:
 (setq org-roam-completion-everywhere t)
 #+end_src
 
-- Variable: org-roam-completion-everywhere
+- Variable: org-roam-completion-everywhere ::
 
 When non-nil, provide link completion matching outside of Org links.
 
@@ -1028,14 +1028,14 @@ If you're using the [[https://formulae.brew.sh/formula/emacs][Emacs Homebrew for
 
 a) Add option `-c` to `emacsclient` in the script, and start emacs from command line with `emacs --daemon`
 
-#+begin_src emacs-lisp
+  #+begin_src emacs-lisp
   on open location this_URL
       set EC to "/usr/local/bin/emacsclient -c --no-wait "
       set filePath to quoted form of this_URL
       do shell script EC & filePath & " &> /dev/null &"
       tell application "Emacs" to activate
   end open location
-#+end_src
+  #+end_src
 
 b) Add `(server-start)` in .emacs (in this case you do not need option `-c` for `emacsclient` in the script, and you do not need to start emacs with `emacs --daemon`
 
@@ -1129,7 +1129,7 @@ generating images using [[https://graphviz.org/][Graphviz]]. The graph can also
 
 The entry point to graph creation is ~org-roam-graph~.
 
-- Function: org-roam-graph & optional arg node
+- Function: org-roam-graph & optional arg node ::
 
 Build and display a graph for NODE.
 ARG may be any of the following values:
@@ -1138,7 +1138,7 @@ ARG may be any of the following values:
   - ~integer~   an integer argument ~N~ will show the graph for the connected
                 components to node up to ~N~ steps away.
 
-- User Option: org-roam-graph-executable
+- User Option: org-roam-graph-executable ::
 
   Path to the graphing executable (in this case, Graphviz). Set this if Org-roam
   is unable to find the Graphviz executable on your system.
@@ -1146,7 +1146,7 @@ ARG may be any of the following values:
   You may also choose to use ~neato~ in place of ~dot~, which generates a more
   compact graph layout.
 
-- User Option: org-roam-graph-viewer
+- User Option: org-roam-graph-viewer ::
 
   Org-roam defaults to using Firefox (located on PATH) to view the SVG, but you
   may choose to set it to:
@@ -1172,22 +1172,22 @@ Graphviz provides many options for customizing the graph output, and Org-roam
 supports some of them. See https://graphviz.gitlab.io/_pages/doc/info/attrs.html
 for customizable options.
 
-- User Option: org-roam-graph-filetype
+- User Option: org-roam-graph-filetype ::
 
   The file type to generate for graphs. This defaults to ~"svg"~.
 
-- User Option: org-roam-graph-extra-config
+- User Option: org-roam-graph-extra-config ::
 
   Extra options passed to graphviz for the digraph (The "G" attributes).
   Example: ~'~(("rankdir" . "LR"))~
 
-- User Option: org-roam-graph-node-extra-config
+- User Option: org-roam-graph-node-extra-config ::
 
   An alist of options to style the nodes.
   The car of the alist node type such as ~"id"~, or ~"http"~. The cdr of the
   list is another alist of Graphviz node options (the "N" attributes).
 
-- User Option: org-roam-graph-edge-extra-config
+- User Option: org-roam-graph-edge-extra-config ::
 
   Extra options for edges in the graphviz output (The "E" attributes).
   Example: ~'(("dir" . "back"))~
@@ -1201,11 +1201,11 @@ Org-journal with ~org-roam-dailies~.
 
 For ~org-roam-dailies~ to work, you need to define two variables:
 
-- Variable: ~org-roam-dailies-directory~
+- Variable: org-roam-dailies-directory ::
 
   Path to daily-notes. This path is relative to ~org-roam-directory~.
 
-- Variable: ~org-roam-dailies-capture-templates~
+- Variable: org-roam-dailies-capture-templates ::
 
   Capture templates for daily-notes in Org-roam.
 
@@ -1227,31 +1227,31 @@ See [[*The Templating System][The Templating System]] for creating new templates
 
 ~org-roam-dailies~ provides these interactive functions:
 
-- Function: ~org-roam-dailies-capture-today~ &optional goto
+- Function: org-roam-dailies-capture-today &optional goto ::
 
   Create an entry in the daily note for today.
 
   When ~goto~ is non-nil, go to the note without creating an entry.
 
-- Function: ~org-roam-dailies-goto-today~
+- Function: org-roam-dailies-goto-today ::
 
   Find the daily note for today, creating it if necessary.
 
 There are variants of those commands for ~-yesterday~ and ~-tomorrow~:
 
-- Function: ~org-roam-dailies-capture-yesterday~ n &optional goto
+- Function: org-roam-dailies-capture-yesterday n &optional goto ::
 
   Create an entry in the daily note for yesterday.
 
   With numeric argument ~n~, use the daily note ~n~ days in the past.
 
-- Function: ~org-roam-dailies-goto-yesterday~
+- Function: org-roam-dailies-goto-yesterday ::
 
   With numeric argument N, use the daily-note N days in the future.
 
 There are also commands which allow you to use Emacs’s ~calendar~ to find the date
 
-- Function: ~org-roam-dailies-capture-date~
+- Function: org-roam-dailies-capture-date ::
 
   Create an entry in the daily note for a date using the calendar.
 
@@ -1260,21 +1260,21 @@ There are also commands which allow you to use Emacs’s ~calendar~ to find the
   With a 'C-u' prefix or when ~goto~ is non-nil, go the note without
   creating an entry.
 
-- Function: ~org-roam-dailies-goto-date~
+- Function: org-roam-dailies-goto-date ::
 
   Find the daily note for a date using the calendar, creating it if necessary.
 
   Prefer past dates, unless ~prefer-future~ is non-nil.
 
-- Function: ~org-roam-dailies-find-directory~
+- Function: org-roam-dailies-find-directory ::
 
   Find and open ~org-roam-dailies-directory~.
 
-- Function: ~org-roam-dailies-goto-previous-note~
+- Function: org-roam-dailies-goto-previous-note ::
 
   When in an daily-note, find the previous one.
 
-- Function: ~org-roam-dailies-goto-next-note~
+- Function: org-roam-dailies-goto-next-note ::
 
   When in an daily-note, find the next one.
 ** org-roam-export
@@ -1664,13 +1664,12 @@ that extensions/customizations are robust to change, extensions should only use
 The node interface is cleanly defined using ~cl-defstruct~. The primary
 method to access nodes is ~org-roam-node-at-point~ and ~org-roam-node-read~:
 
-- Function: org-roam-node-at-point &optional assert
+- Function: org-roam-node-at-point &optional assert ::
 
   Return the node at point. If ASSERT, throw an error if there is no node at
   point.
 
-- Function: org-roam-node-read &optional initial-input filter-fn sort-fn
+- Function: org-roam-node-read &optional initial-input filter-fn sort-fn require-match ::
-  require-match
 
   Read and return an `org-roam-node'.
   INITIAL-INPUT is the initial minibuffer prompt value. FILTER-FN
@@ -1705,7 +1704,7 @@ Org-roam applies some patching over Org's capture system to smooth out the user
 experience, and sometimes it is desirable to use Org-roam's capturing system
 instead. The exposed function to be used in extensions is ~org-roam-capture-~:
 
-- Function: org-roam-capture- &key goto keys node info props templates
+- Function: org-roam-capture- &key goto keys node info props templates ::
 
   Main entry point.
   GOTO and KEYS correspond to `org-capture' arguments.
@@ -1735,7 +1734,8 @@ When GOTO is non-nil, go the note without creating an entry."
 :END:
 
 #+BEGIN_QUOTE
-Copyright (C) 2020-2025 Jethro Kuan <jethrokuan95@gmail.com>
+Copyright (C) 2020-{{{year}}} Jethro Kuan <jethrokuan95@gmail.com> and the
+Org-roam contributors
 
 You can redistribute this document and/or modify it under the terms
 of the GNU General Public License as published by the Free Software
@@ -1796,9 +1796,9 @@ an Org file code block (like =#+BEGIN_SRC emacs-lisp=).
 
 # Local Variables:
 # eval: (require 'ol-info)
-# eval: (require 'ox-texinfo+ nil t)
 # eval: (auto-fill-mode +1)
-# after-save-hook: (lambda nil (progn (require 'ox-texinfo nil t) (org-texinfo-export-to-info)))
+# after-save-hook: org-texinfo-export-to-info
 # indent-tabs-mode: nil
 # org-src-preserve-indentation: nil
+# org-list-allow-alphabetical: t
 # End:

doc/org-roam.texi

@@ -8,7 +8,8 @@
 
 @copying
 @quotation
-Copyright (C) 2020-2025 Jethro Kuan <jethrokuan95@@gmail.com>
+Copyright (C) 2020-2025 Jethro Kuan <jethrokuan95@@gmail.com> and the
+Org-roam contributors
 
 You can redistribute this document and/or modify it under the terms
 of the GNU General Public License as published by the Free Software
@@ -31,7 +32,7 @@ General Public License for more details.
 @finalout
 @titlepage
 @title Org-roam User Manual
-@subtitle for version 2.3.0
+@subtitle for version 2.3.1-devel
 @author Jethro Kuan
 @page
 @vskip 0pt plus 1filll
@@ -44,10 +45,11 @@ General Public License for more details.
 
 @noindent
 
-This manual is for Org-roam version 2.3.0.
+This manual is for Org-roam version 2.3.1-devel.
 
 @quotation
-Copyright (C) 2020-2025 Jethro Kuan <jethrokuan95@@gmail.com>
+Copyright (C) 2020-2025 Jethro Kuan <jethrokuan95@@gmail.com> and the
+Org-roam contributors
 
 You can redistribute this document and/or modify it under the terms of the GNU
 General Public License as published by the Free Software Foundation, either
@@ -433,10 +435,6 @@ dependencies that it requires. These include:
 @item
 dash
 @item
-f
-@item
-s
-@item
 org
 @item
 emacsql
@@ -626,10 +624,7 @@ Node selection is achieved via the @code{completing-read} interface, typically
 through @code{org-roam-node-read}. The presentation of these nodes are governed by
 @code{org-roam-node-display-template}.
 
-@itemize
+@defvar org-roam-node-display-template
-@item
-Variable: org-roam-node-display-template
-
 Configures display formatting for Org-roam node.
 
 Patterns of form ``$@{field-name:length@}'' are interpolated based
@@ -658,7 +653,7 @@ as many characters as possible and will be aligned accordingly.
 A closure can also be assigned to this variable in which case the
 closure is evaluated and the return value is used as the
 template. The closure must evaluate to a valid template string.
-@end itemize
+@end defvar
 
 If you're using a vertical completion framework, such as Ivy and Selectrum,
 Org-roam supports the generation of an aligned, tabular completion interface.
@@ -720,33 +715,27 @@ additionally trying to process these links. Use
 @code{org-roam-db-extra-links-elements} to specify which additional Org AST element
 types to consider.
 
-@itemize
+@defvar org-roam-db-extra-links-elements
-@item
-Variable: org-roam-db-extra-links-elements
-
 The list of Org element types to include for parsing by Org-roam.
 
 By default, when parsing Org's AST, links within keywords and
 property drawers are not parsed as links. Sometimes however, it
 is desirable to parse and cache these links (e.g. hiding links in
 a property drawer).
-@end itemize
+@end defvar
 
 Additionally, one may want to ignore certain keys from being excluded within
 property drawers. For example, we would not want @code{ROAM_REFS} links to be
 self-referential. Hence, to exclude specific keys, we use
 @code{org-roam-db-extra-links-exclude-keys}.
 
-@itemize
+@defvar org-roam-db-extra-links-exclude-keys
-@item
-Variable: org-roam-db-extra-links-exclude-keys
-
 Keys to ignore when mapping over links.
 
 The car of the association list is the Org element type (e.g. keyword). The
 cdr is a list of case-insensitive strings to exclude from being treated as
 links.
-@end itemize
+@end defvar
 
 @node When to cache
 @section When to cache
@@ -760,11 +749,8 @@ However, depending on how large your Org files are, database updating can be a
 slow operation. You can disable the automatic updating of the database by
 setting @code{org-roam-db-update-on-save} to @code{nil}.
 
-@itemize
+@defvar org-roam-db-update-on-save
-@item
+@end defvar
-Variable: org-roam-db-update-on-save
-@end itemize
-
 If t, update the Org-roam database upon saving the file. Disable this if your
 files are large and updating the database is slow.
 
@@ -790,22 +776,16 @@ new node at point.
 To bring up a buffer that tracks the current node at point, call @code{M-x
 org-roam-buffer-toggle}.
 
-@itemize
+@defun org-roam-buffer-toggle
-@item
-Function: org-roam-buffer-toggle
-
 Toggle display of the @code{org-roam-buffer}.
-@end itemize
+@end defun
 
 To bring up a buffer that's dedicated for a specific node, call @code{M-x
 org-roam-buffer-display-dedicated}.
 
-@itemize
+@defun org-roam-buffer-display-dedicated
-@item
-Function: org-roam-buffer-display-dedicated
-
 Launch node dedicated Org-roam buffer without visiting the node itself.
-@end itemize
+@end defun
 
 @menu
 * Navigating the Org-roam Buffer::
@@ -978,18 +958,14 @@ To assign an alias to a node, add the ``ROAM@math{_ALIASES}'' property to the no
 
 Alternatively, Org-roam provides some functions to add or remove aliases.
 
-@itemize
+@defun org-roam-alias-add alias
-@item
-Function: org-roam-alias-add alias
-
 Add ALIAS to the node at point. When called interactively, prompt for the
 alias to add.
+@end defun
 
-@item
+@defun org-roam-alias-remove
-Function: org-roam-alias-remove
-
 Remove an alias from the node at point.
-@end itemize
+@end defun
 
 @node Tags
 @section Tags
@@ -1031,18 +1007,14 @@ key and a URL at the same time.
 
 Org-roam also provides some functions to add or remove refs.
 
-@itemize
+@defun org-roam-ref-add ref
-@item
-Function: org-roam-ref-add ref
-
 Add REF to the node at point. When called interactively, prompt for the
 ref to add.
+@end defun
 
-@item
+@defun org-roam-ref-remove
-Function: org-roam-ref-remove
-
 Remove a ref from the node at point.
-@end itemize
+@end defun
 
 @node Citations
 @chapter Citations
@@ -1155,11 +1127,8 @@ to @code{t}:
 (setq org-roam-completion-everywhere t)
 @end lisp
 
-@itemize
+@defvar org-roam-completion-everywhere
-@item
+@end defvar
-Variable: org-roam-completion-everywhere
-@end itemize
-
 When non-nil, provide link completion matching outside of Org links.
 
 @node Encryption
@@ -1458,7 +1427,6 @@ If you're using the @uref{https://formulae.brew.sh/formula/emacs, Emacs Homebrew
 @enumerate
 @item
 Add option `-c` to `emacsclient` in the script, and start emacs from command line with `emacs --daemon`
-@end enumerate
 
 @lisp
 on open location this_URL
@@ -1469,7 +1437,6 @@ on open location this_URL
 end open location
 @end lisp
 
-@enumerate
 @item
 Add `(server-start)` in .emacs (in this case you do not need option `-c` for `emacsclient` in the script, and you do not need to start emacs with `emacs --daemon`
 @end enumerate
@@ -1574,11 +1541,8 @@ generating images using @uref{https://graphviz.org/, Graphviz}. The graph can al
 
 The entry point to graph creation is @code{org-roam-graph}.
 
-@itemize
+@defun org-roam-graph & optional arg node
-@item
+@end defun
-Function: org-roam-graph & optional arg node
-@end itemize
-
 Build and display a graph for NODE@.
 ARG may be any of the following values:
 
@@ -1590,19 +1554,15 @@ ARG may be any of the following values:
 components to node up to @code{N} steps away.
 @end itemize
 
-@itemize
+@defopt org-roam-graph-executable
-@item
-User Option: org-roam-graph-executable
-
 Path to the graphing executable (in this case, Graphviz). Set this if Org-roam
 is unable to find the Graphviz executable on your system.
 
 You may also choose to use @code{neato} in place of @code{dot}, which generates a more
 compact graph layout.
+@end defopt
 
-@item
+@defopt org-roam-graph-viewer
-User Option: org-roam-graph-viewer
-
 Org-roam defaults to using Firefox (located on PATH) to view the SVG, but you
 may choose to set it to:
 
@@ -1624,7 +1584,7 @@ the second option to set the browser and network file path:
       (let ((org-roam-graph-viewer "/mnt/c/Program Files/Mozilla Firefox/firefox.exe"))
         (org-roam-graph--open (concat "file://///wsl$/Ubuntu" file)))))
 @end lisp
-@end itemize
+@end defopt
 
 @menu
 * Graph Options::
@@ -1637,31 +1597,25 @@ Graphviz provides many options for customizing the graph output, and Org-roam
 supports some of them. See @uref{https://graphviz.gitlab.io/_pages/doc/info/attrs.html}
 for customizable options.
 
-@itemize
+@defopt org-roam-graph-filetype
-@item
-User Option: org-roam-graph-filetype
-
 The file type to generate for graphs. This defaults to @code{"svg"}.
+@end defopt
 
-@item
+@defopt org-roam-graph-extra-config
-User Option: org-roam-graph-extra-config
-
 Extra options passed to graphviz for the digraph (The ``G'' attributes).
 Example: @code{'~(("rankdir" . "LR"))}
+@end defopt
 
-@item
+@defopt org-roam-graph-node-extra-config
-User Option: org-roam-graph-node-extra-config
-
 An alist of options to style the nodes.
 The car of the alist node type such as @code{"id"}, or @code{"http"}. The cdr of the
 list is another alist of Graphviz node options (the ``N'' attributes).
+@end defopt
 
-@item
+@defopt org-roam-graph-edge-extra-config
-User Option: org-roam-graph-edge-extra-config
-
 Extra options for edges in the graphviz output (The ``E'' attributes).
 Example: @code{'(("dir" . "back"))}
-@end itemize
+@end defopt
 
 @node org-roam-dailies
 @section org-roam-dailies
@@ -1679,17 +1633,13 @@ Org-journal with @code{org-roam-dailies}.
 
 For @code{org-roam-dailies} to work, you need to define two variables:
 
-@itemize
+@defvar org-roam-dailies-directory
-@item
-Variable: @code{org-roam-dailies-directory}
-
 Path to daily-notes. This path is relative to @code{org-roam-directory}.
+@end defvar
 
-@item
+@defvar org-roam-dailies-capture-templates
-Variable: @code{org-roam-dailies-capture-templates}
-
 Capture templates for daily-notes in Org-roam.
-@end itemize
+@end defvar
 
 Here is a sane default configuration:
 
@@ -1710,71 +1660,56 @@ See @ref{The Templating System} for creating new templates.
 
 @code{org-roam-dailies} provides these interactive functions:
 
-@itemize
+@defun org-roam-dailies-capture-today &optional goto
-@item
-Function: @code{org-roam-dailies-capture-today} &optional goto
-
 Create an entry in the daily note for today.
 
 When @code{goto} is non-nil, go to the note without creating an entry.
+@end defun
 
-@item
+@defun org-roam-dailies-goto-today
-Function: @code{org-roam-dailies-goto-today}
-
 Find the daily note for today, creating it if necessary.
-@end itemize
+@end defun
 
 There are variants of those commands for @code{-yesterday} and @code{-tomorrow}:
 
-@itemize
+@defun org-roam-dailies-capture-yesterday n &optional goto
-@item
-Function: @code{org-roam-dailies-capture-yesterday} n &optional goto
-
 Create an entry in the daily note for yesterday.
 
 With numeric argument @code{n}, use the daily note @code{n} days in the past.
+@end defun
 
-@item
+@defun org-roam-dailies-goto-yesterday
-Function: @code{org-roam-dailies-goto-yesterday}
-
 With numeric argument N, use the daily-note N days in the future.
-@end itemize
+@end defun
 
 There are also commands which allow you to use Emacs’s @code{calendar} to find the date
 
-@itemize
+@defun org-roam-dailies-capture-date
-@item
-Function: @code{org-roam-dailies-capture-date}
-
 Create an entry in the daily note for a date using the calendar.
 
 Prefer past dates, unless @code{prefer-future} is non-nil.
 
 With a 'C-u' prefix or when @code{goto} is non-nil, go the note without
 creating an entry.
+@end defun
 
-@item
+@defun org-roam-dailies-goto-date
-Function: @code{org-roam-dailies-goto-date}
-
 Find the daily note for a date using the calendar, creating it if necessary.
 
 Prefer past dates, unless @code{prefer-future} is non-nil.
+@end defun
 
-@item
+@defun org-roam-dailies-find-directory
-Function: @code{org-roam-dailies-find-directory}
-
 Find and open @code{org-roam-dailies-directory}.
+@end defun
 
-@item
+@defun org-roam-dailies-goto-previous-note
-Function: @code{org-roam-dailies-goto-previous-note}
-
 When in an daily-note, find the previous one.
+@end defun
 
-@item
+@defun org-roam-dailies-goto-next-note
-Function: @code{org-roam-dailies-goto-next-note}
-
 When in an daily-note, find the next one.
-@end itemize
+@end defun
 
 @node org-roam-export
 @section org-roam-export
@@ -2283,17 +2218,12 @@ that extensions/customizations are robust to change, extensions should only use
 The node interface is cleanly defined using @code{cl-defstruct}. The primary
 method to access nodes is @code{org-roam-node-at-point} and @code{org-roam-node-read}:
 
-@itemize
+@defun org-roam-node-at-point &optional assert
-@item
-Function: org-roam-node-at-point &optional assert
-
 Return the node at point. If ASSERT, throw an error if there is no node at
 point.
+@end defun
 
-@item
+@defun org-roam-node-read &optional initial-input filter-fn sort-fn require-match
-Function: org-roam-node-read &optional initial-input filter-fn sort-fn
-require-match
-
 Read and return an `org-roam-node'.
 INITIAL-INPUT is the initial minibuffer prompt value. FILTER-FN
 is a function to filter out nodes: it takes a single argument (an
@@ -2302,7 +2232,7 @@ filtered out.
 SORT-FN is a function to sort nodes. See @code{org-roam-node-read-sort-by-file-mtime}
 for an example sort function.
 If REQUIRE-MATCH, the minibuffer prompt will require a match.
-@end itemize
+@end defun
 
 Once you obtain the node, you can use the accessors for the node, e.g.
 @code{org-roam-node-id} or @code{org-roam-node-todo}.
@@ -2329,17 +2259,14 @@ Org-roam applies some patching over Org's capture system to smooth out the user
 experience, and sometimes it is desirable to use Org-roam's capturing system
 instead. The exposed function to be used in extensions is @code{org-roam-capture-}:
 
-@itemize
+@defun org-roam-capture- &key goto keys node info props templates
-@item
-Function: org-roam-capture- &key goto keys node info props templates
-
 Main entry point.
 GOTO and KEYS correspond to `org-capture' arguments.
 INFO is a plist for filling up Org-roam's capture templates.
 NODE is an `org-roam-node' construct containing information about the node.
 PROPS is a plist containing additional Org-roam properties for each template.
 TEMPLATES is a list of org-roam templates.
-@end itemize
+@end defun
 
 An example of an extension using @code{org-roam-capture-} is @code{org-roam-dailies}
 itself:
@@ -2421,5 +2348,5 @@ When GOTO is non-nil, go the note without creating an entry."
 
 @printindex vr
 
-Emacs 30.1 (Org mode 9.7.29)
+Emacs 30.1.90 (Org mode 9.7.25)
 @bye

extensions/org-roam-dailies.el

@@ -7,7 +7,7 @@
 ;;      Leo Vivier <leo.vivier+dev@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 2.3.0
+;; Version: 2.3.1
 ;; Package-Requires: ((emacs "26.1") (dash "2.13") (org-roam "2.1"))
 
 ;; This file is NOT part of GNU Emacs.

extensions/org-roam-export.el

@@ -5,7 +5,7 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 2.3.0
+;; Version: 2.3.1
 ;; Package-Requires: ((emacs "26.1") (org "9.6") (org-roam "2.1"))
 
 ;; This file is NOT part of GNU Emacs.

extensions/org-roam-graph.el

@@ -5,7 +5,7 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 2.3.0
+;; Version: 2.3.1
 ;; Package-Requires: ((emacs "26.1") (org "9.6") (org-roam "2.1"))
 
 ;; This file is NOT part of GNU Emacs.

extensions/org-roam-overlay.el

@@ -5,7 +5,7 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 2.3.0
+;; Version: 2.3.1
 ;; Package-Requires: ((emacs "26.1") (org "9.6") (org-roam "2.1"))
 
 ;; This file is NOT part of GNU Emacs.

extensions/org-roam-protocol.el

@@ -4,7 +4,7 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 2.3.0
+;; Version: 2.3.1
 ;; Package-Requires: ((emacs "26.1") (org "9.6") (org-roam "2.1"))
 
 ;; This file is NOT part of GNU Emacs.

github-eldev

@@ -1,11 +0,0 @@
-#! /bin/sh
-set -e
-
-ELDEV_BIN_DIR=~/.local/bin
-
-# `$GITHUB_PATH' is a magic file which contents is translated to environment variable `$PATH'.
-echo "$ELDEV_BIN_DIR" >> $GITHUB_PATH
-
-mkdir -p $ELDEV_BIN_DIR
-curl -fsSL https://raw.githubusercontent.com/doublep/eldev/f111d19cda305e5e8fcb70a5675b87173041cb68/bin/eldev > $ELDEV_BIN_DIR/eldev
-chmod a+x $ELDEV_BIN_DIR/eldev

org-roam-capture.el

@@ -5,7 +5,7 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 2.3.0
+;; Version: 2.3.1
 ;; Package-Requires: ((emacs "26.1") (dash "2.13") (org "9.6") (emacsql "4.1.0") (magit-section "3.0.0"))
 
 ;; This file is NOT part of GNU Emacs.

org-roam-compat.el

@@ -5,7 +5,7 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 2.3.0
+;; Version: 2.3.1
 ;; Package-Requires: ((emacs "26.1"))
 
 ;; This file is NOT part of GNU Emacs.

org-roam-db.el

@@ -5,7 +5,7 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 2.3.0
+;; Version: 2.3.1
 ;; Package-Requires: ((emacs "26.1") (dash "2.13") (org "9.6") (emacsql "4.1.0") (magit-section "3.0.0"))
 
 ;; This file is NOT part of GNU Emacs.
@@ -655,12 +655,14 @@ database, see `org-roam-db-sync' command."
       (add-hook 'kill-emacs-hook #'org-roam-db--close-all)
       (advice-add #'rename-file :after  #'org-roam-db-autosync--rename-file-a)
       (advice-add #'delete-file :before #'org-roam-db-autosync--delete-file-a)
+      (advice-add #'vc-delete-file :around #'org-roam-db-autosync--vc-delete-file-a)
       (org-roam-db-sync))
      (t
       (remove-hook 'find-file-hook  #'org-roam-db-autosync--setup-file-h)
       (remove-hook 'kill-emacs-hook #'org-roam-db--close-all)
       (advice-remove #'rename-file #'org-roam-db-autosync--rename-file-a)
       (advice-remove #'delete-file #'org-roam-db-autosync--delete-file-a)
+      (advice-remove #'vc-delete-file #'org-roam-db-autosync--vc-delete-file-a)
       (org-roam-db--close-all)
       ;; Disable local hooks for all org-roam buffers
       (dolist (buf (org-roam-buffer-list))
@@ -688,6 +690,17 @@ FILE is removed from the database."
              (org-roam-file-p file))
     (org-roam-db-clear-file (expand-file-name file))))
 
+(defun org-roam-db-autosync--vc-delete-file-a (fun file)
+  "Maintain cache consistency on file deletion by FUN.
+FILE is removed from the database."
+  (let ((org-roam-file-p (and (not (auto-save-file-name-p file))
+                              (not (backup-file-name-p file))
+                              (org-roam-file-p file))))
+    (apply fun `(,file))
+    (when (and org-roam-file-p
+               (not (file-exists-p file)))
+      (org-roam-db-clear-file (expand-file-name file)))))
+
 (defun org-roam-db-autosync--rename-file-a (old-file new-file-or-dir &rest _args)
   "Maintain cache consistency of file rename.
 OLD-FILE is cleared from the database, and NEW-FILE-OR-DIR is added."

org-roam-id.el

@@ -5,7 +5,7 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 2.3.0
+;; Version: 2.3.1
 ;; Package-Requires: ((emacs "26.1") (dash "2.13") (org "9.6") (magit-section "3.0.0"))
 
 ;; This file is NOT part of GNU Emacs.

org-roam-log.el

@@ -5,7 +5,7 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 2.3.0
+;; Version: 2.3.1
 ;; Package-Requires: ((emacs "26.1") (dash "2.13") (org "9.6") (emacsql "4.1.0") (magit-section "3.0.0"))
 
 ;; This file is NOT part of GNU Emacs.

org-roam-migrate.el

@@ -5,7 +5,7 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 2.3.0
+;; Version: 2.3.1
 ;; Package-Requires: ((emacs "26.1") (dash "2.13") (org "9.6") (emacsql "4.1.0") (magit-section "3.0.0"))
 
 ;; This file is NOT part of GNU Emacs.

org-roam-mode.el

@@ -5,7 +5,7 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 2.3.0
+;; Version: 2.3.1
 ;; Package-Requires: ((emacs "26.1") (dash "2.13") (org "9.6") (emacsql "4.1.0") (magit-section "3.0.0"))
 
 ;; This file is NOT part of GNU Emacs.
@@ -658,17 +658,26 @@ This is the ROW within FILE."
        (end-of-line)
        (point)))))
 
-(defun org-roam-unlinked-references--rg-command (titles)
+(defun org-roam-unlinked-references--rg-command (titles temp-file)
-  "Return the ripgrep command searching for TITLES."
+  "Return the ripgrep command searching for TITLES using TEMP-FILE for pattern.
+This avoids shell escaping issues by writing the pattern to a file instead
+of passing it directly through the shell command line."
+  ;; Write pattern to temp file to avoid shell escaping issues with quotes,
+  ;; spaces, and other special characters in titles
+  (with-temp-file temp-file
+    (insert "\\[([^[]]++|(?R))*\\]"
+            (mapconcat (lambda (title)
+                         ;; Use regexp-quote instead of shell-quote-argument
+                         ;; since we're writing a regex pattern, not a shell argument
+                         (format "|(\\b%s\\b)" (regexp-quote title)))
+                       titles "")))
+
   (concat "rg --follow --only-matching --vimgrep --pcre2 --ignore-case "
           (mapconcat (lambda (glob) (concat "--glob " glob))
                      (org-roam--list-files-search-globs org-roam-file-extensions)
                      " ")
-          (format " '\\[([^[]]++|(?R))*\\]%s' "
+          " --file " (shell-quote-argument temp-file) " "
-                  (mapconcat (lambda (title)
+          (shell-quote-argument (expand-file-name org-roam-directory))))
-                               (format "|(\\b%s\\b)" (shell-quote-argument title)))
-                             titles ""))
-          (shell-quote-argument org-roam-directory)))
 
 (defun org-roam-unlinked-references-section (node)
   "The unlinked references section for NODE.
@@ -679,33 +688,39 @@ References from FILE are excluded."
                                 (shell-command-to-string "rg --pcre2-version"))))
     (let* ((titles (cons (org-roam-node-title node)
                          (org-roam-node-aliases node)))
-           (rg-command (org-roam-unlinked-references--rg-command titles))
+           ;; Create temp file for the regex pattern
-           (results (split-string (shell-command-to-string rg-command) "\n"))
+           (temp-file (make-temp-file "org-roam-rg-pattern-"))
-           f row col match)
+           (rg-command (org-roam-unlinked-references--rg-command titles temp-file)))
-      (magit-insert-section (unlinked-references)
+      ;; Use unwind-protect to ensure temp file cleanup even if errors occur
-        (magit-insert-heading "Unlinked References:")
+      (unwind-protect
-        (dolist (line results)
+          (let* ((results (split-string (shell-command-to-string rg-command) "\n"))
-          (save-match-data
+                 f row col match)
-            (when (string-match org-roam-unlinked-references-result-re line)
+            (magit-insert-section (unlinked-references)
-              (setq f (match-string 1 line)
+              (magit-insert-heading "Unlinked References:")
-                    row (string-to-number (match-string 2 line))
+              (dolist (line results)
-                    col (string-to-number (match-string 3 line))
+                (save-match-data
-                    match (match-string 4 line))
+                  (when (string-match org-roam-unlinked-references-result-re line)
-              (when (and match
+                    (setq f (match-string 1 line)
-                         (not (file-equal-p (org-roam-node-file node) f))
+                          row (string-to-number (match-string 2 line))
-                         (member (downcase match) (mapcar #'downcase titles)))
+                          col (string-to-number (match-string 3 line))
-                (magit-insert-section section (org-roam-grep-section)
+                          match (match-string 4 line))
-                  (oset section file f)
+                    (when (and match
-                  (oset section row row)
+                               (not (file-equal-p (org-roam-node-file node) f))
-                  (oset section col col)
+                               (member (downcase match) (mapcar #'downcase titles)))
-                  (insert (propertize (format "%s:%s:%s"
+                      (magit-insert-section section (org-roam-grep-section)
-                                              (truncate-string-to-width (file-name-base f) 15 nil nil t)
+                        (oset section file f)
-                                              row col) 'font-lock-face 'org-roam-dim)
+                        (oset section row row)
-                          " "
+                        (oset section col col)
-                          (org-roam-fontify-like-in-org-mode
+                        (insert (propertize (format "%s:%s:%s"
-                           (org-roam-unlinked-references-preview-line f row))
+                                                    (truncate-string-to-width (file-name-base f) 15 nil nil t)
-                          "\n"))))))
+                                                    row col) 'font-lock-face 'org-roam-dim)
-        (insert ?\n)))))
+                                " "
+                                (org-roam-fontify-like-in-org-mode
+                                 (org-roam-unlinked-references-preview-line f row))
+                                "\n"))))))
+              (insert ?\n)))
+        ;; Clean up temp file - this runs even if an error occurs above
+        (delete-file temp-file)))))
 
 (provide 'org-roam-mode)
 ;;; org-roam-mode.el ends here

org-roam-node.el

@@ -5,7 +5,7 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 2.3.0
+;; Version: 2.3.1
 ;; Package-Requires: ((emacs "26.1") (dash "2.13") (org "9.6") (magit-section "3.0.0"))
 
 ;; This file is NOT part of GNU Emacs.
@@ -39,6 +39,16 @@
 ;;;; Completing-read
 (defcustom org-roam-node-display-template "${title}"
   "Configures display formatting for Org-roam node.
+
+If it is a function, it will be called to format a node.
+Its result is expected to be a string (potentially with
+embedded properties).
+
+If it is a string and it will be used as described in org-roam
+ (see org-roam-node-display-template)
+
+When it is a string, the following processing is done:
+
 Patterns of form \"${field-name:length}\" are interpolated based
 on the current node.
 
@@ -64,9 +74,23 @@ as many characters as possible and will be aligned accordingly.
 
 A closure can also be assigned to this variable in which case the
 closure is evaluated and the return value is used as the
-template. The closure must evaluate to a valid template string."
+template. The closure must evaluate to a valid template string.
+
+When org-roam-node-display-template is a function, the function is
+expected to return a string, potentially propertized. For example, the
+following function shows the title and base filename of the node:
+
+\(defun my--org-roam-format (node)
+  \"formats the node\"
+  (format \"%-40s %s\"
+          (if (org-roam-node-title node)
+              (propertize (org-roam-node-title node) 'face 'org-todo)
+            \"\")
+          (file-name-nondirectory (org-roam-node-file node))))
+
+\q(setq org-roam-node-display-template 'my--org-roam-format)"
   :group 'org-roam
-  :type  '(string function))
+  :type  '(choice string function))
 
 (defcustom org-roam-node-annotation-function #'org-roam-node-read--annotation
   "This function used to attach annotations for `org-roam-node-read'.
@@ -90,7 +114,7 @@ argument, an `org-roam-node', and return a string.
 If a string is provided, it is a template string expanded by
 `org-roam-node--format-entry'."
   :group 'org-roam
-  :type '(string function))
+  :type '(choice string function))
 
 (defcustom org-roam-node-template-prefixes
   '(("tags" . "#")
@@ -143,6 +167,10 @@ This path is relative to `org-roam-directory'."
   :group 'org-roam
   :type 'string)
 
+(defvar org-roam-link-type "roam"
+  "Link type for org-roam nodes.
+Replaced by `id' automatically when `org-roam-link-auto-replace' is non-nil.")
+
 (defvar org-roam-node-history nil
   "Minibuffer history of nodes.")
 
@@ -151,6 +179,11 @@ This path is relative to `org-roam-directory'."
 
 ;;; Definition
 (cl-defstruct (org-roam-node (:constructor org-roam-node-create)
+                             (:constructor org-roam-node-create-from-db
+                                           (title aliases                    ; 2
+                                                  id file file-title level todo     ; 5
+                                                  point priority scheduled deadline properties ;;5
+                                                  olp file-atime file-mtime tags refs)) ;;5
                              (:copier nil))
   "A heading or top level file with an assigned ID property."
   file file-title file-hash file-atime file-mtime
@@ -352,23 +385,27 @@ nodes."
 (defun org-roam-node-list ()
   "Return all nodes stored in the database as a list of `org-roam-node's."
   (let ((rows (org-roam-db-query
-               "SELECT
+               "
+SELECT
+  title,
+  aliases,
+
   id,
   file,
   filetitle,
   \"level\",
   todo,
+
   pos,
   priority ,
   scheduled ,
   deadline ,
-  title,
   properties ,
+
   olp,
   atime,
   mtime,
   '(' || group_concat(tags, ' ') || ')' as tags,
-  aliases,
   refs
 FROM
   (
@@ -417,32 +454,20 @@ FROM
     LEFT JOIN refs ON refs.node_id = nodes.id
     GROUP BY nodes.id, tags.tag, aliases.alias )
   GROUP BY id, tags )
-GROUP BY id")))
+GROUP BY id
-    (cl-loop for row in rows
+")))
-             append (pcase-let* ((`(
+    (mapcan
-                                    ,id ,file ,file-title ,level ,todo ,pos ,priority ,scheduled ,deadline
+     (lambda (row)
-                                    ,title ,properties ,olp ,atime ,mtime ,tags ,aliases ,refs)
+       (let (
-                                  row)
+             (all-titles (cons (car row) (nth 1 row)))
-                                 (all-titles (cons title aliases)))
+             )
-                      (mapcar (lambda (temp-title)
+         (mapcar (lambda (temp-title)
-                                (org-roam-node-create :id id
+                   (apply 'org-roam-node-create-from-db (cons temp-title (cdr row))))
-                                                      :file file
+                 all-titles)
-                                                      :file-title file-title
+         ))
-                                                      :file-atime atime
+     rows)
-                                                      :file-mtime mtime
+    )
-                                                      :level level
+  )
-                                                      :point pos
-                                                      :todo todo
-                                                      :priority priority
-                                                      :scheduled scheduled
-                                                      :deadline deadline
-                                                      :title temp-title
-                                                      :aliases aliases
-                                                      :properties properties
-                                                      :olp olp
-                                                      :tags tags
-                                                      :refs refs))
-                              all-titles)))))
 
 ;;;; Finders
 (defun org-roam-node-marker (node)
@@ -556,6 +581,25 @@ PROMPT is a string to show at the beginning of the mini-buffer, defaulting to \"
     (or (cdr (assoc node nodes))
         (org-roam-node-create :title node))))
 
+(defun org-roam--format-nodes-using-template (nodes)
+  "Formats NODES using org-roam template features.
+Uses org-roam--node-display-template."
+  (let  (
+         (wTemplate (org-roam-node--process-display-format org-roam-node-display-template))
+         )
+    (mapcar (lambda (node)
+              (org-roam-node-read--to-candidate node wTemplate)) nodes))
+  )
+
+(defun org-roam--format-nodes-using-function (nodes)
+  "Formats NODES using the function org-roam-node-display-template."
+  (mapcar (lambda (node)
+            (cons
+             (propertize (funcall org-roam-node-display-template node) 'node node)
+             node))
+          nodes)
+  )
+
 (defun org-roam-node-read--completions (&optional filter-fn sort-fn)
   "Return an alist for node completion.
 The car is the displayed title or alias for the node, and the cdr
@@ -565,15 +609,17 @@ and when nil is returned the node will be filtered out.
 SORT-FN is a function to sort nodes. See `org-roam-node-read-sort-by-file-mtime'
 for an example sort function.
 The displayed title is formatted according to `org-roam-node-display-template'."
-  (let* ((template (org-roam-node--process-display-format org-roam-node-display-template))
+  (let* (
          (nodes (org-roam-node-list))
          (nodes (if filter-fn
                     (cl-remove-if-not
                      (lambda (n) (funcall filter-fn n))
                      nodes)
                   nodes))
-         (nodes (mapcar (lambda (node)
+         (nodes (if (functionp org-roam-node-display-template)
-                          (org-roam-node-read--to-candidate node template)) nodes))
+                    (org-roam--format-nodes-using-function nodes)
+                  (org-roam--format-nodes-using-template nodes)))
+
          (sort-fn (or sort-fn
                       (when org-roam-node-default-sort
                         (intern (concat "org-roam-node-read-sort-by-"
@@ -726,7 +772,7 @@ The INFO, if provided, is passed to the underlying `org-roam-capture-'."
     (deactivate-mark)))
 
 ;;;;; [roam:] link
-(org-link-set-parameters "roam" :follow #'org-roam-link-follow-link)
+(org-link-set-parameters org-roam-link-type :follow #'org-roam-link-follow-link)
 (defun org-roam-link-follow-link (title-or-alias)
   "Navigate \"roam:\" link to find and open the node with TITLE-OR-ALIAS.
 Assumes that the cursor was put where the link is."
@@ -755,7 +801,7 @@ Assumes that the cursor was put where the link is."
              node)
         (goto-char (org-element-property :begin link))
         (when (and (org-in-regexp org-link-any-re 1)
-                   (string-equal type "roam")
+                   (string-equal type org-roam-link-type)
                    (setq node (save-match-data (org-roam-node-from-title-or-alias path))))
           (replace-match (org-link-make-string
                           (concat "id:" (org-roam-node-id node))
@@ -764,9 +810,10 @@ Assumes that the cursor was put where the link is."
 (defun org-roam-link-replace-all ()
   "Replace all \"roam:\" links in buffer with \"id:\" links."
   (interactive)
-  (org-with-point-at 1
+  (let ((org-roam-link-prefix (concat "[[" org-roam-link-type ":")))
-    (while (re-search-forward org-link-bracket-re nil t)
+    (org-with-point-at 1
-      (org-roam-link-replace-at-point))))
+      (while (re-search-forward org-roam-link-prefix nil t)
+        (org-roam-link-replace-at-point)))))
 
 (add-hook 'org-roam-find-file-hook #'org-roam--replace-roam-links-on-save-h)
 (defun org-roam--replace-roam-links-on-save-h ()

org-roam-utils.el

@@ -5,7 +5,7 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 2.3.0
+;; Version: 2.3.1
 ;; Package-Requires: ((emacs "26.1") (dash "2.13") (org "9.6"))
 
 ;; This file is NOT part of GNU Emacs.
@@ -163,7 +163,8 @@ If FILE, set `default-directory' to FILE's directory and insert its contents."
   (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))
+         (let ((org-roam-directory ,current-org-roam-directory)
+               (org-inhibit-startup t))
            (delay-mode-hooks (org-mode))
            (when ,file
              (insert-file-contents ,file)

org-roam.el

@@ -5,7 +5,7 @@
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience
-;; Version: 2.3.0
+;; Version: 2.3.1
 ;; Package-Requires: ((emacs "26.1") (dash "2.13") (org "9.6") (emacsql "4.1.0") (magit-section "3.0.0"))
 
 ;; This file is NOT part of GNU Emacs.

tests/test-org-roam-mode.el

@@ -30,9 +30,9 @@
     (setq org-roam-directory "/tmp/org roam"))
 
   (it "returns the correct rg command for unlinked references"
-    (expect (org-roam-unlinked-references--rg-command '("foo" "bar"))
+    (expect (org-roam-unlinked-references--rg-command '("foo" "bar") "/tmp/regex")
             :to-equal
-            "rg --follow --only-matching --vimgrep --pcre2 --ignore-case --glob \"*.org\" --glob \"*.org.gpg\" --glob \"*.org.age\" '\\[([^[]]++|(?R))*\\]|(\\bfoo\\b)|(\\bbar\\b)' /tmp/org\\ roam")))
+            "rg --follow --only-matching --vimgrep --pcre2 --ignore-case --glob \"*.org\" --glob \"*.org.gpg\" --glob \"*.org.age\" --file /tmp/regex /tmp/org\\ roam")))
 
 (provide 'test-org-roam-mode)