v2.2.2 (#2171)

Create initial log module for working with Org logs

.github/FUNDING.yml

@@ -1,6 +1,6 @@
 # These are supported funding model platforms
 
-github: [jethrokuan, zaeph]
+github: [jethrokuan]
 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

.github/ISSUE_TEMPLATE/bug_report.md

@@ -39,5 +39,3 @@ Example:
 ### Environment
 
 <!-- Please M-x org-roam-diagnostics and paste results here -->
-
-- Org-roam commit: https://github.com/jethrokuan/org-roam/commit/commithashhere

CHANGELOG.md

@@ -1,4 +1,23 @@
 # Changelog
+## 2.2.2
+### Breaking
+### Added
+- [#2138](https://github.com/org-roam/org-roam/pull/2138) export: add new module
+- [#2170](https://github.com/org-roam/org-roam/pull/2170) log: add new module for working with org logs
+- [#2158](https://github.com/org-roam/org-roam/pull/2158) db: support emacsql-sqlite-builtin and emacsql-sqlite-module
+- [#2160](https://github.com/org-roam/org-roam/pull/2160) core: support a list of `org-roam-file-exclude-regexp`
+
+### Removed
+### Fixed
+- [#2091](https://github.com/org-roam/org-roam/pull/2091) node: fix org-roam-promote-entire-buffer structural errors
+- [#2130](https://github.com/org-roam/org-roam/pull/2130) buffer: unlinked-references section now also searches within symlinked directories
+- [#2152](https://github.com/org-roam/org-roam/pull/2152) org-roam-preview-default-function: doesn't copy copy content of next heading node when current node's content is empty
+- [#2159](https://github.com/org-roam/org-roam/pull/2159) db: fix db syncs on narrowed buffers
+- [#2156](https://github.com/org-roam/org-roam/pull/2157) capture: templates with functions are handled correctly to avoid signaling `char-or-string-p`
+
+### Changed
+- [#2160](https://github.com/org-roam/org-roam/pull/2160) core: ignore files in `org-attach-id-dir` by default
+
 ## 2.2.1
 ### Breaking
 - [#2054](https://github.com/org-roam/org-roam/pull/2054) node: simplify default `org-roam-node-display-template`.

doc/org-roam.org

@@ -17,7 +17,7 @@
 This manual is for Org-roam version 2.2.1.
 
 #+BEGIN_QUOTE
-Copyright (C) 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
+Copyright (C) 2020-2022 Jethro Kuan <jethrokuan95@gmail.com>
 
 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
@@ -134,7 +134,7 @@ A slip-box requires a method for quickly capturing ideas. These are called
 *fleeting notes*: they are simple reminders of information or ideas that will
 need to be processed later on, or trashed. This is typically accomplished using
 ~org-capture~ (see info:org#Capture), or using Org-roam's daily notes
-functionality (see [[*Org-roam Dailies][Org-roam Dailies]]). This provides a central inbox for collecting
+functionality (see [[*org-roam-dailies][org-roam-dailies]]). This provides a central inbox for collecting
 thoughts, to be processed later into permanent notes.
 
 *Permanent notes*
@@ -468,9 +468,6 @@ can set ~org-roam-node-display-template~ as such:
 
 * Customizing Node Caching
 ** How to cache
-:PROPERTIES:
-:ID:       280bfca8-83f3-4371-bc3a-25478d25129c
-:END:
 
 Org-roam uses a sqlite database to perform caching, but there are multiple Emacs
 libraries that can be used. The default used by Org-roam is ~emacs-sqlite~.
@@ -765,7 +762,7 @@ With the above example, if another node links to https://www.google.com/, it
 will show up as a “reference backlink”.
 
 These keys also come in useful for when taking website notes, using the
- ~roam-ref~ protocol (see [[*Org-roam Protocol][Roam Protocol]]).
+ ~roam-ref~ protocol (see [[*org-roam-protocol][org-roam-protocol]]).
 
 You may assign multiple refs to a single node, for example when you want
 multiple papers in a series to share the same note, or an article has a citation
@@ -896,211 +893,6 @@ Note that the Org-roam database stores metadata information in plain-text
 (headline text, for example), so if this information is private to you then you
 should also ensure the database is encrypted.
 
-* Org-roam Protocol
-
-Org-roam provides extensions for capturing content from external applications
-such as the browser, via ~org-protocol~. Org-roam extends ~org-protocol~ with 2
-protocols: the ~roam-node~ and ~roam-ref~ protocols.
-
-** Installation
-
-To enable Org-roam's protocol extensions, simply add the following to your init
-file:
-
-#+BEGIN_SRC emacs-lisp
-(require 'org-roam-protocol)
-#+END_SRC
-
-We also need to set up ~org-protocol~: the instructions for setting up
-~org-protocol~ are reproduced here.
-
-On a high-level, external calls are passed to Emacs via ~emacsclient~.
-~org-protocol~ intercepts these and runs custom actions based on the protocols
-registered. Hence, to use ~org-protocol~, once must:
-
-1. launch the ~emacsclient~ process
-2. Register ~org-protocol://~ as a valid scheme-handler
-
-The instructions for the latter for each operating system is detailed below.
-
-*** Linux
-For Linux users, create a desktop application in
-~~/.local/share/applications/org-protocol.desktop~:
-
-#+begin_example
-[Desktop Entry]
-Name=Org-Protocol
-Exec=emacsclient %u
-Icon=emacs-icon
-Type=Application
-Terminal=false
-MimeType=x-scheme-handler/org-protocol
-#+end_example
-
-Associate ~org-protocol://~ links with the desktop application by
-running in your shell:
-
-#+BEGIN_SRC bash
-xdg-mime default org-protocol.desktop x-scheme-handler/org-protocol
-#+END_SRC
-
-To disable the "confirm" prompt in Chrome, you can also make Chrome show a
-checkbox to tick, so that the ~Org-Protocol Client~ app will be used without
-confirmation. To do this, run in a shell:
-
-#+BEGIN_SRC bash
-sudo mkdir -p /etc/opt/chrome/policies/managed/
-sudo tee /etc/opt/chrome/policies/managed/external_protocol_dialog.json >/dev/null <<'EOF'
-{
-  "ExternalProtocolDialogShowAlwaysOpenCheckbox": true
-}
-EOF
-sudo chmod 644 /etc/opt/chrome/policies/managed/external_protocol_dialog.json
-#+END_SRC
-
-and then restart Chrome (for example, by navigating to <chrome://restart>) to
-make the new policy take effect.
-
-See [[https://www.chromium.org/administrators/linux-quick-start][here]] for more info on the ~/etc/opt/chrome/policies/managed~ directory and
-[[https://cloud.google.com/docs/chrome-enterprise/policies/?policy=ExternalProtocolDialogShowAlwaysOpenCheckbox][here]] for information on the ~ExternalProtocolDialogShowAlwaysOpenCheckbox~ policy.
-
-*** Mac OS
-For Mac OS, we need to create our own application.
-
-1. Launch Script Editor
-2. Use the following script, paying attention to the path to ~emacsclient~:
-
-#+begin_src emacs-lisp
-  on open location this_URL
-      set EC to "/usr/local/bin/emacsclient --no-wait "
-      set filePath to quoted form of this_URL
-      do shell script EC & filePath
-      tell application "Emacs" to activate
-  end open location
-#+end_src
-
-3. Save the script in ~/Applications/OrgProtocolClient.app~, changing the script type to
-   "Application", rather than "Script".
-4. Edit ~/Applications/OrgProtocolClient.app/Contents/Info.plist~, adding the
-   following before the last ~</dict>~ tag:
-
-#+begin_src text
-  <key>CFBundleURLTypes</key>
-  <array>
-    <dict>
-      <key>CFBundleURLName</key>
-      <string>org-protocol handler</string>
-      <key>CFBundleURLSchemes</key>
-      <array>
-        <string>org-protocol</string>
-      </array>
-    </dict>
-  </array>
-#+end_src
-
-5. Save the file, and run the ~OrgProtocolClient.app~ to register the protocol.
-
-To disable the "confirm" prompt in Chrome, you can also make Chrome
-show a checkbox to tick, so that the ~OrgProtocol~ app will be used
-without confirmation. To do this, run in a shell:
-
-#+BEGIN_SRC bash
-defaults write com.google.Chrome ExternalProtocolDialogShowAlwaysOpenCheckbox -bool true
-#+END_SRC
-
-If you're using [[https://github.com/railwaycat/homebrew-emacsmacport][Emacs Mac Port]], it registered its `Emacs.app` as the default
-handler for the URL scheme `org-protocol`. To make ~OrgProtocol.app~
-the default handler instead, run:
-
-#+BEGIN_SRC bash
-defaults write com.apple.LaunchServices/com.apple.launchservices.secure LSHandlers -array-add \
-'{"LSHandlerPreferredVersions" = { "LSHandlerRoleAll" = "-"; }; LSHandlerRoleAll = "org.yourusername.OrgProtocol"; LSHandlerURLScheme = "org-protocol";}'
-#+END_SRC
-
-Then restart your computer.
-
-**** Testing org-protocol
-
-To test that you have the handler setup and registered properly from the command
-line you can run:
-
-#+begin_src bash
-  open org-protocol://roam-ref\?template=r\&ref=test\&title=this
-#+end_src
-
-If you get an error similar too this or the wrong handler is run:
-
-#+begin_quote
-No application knows how to open URL org-protocol://roam-ref?template=r&ref=test&title=this (Error Domain=NSOSStatusErrorDomain Code=-10814 "kLSApplicationNotFoundErr: E.g. no application claims the file" UserInfo={_LSLine=1489, _LSFunction=runEvaluator}).
-
-#+end_quote
-
-You may need to manually register your handler, like this:
-
-#+begin_src bash
-/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -R  -f /Applications/OrgProtocolClient.app
-#+end_src
-
-Here is a link to the lsregister command that is really useful: https://eclecticlight.co/2019/03/25/lsregister-a-valuable-undocumented-command-for-launchservices/
-*** Windows
-For Windows, create a temporary ~org-protocol.reg~ file:
-
-#+BEGIN_SRC text
-REGEDIT4
-
-[HKEY_CLASSES_ROOT\org-protocol]
-@="URL:Org Protocol"
-"URL Protocol"=""
-[HKEY_CLASSES_ROOT\org-protocol\shell]
-[HKEY_CLASSES_ROOT\org-protocol\shell\open]
-[HKEY_CLASSES_ROOT\org-protocol\shell\open\command]
-@="\"C:\\Windows\\System32\\wsl.exe\" emacsclient \"%1\""
-#+END_SRC
-
-The above will forward the protocol to WSL. If you run Emacs natively on
-Windows, replace the last line with:
-
-#+BEGIN_SRC text
-@="\"c:\\path\\to\\emacs\\bin\\emacsclientw.exe\"  \"%1\""
-#+END_SRC
-
-After executing the .reg file, the protocol is registered and you can delete the
-file.
-
-** The roam-node protocol
-
-The roam-node protocol opens the node with ID specified by the ~node~ key (e.g.
-~org-protocol://roam-node?node=node-id~). ~org-roam-graph~ uses this to make the
-graph navigable.
-
-** The roam-ref protocol
-
-This protocol finds or creates a new note with a given ~ROAM_REFS~:
-
-[[file:images/roam-ref.gif]]
-
-To use this, create the following [[https://en.wikipedia.org/wiki/Bookmarklet][bookmarklet]] in your browser:
-
-#+BEGIN_SRC javascript
-  javascript:location.href =
-      'org-protocol://roam-ref?template=r&ref='
-      + encodeURIComponent(location.href)
-      + '&title='
-      + encodeURIComponent(document.title)
-      + '&body='
-      + encodeURIComponent(window.getSelection())
-#+END_SRC
-
-or as a keybinding in ~qutebrowser~ in , using the ~config.py~ file (see
-[[https://github.com/qutebrowser/qutebrowser/blob/master/doc/help/configuring.asciidoc][Configuring qutebrowser]]):
-
-#+BEGIN_SRC python
-  config.bind("<Ctrl-r>", "open javascript:location.href='org-protocol://roam-ref?template=r&ref='+encodeURIComponent(location.href)+'&title='+encodeURIComponent(document.title)")
-#+END_SRC
-
-where ~template~ is the template key for a template in
-~org-roam-capture-ref-templates~ (see [[*The Templating System][The Templating System]]).
-
 * The Templating System
 
 Org-roam extends the ~org-capture~ system, providing a smoother note-taking
@@ -1182,12 +974,217 @@ One can check the list of available keys for nodes by inspecting the
 
 This makes ~${file}~, ~${file-hash}~ etc. all valid substitutions.
 
-* Graphing
+* Extensions
+** org-roam-protocol
+
+Org-roam provides extensions for capturing content from external applications
+such as the browser, via ~org-protocol~. Org-roam extends ~org-protocol~ with 2
+protocols: the ~roam-node~ and ~roam-ref~ protocols.
+
+*** Installation
+
+To enable Org-roam's protocol extensions, simply add the following to your init
+file:
+
+#+BEGIN_SRC emacs-lisp
+(require 'org-roam-protocol)
+#+END_SRC
+
+We also need to set up ~org-protocol~: the instructions for setting up
+~org-protocol~ are reproduced here.
+
+On a high-level, external calls are passed to Emacs via ~emacsclient~.
+~org-protocol~ intercepts these and runs custom actions based on the protocols
+registered. Hence, to use ~org-protocol~, once must:
+
+1. launch the ~emacsclient~ process
+2. Register ~org-protocol://~ as a valid scheme-handler
+
+The instructions for the latter for each operating system is detailed below.
+
+**** Linux
+For Linux users, create a desktop application in
+~~/.local/share/applications/org-protocol.desktop~:
+
+#+begin_example
+[Desktop Entry]
+Name=Org-Protocol
+Exec=emacsclient %u
+Icon=emacs-icon
+Type=Application
+Terminal=false
+MimeType=x-scheme-handler/org-protocol
+#+end_example
+
+Associate ~org-protocol://~ links with the desktop application by
+running in your shell:
+
+#+BEGIN_SRC bash
+xdg-mime default org-protocol.desktop x-scheme-handler/org-protocol
+#+END_SRC
+
+To disable the "confirm" prompt in Chrome, you can also make Chrome show a
+checkbox to tick, so that the ~Org-Protocol Client~ app will be used without
+confirmation. To do this, run in a shell:
+
+#+BEGIN_SRC bash
+sudo mkdir -p /etc/opt/chrome/policies/managed/
+sudo tee /etc/opt/chrome/policies/managed/external_protocol_dialog.json >/dev/null <<'EOF'
+{
+  "ExternalProtocolDialogShowAlwaysOpenCheckbox": true
+}
+EOF
+sudo chmod 644 /etc/opt/chrome/policies/managed/external_protocol_dialog.json
+#+END_SRC
+
+and then restart Chrome (for example, by navigating to <chrome://restart>) to
+make the new policy take effect.
+
+See [[https://www.chromium.org/administrators/linux-quick-start][here]] for more info on the ~/etc/opt/chrome/policies/managed~ directory and
+[[https://cloud.google.com/docs/chrome-enterprise/policies/?policy=ExternalProtocolDialogShowAlwaysOpenCheckbox][here]] for information on the ~ExternalProtocolDialogShowAlwaysOpenCheckbox~ policy.
+
+**** Mac OS
+For Mac OS, we need to create our own application.
+
+1. Launch Script Editor
+2. Use the following script, paying attention to the path to ~emacsclient~:
+
+#+begin_src emacs-lisp
+  on open location this_URL
+      set EC to "/usr/local/bin/emacsclient --no-wait "
+      set filePath to quoted form of this_URL
+      do shell script EC & filePath
+      tell application "Emacs" to activate
+  end open location
+#+end_src
+
+3. Save the script in ~/Applications/OrgProtocolClient.app~, changing the script type to
+   "Application", rather than "Script".
+4. Edit ~/Applications/OrgProtocolClient.app/Contents/Info.plist~, adding the
+   following before the last ~</dict>~ tag:
+
+#+begin_src text
+  <key>CFBundleURLTypes</key>
+  <array>
+    <dict>
+      <key>CFBundleURLName</key>
+      <string>org-protocol handler</string>
+      <key>CFBundleURLSchemes</key>
+      <array>
+        <string>org-protocol</string>
+      </array>
+    </dict>
+  </array>
+#+end_src
+
+5. Save the file, and run the ~OrgProtocolClient.app~ to register the protocol.
+
+To disable the "confirm" prompt in Chrome, you can also make Chrome
+show a checkbox to tick, so that the ~OrgProtocol~ app will be used
+without confirmation. To do this, run in a shell:
+
+#+BEGIN_SRC bash
+defaults write com.google.Chrome ExternalProtocolDialogShowAlwaysOpenCheckbox -bool true
+#+END_SRC
+
+If you're using [[https://github.com/railwaycat/homebrew-emacsmacport][Emacs Mac Port]], it registered its `Emacs.app` as the default
+handler for the URL scheme `org-protocol`. To make ~OrgProtocol.app~
+the default handler instead, run:
+
+#+BEGIN_SRC bash
+defaults write com.apple.LaunchServices/com.apple.launchservices.secure LSHandlers -array-add \
+'{"LSHandlerPreferredVersions" = { "LSHandlerRoleAll" = "-"; }; LSHandlerRoleAll = "org.yourusername.OrgProtocol"; LSHandlerURLScheme = "org-protocol";}'
+#+END_SRC
+
+Then restart your computer.
+
+***** Testing org-protocol
+
+To test that you have the handler setup and registered properly from the command
+line you can run:
+
+#+begin_src bash
+  open org-protocol://roam-ref\?template=r\&ref=test\&title=this
+#+end_src
+
+If you get an error similar too this or the wrong handler is run:
+
+#+begin_quote
+No application knows how to open URL org-protocol://roam-ref?template=r&ref=test&title=this (Error Domain=NSOSStatusErrorDomain Code=-10814 "kLSApplicationNotFoundErr: E.g. no application claims the file" UserInfo={_LSLine=1489, _LSFunction=runEvaluator}).
+
+#+end_quote
+
+You may need to manually register your handler, like this:
+
+#+begin_src bash
+/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -R  -f /Applications/OrgProtocolClient.app
+#+end_src
+
+Here is a link to the lsregister command that is really useful: https://eclecticlight.co/2019/03/25/lsregister-a-valuable-undocumented-command-for-launchservices/
+**** Windows
+For Windows, create a temporary ~org-protocol.reg~ file:
+
+#+BEGIN_SRC text
+REGEDIT4
+
+[HKEY_CLASSES_ROOT\org-protocol]
+@="URL:Org Protocol"
+"URL Protocol"=""
+[HKEY_CLASSES_ROOT\org-protocol\shell]
+[HKEY_CLASSES_ROOT\org-protocol\shell\open]
+[HKEY_CLASSES_ROOT\org-protocol\shell\open\command]
+@="\"C:\\Windows\\System32\\wsl.exe\" emacsclient \"%1\""
+#+END_SRC
+
+The above will forward the protocol to WSL. If you run Emacs natively on
+Windows, replace the last line with:
+
+#+BEGIN_SRC text
+@="\"c:\\path\\to\\emacs\\bin\\emacsclientw.exe\"  \"%1\""
+#+END_SRC
+
+After executing the .reg file, the protocol is registered and you can delete the
+file.
+
+*** The roam-node protocol
+
+The roam-node protocol opens the node with ID specified by the ~node~ key (e.g.
+~org-protocol://roam-node?node=node-id~). ~org-roam-graph~ uses this to make the
+graph navigable.
+
+*** The roam-ref protocol
+
+This protocol finds or creates a new note with a given ~ROAM_REFS~:
+
+[[file:images/roam-ref.gif]]
+
+To use this, create the following [[https://en.wikipedia.org/wiki/Bookmarklet][bookmarklet]] in your browser:
+
+#+BEGIN_SRC javascript
+  javascript:location.href =
+      'org-protocol://roam-ref?template=r&ref='
+      + encodeURIComponent(location.href)
+      + '&title='
+      + encodeURIComponent(document.title)
+      + '&body='
+      + encodeURIComponent(window.getSelection())
+#+END_SRC
+
+or as a keybinding in ~qutebrowser~ in , using the ~config.py~ file (see
+[[https://github.com/qutebrowser/qutebrowser/blob/master/doc/help/configuring.asciidoc][Configuring qutebrowser]]):
+
+#+BEGIN_SRC python
+  config.bind("<Ctrl-r>", "open javascript:location.href='org-protocol://roam-ref?template=r&ref='+encodeURIComponent(location.href)+'&title='+encodeURIComponent(document.title)")
+#+END_SRC
+
+where ~template~ is the template key for a template in
+~org-roam-capture-ref-templates~ (see [[*The Templating System][The Templating System]]).
+
+** org-roam-graph
 
 Org-roam provides basic graphing capabilities to explore interconnections
 between notes, in ~org-roam-graph~. This is done by performing SQL queries and
-generating images using [[https://graphviz.org/][Graphviz]]. The graph can also be navigated: see [[*Org-roam Protocol][Roam
+generating images using [[https://graphviz.org/][Graphviz]]. The graph can also be navigated: see [[*org-roam-protocol][org-roam-protocol]].
-Protocol]].
 
 The entry point to graph creation is ~org-roam-graph~.
 
@@ -1228,7 +1225,7 @@ ARG may be any of the following values:
           (org-roam-graph--open (concat "file://///wsl$/Ubuntu" file)))))
   #+END_SRC
 
-** Graph Options
+*** Graph Options
 
 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
@@ -1254,12 +1251,12 @@ for customizable options.
   Extra options for edges in the graphviz output (The "E" attributes).
   Example: ~'(("dir" . "back"))~
 
-* Org-roam Dailies
+** org-roam-dailies
 
 Org-roam provides journaling capabilities akin to
 Org-journal with ~org-roam-dailies~.
 
-** Configuration
+*** Configuration
 
 For ~org-roam-dailies~ to work, you need to define two variables:
 
@@ -1285,7 +1282,7 @@ Here is a sane default configuration:
 
 See [[*The Templating System][The Templating System]] for creating new templates.
 
-** Usage
+*** Usage
 
 ~org-roam-dailies~ provides these interactive functions:
 
@@ -1339,6 +1336,18 @@ There are also commands which allow you to use Emacs’s ~calendar~ to find the
 - Function: ~org-roam-dailies-goto-next-note~
 
   When in an daily-note, find the next one.
+** org-roam-export
+
+Because Org-roam files are plain org files, they can be exported easily using
+~org-export~ to a variety of formats, including ~html~ and ~pdf~. However,
+Org-roam relies heavily on ID links, which Org's html export has poor support
+of. To fix this, Org-roam provides a bunch of overrides to better support
+export. To use them, simply run:
+
+#+begin_src emacs-lisp
+  (require 'org-roam-export)
+#+end_src
+
 * Performance Optimization
 ** Garbage Collection
 
@@ -1412,7 +1421,7 @@ The Deft interface can slow down quickly when the number of files get huge.
 
 [[https://github.com/bastibe/org-journal][Org-journal]] provides journaling capabilities to Org-mode. A lot of its
 functionalities have been incorporated into Org-roam under the name
-[[*Org-roam Dailies][~org-roam-dailies~]]. It remains a good tool if you want to isolate your verbose
+[[*org-roam-dailies][~org-roam-dailies~]]. It remains a good tool if you want to isolate your verbose
 journal entries from the ideas you would write on a scratchpad.
 
 #+BEGIN_SRC emacs-lisp
@@ -1653,7 +1662,7 @@ To fix this, you can try the following:
 1. If on Windows, try replacing your system binary with [[https://github.com/nobiot/emacsql-sqlite.exe][this one]] that has been proven
    to work
 2. Use the ~emacsql-sqlite3~ option rather than compiling your own emacsql
-   binary (see [[id:280bfca8-83f3-4371-bc3a-25478d25129c][How to cache]]).
+   binary (see [[*How to cache][How to cache]]).
 
 * Developer's Guide to Org-roam
 ** Org-roam's Design Principle
@@ -1800,7 +1809,7 @@ When GOTO is non-nil, go the note without creating an entry."
 :END:
 
 #+BEGIN_QUOTE
-Copyright (C) 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
+Copyright (C) 2020-2022 Jethro Kuan <jethrokuan95@gmail.com>
 
 You can redistribute this document and/or modify it under the terms
 of the GNU General Public License as published by the Free Software

doc/org-roam.texi

@@ -8,7 +8,7 @@
 
 @copying
 @quotation
-Copyright (C) 2020-2021 Jethro Kuan <jethrokuan95@@gmail.com>
+Copyright (C) 2020-2022 Jethro Kuan <jethrokuan95@@gmail.com>
 
 You can redistribute this document and/or modify it under the terms
 of the GNU General Public License as published by the Free Software
@@ -47,7 +47,7 @@ General Public License for more details.
 This manual is for Org-roam version 2.2.1.
 
 @quotation
-Copyright (C) 2020-2021 Jethro Kuan <jethrokuan95@@gmail.com>
+Copyright (C) 2020-2022 Jethro Kuan <jethrokuan95@@gmail.com>
 
 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
@@ -73,10 +73,8 @@ General Public License for more details.
 * Citations::
 * Completion::
 * Encryption::
-* Org-roam Protocol::
 * The Templating System::
-* Graphing::
+* Extensions::
-* Org-roam Dailies::
 * Performance Optimization::
 * The Org-mode Ecosystem::
 * FAQ::
@@ -141,7 +139,19 @@ Completion
 * Completing within Link Brackets::
 * Completing anywhere::
 
-Org-roam Protocol
+The Templating System
+
+* Template Walkthrough::
+* Org-roam Template Expansion::
+
+Extensions
+
+* org-roam-protocol::
+* org-roam-graph::
+* org-roam-dailies::
+* org-roam-export::
+
+org-roam-protocol
 
 * Installation: Installation (1). 
 * The roam-node protocol::
@@ -153,20 +163,11 @@ Installation
 * Mac OS::
 * Windows::
 
-Mac OS
+org-roam-graph
-
-* Testing org-protocol::
-
-The Templating System
-
-* Template Walkthrough::
-* Org-roam Template Expansion::
-
-Graphing
 
 * Graph Options::
 
-Org-roam Dailies
+org-roam-dailies
 
 * Configuration::
 * Usage::
@@ -342,7 +343,7 @@ A slip-box requires a method for quickly capturing ideas. These are called
 @strong{fleeting notes}: they are simple reminders of information or ideas that will
 need to be processed later on, or trashed. This is typically accomplished using
 @code{org-capture} (see @ref{Capture,,,org,}), or using Org-roam's daily notes
-functionality (see @ref{Org-roam Dailies}). This provides a central inbox for collecting
+functionality (see @ref{org-roam-dailies}). This provides a central inbox for collecting
 thoughts, to be processed later into permanent notes.
 
 @strong{Permanent notes}
@@ -1141,7 +1142,7 @@ With the above example, if another node links to @uref{https://www.google.com/},
 will show up as a “reference backlink”.
 
 These keys also come in useful for when taking website notes, using the
- @code{roam-ref} protocol (see @ref{Org-roam Protocol, , Roam Protocol}).
+ @code{roam-ref} protocol (see @ref{org-roam-protocol}).
 
 You may assign multiple refs to a single node, for example when you want
 multiple papers in a series to share the same note, or an article has a citation
@@ -1295,257 +1296,6 @@ Note that the Org-roam database stores metadata information in plain-text
 (headline text, for example), so if this information is private to you then you
 should also ensure the database is encrypted.
 
-@node Org-roam Protocol
-@chapter Org-roam Protocol
-
-Org-roam provides extensions for capturing content from external applications
-such as the browser, via @code{org-protocol}. Org-roam extends @code{org-protocol} with 2
-protocols: the @code{roam-node} and @code{roam-ref} protocols.
-
-@menu
-* Installation: Installation (1). 
-* The roam-node protocol::
-* The roam-ref protocol::
-@end menu
-
-@node Installation (1)
-@section Installation
-
-To enable Org-roam's protocol extensions, simply add the following to your init
-file:
-
-@lisp
-(require 'org-roam-protocol)
-@end lisp
-
-We also need to set up @code{org-protocol}: the instructions for setting up
-@code{org-protocol} are reproduced here.
-
-On a high-level, external calls are passed to Emacs via @code{emacsclient}.
-@code{org-protocol} intercepts these and runs custom actions based on the protocols
-registered. Hence, to use @code{org-protocol}, once must:
-
-@itemize
-@item
-launch the @code{emacsclient} process
-
-@item
-Register @code{org-protocol://} as a valid scheme-handler
-@end itemize
-
-The instructions for the latter for each operating system is detailed below.
-
-@menu
-* Linux::
-* Mac OS::
-* Windows::
-@end menu
-
-@node Linux
-@subsection Linux
-
-For Linux users, create a desktop application in
-@code{~/.local/share/applications/org-protocol.desktop}:
-
-@example
-[Desktop Entry]
-Name=Org-Protocol
-Exec=emacsclient %u
-Icon=emacs-icon
-Type=Application
-Terminal=false
-MimeType=x-scheme-handler/org-protocol
-@end example
-
-Associate @code{org-protocol://} links with the desktop application by
-running in your shell:
-
-@example
-xdg-mime default org-protocol.desktop x-scheme-handler/org-protocol
-@end example
-
-To disable the ``confirm'' prompt in Chrome, you can also make Chrome show a
-checkbox to tick, so that the @code{Org-Protocol Client} app will be used without
-confirmation. To do this, run in a shell:
-
-@example
-sudo mkdir -p /etc/opt/chrome/policies/managed/
-sudo tee /etc/opt/chrome/policies/managed/external_protocol_dialog.json >/dev/null <<'EOF'
-@{
-  "ExternalProtocolDialogShowAlwaysOpenCheckbox": true
-@}
-EOF
-sudo chmod 644 /etc/opt/chrome/policies/managed/external_protocol_dialog.json
-@end example
-
-and then restart Chrome (for example, by navigating to <chrome://restart>) to
-make the new policy take effect.
-
-See @uref{https://www.chromium.org/administrators/linux-quick-start, here} for more info on the @code{/etc/opt/chrome/policies/managed} directory and
-@uref{https://cloud.google.com/docs/chrome-enterprise/policies/?policy=ExternalProtocolDialogShowAlwaysOpenCheckbox, here} for information on the @code{ExternalProtocolDialogShowAlwaysOpenCheckbox} policy.
-
-@node Mac OS
-@subsection Mac OS
-
-For Mac OS, we need to create our own application.
-
-@itemize
-@item
-Launch Script Editor
-
-@item
-Use the following script, paying attention to the path to @code{emacsclient}:
-@end itemize
-
-@lisp
-on open location this_URL
-    set EC to "/usr/local/bin/emacsclient --no-wait "
-    set filePath to quoted form of this_URL
-    do shell script EC & filePath
-    tell application "Emacs" to activate
-end open location
-@end lisp
-
-@itemize
-@item
-Save the script in @code{/Applications/OrgProtocolClient.app}, changing the script type to
-``Application'', rather than ``Script''.
-
-@item
-Edit @code{/Applications/OrgProtocolClient.app/Contents/Info.plist}, adding the
-following before the last @code{</dict>} tag:
-@end itemize
-
-@example
-<key>CFBundleURLTypes</key>
-<array>
-  <dict>
-    <key>CFBundleURLName</key>
-    <string>org-protocol handler</string>
-    <key>CFBundleURLSchemes</key>
-    <array>
-      <string>org-protocol</string>
-    </array>
-  </dict>
-</array>
-@end example
-
-@itemize
-@item
-Save the file, and run the @code{OrgProtocolClient.app} to register the protocol.
-@end itemize
-
-To disable the ``confirm'' prompt in Chrome, you can also make Chrome
-show a checkbox to tick, so that the @code{OrgProtocol} app will be used
-without confirmation. To do this, run in a shell:
-
-@example
-defaults write com.google.Chrome ExternalProtocolDialogShowAlwaysOpenCheckbox -bool true
-@end example
-
-If you're using @uref{https://github.com/railwaycat/homebrew-emacsmacport, Emacs Mac Port}, it registered its `Emacs.app` as the default
-handler for the URL scheme `org-protocol`. To make @code{OrgProtocol.app}
-the default handler instead, run:
-
-@example
-defaults write com.apple.LaunchServices/com.apple.launchservices.secure LSHandlers -array-add \
-'@{"LSHandlerPreferredVersions" = @{ "LSHandlerRoleAll" = "-"; @}; LSHandlerRoleAll = "org.yourusername.OrgProtocol"; LSHandlerURLScheme = "org-protocol";@}'
-@end example
-
-Then restart your computer.
-
-@menu
-* Testing org-protocol::
-@end menu
-
-@node Testing org-protocol
-@unnumberedsubsubsec Testing org-protocol
-
-To test that you have the handler setup and registered properly from the command
-line you can run:
-
-@example
-open org-protocol://roam-ref\?template=r\&ref=test\&title=this
-@end example
-
-If you get an error similar too this or the wrong handler is run:
-
-@quotation
-No application knows how to open URL org-protocol://roam-ref?template=r&ref=test&title=this (Error Domain=NSOSStatusErrorDomain Code=-10814 ``kLSApplicationNotFoundErr: E.g. no application claims the file'' UserInfo=@{@math{_LSLine}=1489, _LSFunction=runEvaluator@}).
-
-@end quotation
-
-You may need to manually register your handler, like this:
-
-@example
-/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -R  -f /Applications/OrgProtocolClient.app
-@end example
-
-Here is a link to the lsregister command that is really useful: @uref{https://eclecticlight.co/2019/03/25/lsregister-a-valuable-undocumented-command-for-launchservices/}
-
-@node Windows
-@subsection Windows
-
-For Windows, create a temporary @code{org-protocol.reg} file:
-
-@example
-REGEDIT4
-
-[HKEY_CLASSES_ROOT\org-protocol]
-@@="URL:Org Protocol"
-"URL Protocol"=""
-[HKEY_CLASSES_ROOT\org-protocol\shell]
-[HKEY_CLASSES_ROOT\org-protocol\shell\open]
-[HKEY_CLASSES_ROOT\org-protocol\shell\open\command]
-@@="\"C:\\Windows\\System32\\wsl.exe\" emacsclient \"%1\""
-@end example
-
-The above will forward the protocol to WSL@. If you run Emacs natively on
-Windows, replace the last line with:
-
-@example
-@@="\"c:\\path\\to\\emacs\\bin\\emacsclientw.exe\"  \"%1\""
-@end example
-
-After executing the .reg file, the protocol is registered and you can delete the
-file.
-
-@node The roam-node protocol
-@section The roam-node protocol
-
-The roam-node protocol opens the node with ID specified by the @code{node} key (e.g.
-@code{org-protocol://roam-node?node=node-id}). @code{org-roam-graph} uses this to make the
-graph navigable.
-
-@node The roam-ref protocol
-@section The roam-ref protocol
-
-This protocol finds or creates a new note with a given @code{ROAM_REFS}:
-
-@image{images/roam-ref,,,,gif}
-
-To use this, create the following @uref{https://en.wikipedia.org/wiki/Bookmarklet, bookmarklet} in your browser:
-
-@example
-javascript:location.href =
-    'org-protocol://roam-ref?template=r&ref='
-    + encodeURIComponent(location.href)
-    + '&title='
-    + encodeURIComponent(document.title)
-    + '&body='
-    + encodeURIComponent(window.getSelection())
-@end example
-
-or as a keybinding in @code{qutebrowser} in , using the @code{config.py} file (see
-@uref{https://github.com/qutebrowser/qutebrowser/blob/master/doc/help/configuring.asciidoc, Configuring qutebrowser}):
-
-@example
-config.bind("<Ctrl-r>", "open javascript:location.href='org-protocol://roam-ref?template=r&ref='+encodeURIComponent(location.href)+'&title='+encodeURIComponent(document.title)")
-@end example
-
-where @code{template} is the template key for a template in
-@code{org-roam-capture-ref-templates} (see @ref{The Templating System}).
-
 @node The Templating System
 @chapter The Templating System
 
@@ -1662,13 +1412,272 @@ One can check the list of available keys for nodes by inspecting the
 
 This makes @code{$@{file@}}, @code{$@{file-hash@}} etc. all valid substitutions.
 
-@node Graphing
+@node Extensions
-@chapter Graphing
+@chapter Extensions
+
+@menu
+* org-roam-protocol::
+* org-roam-graph::
+* org-roam-dailies::
+* org-roam-export::
+@end menu
+
+@node org-roam-protocol
+@section org-roam-protocol
+
+Org-roam provides extensions for capturing content from external applications
+such as the browser, via @code{org-protocol}. Org-roam extends @code{org-protocol} with 2
+protocols: the @code{roam-node} and @code{roam-ref} protocols.
+
+@menu
+* Installation: Installation (1). 
+* The roam-node protocol::
+* The roam-ref protocol::
+@end menu
+
+@node Installation (1)
+@subsection Installation
+
+To enable Org-roam's protocol extensions, simply add the following to your init
+file:
+
+@lisp
+(require 'org-roam-protocol)
+@end lisp
+
+We also need to set up @code{org-protocol}: the instructions for setting up
+@code{org-protocol} are reproduced here.
+
+On a high-level, external calls are passed to Emacs via @code{emacsclient}.
+@code{org-protocol} intercepts these and runs custom actions based on the protocols
+registered. Hence, to use @code{org-protocol}, once must:
+
+@itemize
+@item
+launch the @code{emacsclient} process
+
+@item
+Register @code{org-protocol://} as a valid scheme-handler
+@end itemize
+
+The instructions for the latter for each operating system is detailed below.
+
+@menu
+* Linux::
+* Mac OS::
+* Windows::
+@end menu
+
+@node Linux
+@unnumberedsubsubsec Linux
+
+For Linux users, create a desktop application in
+@code{~/.local/share/applications/org-protocol.desktop}:
+
+@example
+[Desktop Entry]
+Name=Org-Protocol
+Exec=emacsclient %u
+Icon=emacs-icon
+Type=Application
+Terminal=false
+MimeType=x-scheme-handler/org-protocol
+@end example
+
+Associate @code{org-protocol://} links with the desktop application by
+running in your shell:
+
+@example
+xdg-mime default org-protocol.desktop x-scheme-handler/org-protocol
+@end example
+
+To disable the ``confirm'' prompt in Chrome, you can also make Chrome show a
+checkbox to tick, so that the @code{Org-Protocol Client} app will be used without
+confirmation. To do this, run in a shell:
+
+@example
+sudo mkdir -p /etc/opt/chrome/policies/managed/
+sudo tee /etc/opt/chrome/policies/managed/external_protocol_dialog.json >/dev/null <<'EOF'
+@{
+  "ExternalProtocolDialogShowAlwaysOpenCheckbox": true
+@}
+EOF
+sudo chmod 644 /etc/opt/chrome/policies/managed/external_protocol_dialog.json
+@end example
+
+and then restart Chrome (for example, by navigating to <chrome://restart>) to
+make the new policy take effect.
+
+See @uref{https://www.chromium.org/administrators/linux-quick-start, here} for more info on the @code{/etc/opt/chrome/policies/managed} directory and
+@uref{https://cloud.google.com/docs/chrome-enterprise/policies/?policy=ExternalProtocolDialogShowAlwaysOpenCheckbox, here} for information on the @code{ExternalProtocolDialogShowAlwaysOpenCheckbox} policy.
+
+@node Mac OS
+@unnumberedsubsubsec Mac OS
+
+For Mac OS, we need to create our own application.
+
+@itemize
+@item
+Launch Script Editor
+
+@item
+Use the following script, paying attention to the path to @code{emacsclient}:
+@end itemize
+
+@lisp
+on open location this_URL
+    set EC to "/usr/local/bin/emacsclient --no-wait "
+    set filePath to quoted form of this_URL
+    do shell script EC & filePath
+    tell application "Emacs" to activate
+end open location
+@end lisp
+
+@itemize
+@item
+Save the script in @code{/Applications/OrgProtocolClient.app}, changing the script type to
+``Application'', rather than ``Script''.
+
+@item
+Edit @code{/Applications/OrgProtocolClient.app/Contents/Info.plist}, adding the
+following before the last @code{</dict>} tag:
+@end itemize
+
+@example
+<key>CFBundleURLTypes</key>
+<array>
+  <dict>
+    <key>CFBundleURLName</key>
+    <string>org-protocol handler</string>
+    <key>CFBundleURLSchemes</key>
+    <array>
+      <string>org-protocol</string>
+    </array>
+  </dict>
+</array>
+@end example
+
+@itemize
+@item
+Save the file, and run the @code{OrgProtocolClient.app} to register the protocol.
+@end itemize
+
+To disable the ``confirm'' prompt in Chrome, you can also make Chrome
+show a checkbox to tick, so that the @code{OrgProtocol} app will be used
+without confirmation. To do this, run in a shell:
+
+@example
+defaults write com.google.Chrome ExternalProtocolDialogShowAlwaysOpenCheckbox -bool true
+@end example
+
+If you're using @uref{https://github.com/railwaycat/homebrew-emacsmacport, Emacs Mac Port}, it registered its `Emacs.app` as the default
+handler for the URL scheme `org-protocol`. To make @code{OrgProtocol.app}
+the default handler instead, run:
+
+@example
+defaults write com.apple.LaunchServices/com.apple.launchservices.secure LSHandlers -array-add \
+'@{"LSHandlerPreferredVersions" = @{ "LSHandlerRoleAll" = "-"; @}; LSHandlerRoleAll = "org.yourusername.OrgProtocol"; LSHandlerURLScheme = "org-protocol";@}'
+@end example
+
+Then restart your computer.
+
+@itemize
+@item
+@anchor{Testing org-protocol}Testing org-protocol
+
+
+To test that you have the handler setup and registered properly from the command
+line you can run:
+
+@example
+open org-protocol://roam-ref\?template=r\&ref=test\&title=this
+@end example
+
+If you get an error similar too this or the wrong handler is run:
+
+@quotation
+No application knows how to open URL org-protocol://roam-ref?template=r&ref=test&title=this (Error Domain=NSOSStatusErrorDomain Code=-10814 ``kLSApplicationNotFoundErr: E.g. no application claims the file'' UserInfo=@{@math{_LSLine}=1489, _LSFunction=runEvaluator@}).
+
+@end quotation
+
+You may need to manually register your handler, like this:
+
+@example
+/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -R  -f /Applications/OrgProtocolClient.app
+@end example
+
+Here is a link to the lsregister command that is really useful: @uref{https://eclecticlight.co/2019/03/25/lsregister-a-valuable-undocumented-command-for-launchservices/}
+@end itemize
+
+@node Windows
+@unnumberedsubsubsec Windows
+
+For Windows, create a temporary @code{org-protocol.reg} file:
+
+@example
+REGEDIT4
+
+[HKEY_CLASSES_ROOT\org-protocol]
+@@="URL:Org Protocol"
+"URL Protocol"=""
+[HKEY_CLASSES_ROOT\org-protocol\shell]
+[HKEY_CLASSES_ROOT\org-protocol\shell\open]
+[HKEY_CLASSES_ROOT\org-protocol\shell\open\command]
+@@="\"C:\\Windows\\System32\\wsl.exe\" emacsclient \"%1\""
+@end example
+
+The above will forward the protocol to WSL@. If you run Emacs natively on
+Windows, replace the last line with:
+
+@example
+@@="\"c:\\path\\to\\emacs\\bin\\emacsclientw.exe\"  \"%1\""
+@end example
+
+After executing the .reg file, the protocol is registered and you can delete the
+file.
+
+@node The roam-node protocol
+@subsection The roam-node protocol
+
+The roam-node protocol opens the node with ID specified by the @code{node} key (e.g.
+@code{org-protocol://roam-node?node=node-id}). @code{org-roam-graph} uses this to make the
+graph navigable.
+
+@node The roam-ref protocol
+@subsection The roam-ref protocol
+
+This protocol finds or creates a new note with a given @code{ROAM_REFS}:
+
+@image{images/roam-ref,,,,gif}
+
+To use this, create the following @uref{https://en.wikipedia.org/wiki/Bookmarklet, bookmarklet} in your browser:
+
+@example
+javascript:location.href =
+    'org-protocol://roam-ref?template=r&ref='
+    + encodeURIComponent(location.href)
+    + '&title='
+    + encodeURIComponent(document.title)
+    + '&body='
+    + encodeURIComponent(window.getSelection())
+@end example
+
+or as a keybinding in @code{qutebrowser} in , using the @code{config.py} file (see
+@uref{https://github.com/qutebrowser/qutebrowser/blob/master/doc/help/configuring.asciidoc, Configuring qutebrowser}):
+
+@example
+config.bind("<Ctrl-r>", "open javascript:location.href='org-protocol://roam-ref?template=r&ref='+encodeURIComponent(location.href)+'&title='+encodeURIComponent(document.title)")
+@end example
+
+where @code{template} is the template key for a template in
+@code{org-roam-capture-ref-templates} (see @ref{The Templating System}).
+
+@node org-roam-graph
+@section org-roam-graph
 
 Org-roam provides basic graphing capabilities to explore interconnections
 between notes, in @code{org-roam-graph}. This is done by performing SQL queries and
-generating images using @uref{https://graphviz.org/, Graphviz}. The graph can also be navigated: see @ref{Org-roam Protocol, , Roam
+generating images using @uref{https://graphviz.org/, Graphviz}. The graph can also be navigated: see @ref{org-roam-protocol}.
-Protocol}.
 
 The entry point to graph creation is @code{org-roam-graph}.
 
@@ -1726,7 +1735,7 @@ the second option to set the browser and network file path:
 @end menu
 
 @node Graph Options
-@section Graph Options
+@subsection Graph Options
 
 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}
@@ -1756,8 +1765,8 @@ Extra options for edges in the graphviz output (The ``E'' attributes).
 Example: @code{'(("dir" . "back"))}
 @end defopt
 
-@node Org-roam Dailies
+@node org-roam-dailies
-@chapter Org-roam Dailies
+@section org-roam-dailies
 
 Org-roam provides journaling capabilities akin to
 Org-journal with @code{org-roam-dailies}.
@@ -1768,7 +1777,7 @@ Org-journal with @code{org-roam-dailies}.
 @end menu
 
 @node Configuration
-@section Configuration
+@subsection Configuration
 
 For @code{org-roam-dailies} to work, you need to define two variables:
 
@@ -1797,7 +1806,7 @@ Here is a sane default configuration:
 See @ref{The Templating System} for creating new templates.
 
 @node Usage
-@section Usage
+@subsection Usage
 
 @code{org-roam-dailies} provides these interactive functions:
 
@@ -1861,6 +1870,19 @@ When in an daily-note, find the previous one.
 When in an daily-note, find the next one.
 @end defun
 
+@node org-roam-export
+@section org-roam-export
+
+Because Org-roam files are plain org files, they can be exported easily using
+@code{org-export} to a variety of formats, including @code{html} and @code{pdf}. However,
+Org-roam relies heavily on ID links, which Org's html export has poor support
+of. To fix this, Org-roam provides a bunch of overrides to better support
+export. To use them, simply run:
+
+@lisp
+(require 'org-roam-export)
+@end lisp
+
 @node Performance Optimization
 @chapter Performance Optimization
 
@@ -1958,7 +1980,7 @@ The Deft interface can slow down quickly when the number of files get huge.
 
 @uref{https://github.com/bastibe/org-journal, Org-journal} provides journaling capabilities to Org-mode. A lot of its
 functionalities have been incorporated into Org-roam under the name
-@ref{Org-roam Dailies, , @code{org-roam-dailies}}. It remains a good tool if you want to isolate your verbose
+@ref{org-roam-dailies, , @code{org-roam-dailies}}. It remains a good tool if you want to isolate your verbose
 journal entries from the ideas you would write on a scratchpad.
 
 @lisp

extensions/org-roam-dailies.el

@@ -1,6 +1,6 @@
 ;;; org-roam-dailies.el --- Daily-notes for Org-roam -*- coding: utf-8; lexical-binding: t; -*-
 ;;;
-;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
+;; Copyright © 2020-2022 Jethro Kuan <jethrokuan95@gmail.com>
 ;; Copyright © 2020 Leo Vivier <leo.vivier+dev@gmail.com>
 
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>

extensions/org-roam-export.el

@@ -0,0 +1,75 @@
+;;; org-roam-export.el --- Org-roam org-export tweaks -*- coding: utf-8; lexical-binding: t; -*-
+
+;; Copyright © 2020-2022 Jethro Kuan <jethrokuan95@gmail.com>
+
+;; Author: Jethro Kuan <jethrokuan95@gmail.com>
+;; URL: https://github.com/org-roam/org-roam
+;; Keywords: org-mode, roam, convenience
+;; Version: 2.2.1
+;; Package-Requires: ((emacs "26.1") (org "9.4") (org-roam "2.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 package provides the necessary changes required to make org-export work out-of-the-box.
+;;
+;; To enable it, run:
+;;
+;;    (require 'org-roam-export)
+;;
+;; The key issue Org's export-to-html functionality has is that it does not respect the ID property, which
+;; Org-roam relies heavily on. This patches the necessary function in ox-html to export ID links correctly,
+;; pointing to the correct place.
+;;
+;;; Code:
+(require 'ox-html)
+
+(defun org-roam-export--org-html--reference (datum info &optional named-only)
+  "Org-roam's patch for `org-html--reference' to support ID link export.
+See `org-html--reference' for DATUM, INFO and NAMED-ONLY."
+  (let* ((type (org-element-type datum))
+         (user-label
+          (org-element-property
+           (pcase type
+             ((or `headline `inlinetask) :CUSTOM_ID)
+             ((or `radio-target `target) :value)
+             (_ :name))
+           datum))
+         (user-label
+          (or user-label
+              (when-let ((path (org-element-property :ID datum)))
+                ;; see `org-html-link' for why we use "ID-"
+                ;; (search for "ID-" in ox-html.el)
+                (concat "ID-" path)))))
+    (cond
+     ((and user-label
+           (or (plist-get info :html-prefer-user-labels)
+               (memq type '(headline inlinetask))))
+      user-label)
+     ((and named-only
+           (not (memq type '(headline inlinetask radio-target target)))
+           (not user-label))
+      nil)
+     (t
+      (org-export-get-reference datum info)))))
+
+(advice-add 'org-html--reference :override #'org-roam-export--org-html--reference)
+
+(provide 'org-roam-export)
+;;; org-roam-export.el ends here

extensions/org-roam-graph.el

@@ -1,6 +1,6 @@
 ;;; org-roam-graph.el --- Basic graphing functionality for Org-roam -*- coding: utf-8; lexical-binding: t; -*-
 
-;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
+;; Copyright © 2020-2022 Jethro Kuan <jethrokuan95@gmail.com>
 
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam

extensions/org-roam-overlay.el

@@ -1,6 +1,6 @@
 ;;; org-roam-overlay.el --- Link overlay for [id:] links to Org-roam nodes -*- coding: utf-8; lexical-binding: t; -*-
 
-;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
+;; Copyright © 2020-2022 Jethro Kuan <jethrokuan95@gmail.com>
 
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam

extensions/org-roam-protocol.el

@@ -1,6 +1,6 @@
 ;;; org-roam-protocol.el --- Protocol handler for roam:// links  -*- coding: utf-8; lexical-binding: t; -*-
 
-;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
+;; Copyright © 2020-2022 Jethro Kuan <jethrokuan95@gmail.com>
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
 ;; Keywords: org-mode, roam, convenience

org-roam-capture.el

@@ -1,6 +1,6 @@
 ;;; org-roam-capture.el --- Capture functionality -*- coding: utf-8; lexical-binding: t; -*-
 
-;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
+;; Copyright © 2020-2022 Jethro Kuan <jethrokuan95@gmail.com>
 
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
@@ -762,7 +762,10 @@ This function is to be called in the Org-capture finalization process."
 It expands ${var} occurrences in TEMPLATE, and then runs
 org-capture's template expansion.
 When ENSURE-NEWLINE, always ensure there's a newline behind."
-  (let ((template-whitespace-content (org-roam-whitespace-content template)))
+  (let* ((template (if (functionp template)
+                       (funcall template)
+                     template))
+         (template-whitespace-content (org-roam-whitespace-content template)))
     (setq template
           (org-roam-format-template
            template

org-roam-compat.el

@@ -1,6 +1,6 @@
 ;;; org-roam-compat.el --- Backward compatibility code -*- coding: utf-8; lexical-binding: t; -*-
 
-;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
+;; Copyright © 2020-2022 Jethro Kuan <jethrokuan95@gmail.com>
 
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam

org-roam-db.el

@@ -1,6 +1,6 @@
 ;;; org-roam-db.el --- Org-roam database API -*- coding: utf-8; lexical-binding: t; -*-
 
-;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
+;; Copyright © 2020-2022 Jethro Kuan <jethrokuan95@gmail.com>
 
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
@@ -36,23 +36,35 @@
 ;;; Options
 (defcustom org-roam-database-connector 'sqlite
   "The database connector used by Org-roam.
-This must be set before `org-roam' is loaded. To use an
+This must be set before `org-roam' is loaded.  To use an alternative
-alternative connector you must install the respective package
+connector you must install the respective package explicitly.
-explicitly. When `sqlite', then use the `emacsql-sqlite' library
+The default is `sqlite', which uses the `emacsql-sqlite' library
 that is being maintained in the same repository as `emacsql'
-itself. When `libsqlite3', then use the `emacsql-libsqlite3'
+itself.
-library, which itself uses a module provided by the `sqlite3'
+If you are using Emacs 29, then the recommended connector is
-package. This is still experimental. When `sqlite3', then use the
+`sqlite-builtin', which uses the new builtin support for SQLite.
-`emacsql-sqlite3' library, which uses the official `sqlite3' cli
+You need to install the `emacsql-sqlite-builtin' package to use
-tool, which is not recommended because it is not suitable to be
+this connector.
-used like this, but has the advantage that you likely don't need
+If you are using an older Emacs release, then the recommended
-a compiler. See https://nullprogram.com/blog/2014/02/06/."
+connector is `sqlite-module', which uses the module provided by
-  :package-version '(org-roam . "2.2.0")
+the `sqlite3' package.  This is very similar to the previous
-  :group 'org-roam
+connector and the built-in support in Emacs 29 derives from this
+module.  You need to install the `emacsql-sqlite-module' package
+to use this connector.
+For the time being `libsqlite3' is still supported.  Do not use
+this, it is an older version of the `sqlite-module' connector
+from before the connector and the package were renamed.
+For the time being `sqlite3' is also supported.  Do not use this.
+This uses the third-party `emacsql-sqlite3' package, which uses
+the official `sqlite3' cli tool, which is not intended
+to be used like this.  See https://nullprogram.com/blog/2014/02/06/."
+  :package-version '(forge . "0.3.0")
+  :group 'forge
   :type '(choice (const sqlite)
-                 (const libsqlite3)
+                 (const sqlite-builtin)
-                 (const sqlite3)
+                 (const sqlite-module)
-                 (symbol :tag "other")))
+                 (const :tag "libsqlite3 (OBSOLETE)" libsqlite3)
+                 (const :tag "sqlite3 (BROKEN)" sqlite3)))
 
 (defcustom org-roam-db-location (locate-user-emacs-file "org-roam.db")
   "The path to file where the Org-roam database is stored.
@@ -137,8 +149,10 @@ ROAM_REFS."
            org-roam-db--connection))
 
 (declare-function emacsql-sqlite "ext:emacsql-sqlite")
-(declare-function emacsql-libsqlite3 "ext:emacsql-libsqlite3")
 (declare-function emacsql-sqlite3 "ext:emacsql-sqlite3")
+(declare-function emacsql-libsqlite3 "ext:emacsql-libsqlite3")
+(declare-function emacsql-sqlite-builtin "ext:emacsql-sqlite-builtin")
+(declare-function emacsql-sqlite-module "ext:emacsql-sqlite-module")
 
 (defun org-roam-db--conn-fn ()
   "Return the function for creating the database connection."
@@ -147,6 +161,14 @@ ROAM_REFS."
      (progn
        (require 'emacsql-sqlite)
        #'emacsql-sqlite))
+    (sqlite-builtin
+     (progn
+       (require 'emacsql-sqlite-builtin)
+       #'emacsql-sqlite-builtin))
+    (sqlite-module
+     (progn
+       (require 'emacsql-sqlite-module)
+       #'emacsql-sqlite-module))
     (libsqlite3
      (progn
        (require 'emacsql-libsqlite3)
@@ -166,7 +188,8 @@ Performs a database upgrade when required."
       (make-directory (file-name-directory org-roam-db-location) t)
       (let ((conn (funcall (org-roam-db--conn-fn) org-roam-db-location)))
         (emacsql conn [:pragma (= foreign_keys ON)])
-        (when-let ((process (emacsql-process conn)))
+        (when-let* ((process (emacsql-process conn))
+                    (_ (processp process)))
           (set-process-query-on-exit-flag process nil))
         (puthash (expand-file-name (file-name-as-directory org-roam-directory))
                  conn
@@ -617,27 +640,27 @@ in `org-roam-db-sync'."
         (org-roam-require '(org-ref oc)))
       (org-roam-with-file file-path nil
         (emacsql-with-transaction (org-roam-db)
-          (save-excursion
+          (org-with-wide-buffer
-            (org-set-regexps-and-options 'tags-only)
+           (org-set-regexps-and-options 'tags-only)
-            (org-refresh-category-properties)
+           (org-refresh-category-properties)
-            (org-roam-db-clear-file)
+           (org-roam-db-clear-file)
-            (org-roam-db-insert-file)
+           (org-roam-db-insert-file)
-            (org-roam-db-insert-file-node)
+           (org-roam-db-insert-file-node)
-            (setq org-outline-path-cache nil)
+           (setq org-outline-path-cache nil)
-            (org-roam-db-map-nodes
+           (org-roam-db-map-nodes
-             (list #'org-roam-db-insert-node-data
+            (list #'org-roam-db-insert-node-data
-                   #'org-roam-db-insert-aliases
+                  #'org-roam-db-insert-aliases
-                   #'org-roam-db-insert-tags
+                  #'org-roam-db-insert-tags
-                   #'org-roam-db-insert-refs))
+                  #'org-roam-db-insert-refs))
-            (setq org-outline-path-cache nil)
+           (setq org-outline-path-cache nil)
-            (setq info (org-element-parse-buffer))
+           (setq info (org-element-parse-buffer))
-            (org-roam-db-map-links
+           (org-roam-db-map-links
-             (list #'org-roam-db-insert-link))
+            (list #'org-roam-db-insert-link))
-            (when (fboundp 'org-cite-insert)
+           (when (fboundp 'org-cite-insert)
-              (require 'oc)             ;ensure feature is loaded
+             (require 'oc)             ;ensure feature is loaded
-              (org-roam-db-map-citations
+             (org-roam-db-map-citations
-               info
+              info
-               (list #'org-roam-db-insert-citation)))))))))
+              (list #'org-roam-db-insert-citation)))))))))
 
 ;;;###autoload
 (defun org-roam-db-sync (&optional force)

org-roam-log.el

@@ -0,0 +1,53 @@
+;;; org-roam-log.el --- Integrations with Org-log -*- coding: utf-8; lexical-binding: t; -*-
+
+;; Copyright © 2022-2022 Jethro Kuan <jethrokuan95@gmail.com>
+
+;; Author: Jethro Kuan <jethrokuan95@gmail.com>
+;; URL: https://github.com/org-roam/org-roam
+;; Keywords: org-mode, roam, convenience
+;; Version: 2.2.1
+;; Package-Requires: ((emacs "26.1") (dash "2.13") (org "9.4") (emacsql "3.0.0") (emacsql-sqlite "1.0.0") (magit-section "3.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 module provides integrations with Org-log.
+;;
+;;; Code:
+(require 'org-roam)
+
+(defcustom org-roam-log-setup-hook nil
+  "Hook run when a log for an Org-roam file is setup."
+  :group 'org-roam
+  :type 'hook)
+
+(defun org-roam-log-p ()
+  "Return t if the log buffer is for an Org-roam file, nil otherwise."
+  (and org-log-note-marker
+       (org-roam-file-p (buffer-file-name (marker-buffer org-log-note-marker)))))
+
+(defun org-roam-log--setup ()
+  "Run hooks in `org-roam-log-setup-hook'."
+  (run-hooks 'org-roam-log-setup-hook))
+
+(add-hook 'org-roam-log-setup-hook #'org-roam--register-completion-functions-h)
+(add-hook 'org-log-buffer-setup-hook #'org-roam-log--setup)
+
+(provide 'org-roam-log)
+;;; org-roam-log.el ends here

org-roam-migrate.el

@@ -1,6 +1,6 @@
 ;;; org-roam-migrate.el --- Migration utilities from v1 to v2 -*- coding: utf-8; lexical-binding: t; -*-
 
-;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
+;; Copyright © 2020-2022 Jethro Kuan <jethrokuan95@gmail.com>
 
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam

org-roam-mode.el

@@ -449,10 +449,12 @@ In interactive calls OTHER-WINDOW is set with
 
 This function returns the all contents under the current
 headline, up to the next headline."
-  (let ((beg (progn (org-roam-end-of-meta-data t)
+  (let ((beg (save-excursion
-                    (point)))
+               (org-roam-end-of-meta-data t)
-        (end (progn (org-next-visible-heading 1)
+               (point)))
-                    (point))))
+        (end (save-excursion
+               (org-next-visible-heading 1)
+               (point))))
     (string-trim (buffer-substring-no-properties beg end))))
 
 (defun org-roam-preview-get-contents (file pt)
@@ -655,7 +657,7 @@ 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 (concat "rg -o --vimgrep -P -i "
+           (rg-command (concat "rg -L -o --vimgrep -P -i "
                                (mapconcat (lambda (glob) (concat "-g " glob))
                                           (org-roam--list-files-search-globs org-roam-file-extensions)
                                           " ")

org-roam-node.el

@@ -1,6 +1,6 @@
 ;;; org-roam-node.el --- Interfacing and interacting with nodes -*- lexical-binding: t; -*-
 
-;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
+;; Copyright © 2020-2022 Jethro Kuan <jethrokuan95@gmail.com>
 
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
@@ -802,6 +802,8 @@ hence \"everywhere\"."
             :exclusive 'no))))
 
 (add-hook 'org-roam-find-file-hook #'org-roam--register-completion-functions-h)
+(add-hook 'org-roam-indirect-buffer-hook #'org-roam--register-completion-functions-h)
+
 (defun org-roam--register-completion-functions-h ()
   "Setup `org-roam-completion-functions' for `completion-at-point'."
   (dolist (f org-roam-completion-functions)
@@ -829,23 +831,40 @@ Any top level properties drawers are incorporated into the new heading."
     (org-roam-erase-keyword "title")
     (org-roam-erase-keyword "filetags")))
 
+(defun org-roam--h1-count ()
+  "Count level-1 headings in the current file."
+  (let ((h1-count 0))
+    (org-with-wide-buffer
+     (org-map-region (lambda ()
+                       (if (= (org-current-level) 1)
+                           (incf h1-count)))
+                     (point-min) (point-max))
+     h1-count)))
+
+(defun org-roam--buffer-promoteable-p ()
+  "Verify that this buffer is promoteable:
+There is a single level-1 heading
+and no extra content before the first heading."
+  (and
+   (= (org-roam--h1-count) 1)
+   (org-with-point-at 1 (org-at-heading-p))))
+
 (defun org-roam-promote-entire-buffer ()
   "Promote the current buffer.
-Converts a file containing a headline node at the top to a file
+Converts a file containing a single level-1 headline node to a file
 node."
   (interactive)
+  (unless (org-roam--buffer-promoteable-p)
+    (user-error "Cannot promote: multiple root headings or there is extra file-level text"))
   (org-with-point-at 1
-    (org-map-region
-     (lambda ()
-       (when (> (org-outline-level) 1)
-         (org-do-promote)))
-     (point-min) (point-max))
     (let ((title (nth 4 (org-heading-components)))
-          (tags (nth 5 (org-heading-components))))
+          (tags (org-get-tags)))
-      (beginning-of-line)
+      (kill-whole-line)
-      (kill-line 1)
+      (org-roam-end-of-meta-data)
-      (org-roam-set-keyword "title" title)
+      (insert "#+title: " title "\n")
-      (when tags (org-roam-set-keyword "filetags" tags)))))
+      (when tags (org-roam-tag-add tags))
+      (org-map-region #'org-promote (point-min) (point-max))
+      (org-roam-db-update-file))))
 
 ;;;###autoload
 (defun org-roam-refile ()
@@ -942,6 +961,7 @@ If region is active, then use it instead of the node at point."
       (save-buffer)
       (with-current-buffer (find-file-noselect file-path)
         (org-paste-subtree)
+        (while (> (org-current-level) 1) (org-promote-subtree))
         (org-roam-promote-entire-buffer)
         (save-buffer)))))
 

org-roam-utils.el

@@ -486,7 +486,8 @@ See <https://github.com/raxod502/straight.el/issues/520>."
                                          '("Doom" "Spacemacs" "N/A" "I don't know"))
                       (quit "N/A"))))
     (insert (format "- Org: %s\n" (org-version nil 'full)))
-    (insert (format "- Org-roam: %s" (org-roam-version)))))
+    (insert (format "- Org-roam: %s" (org-roam-version)))
+    (insert (format "- sqlite-connector: %s" org-roam-database-connector))))
 
 
 (provide 'org-roam-utils)

org-roam.el

@@ -1,6 +1,6 @@
 ;;; org-roam.el --- A database abstraction layer for Org-mode -*- coding: utf-8; lexical-binding: t; -*-
 
-;; Copyright © 2020-2021 Jethro Kuan <jethrokuan95@gmail.com>
+;; Copyright © 2020-2022 Jethro Kuan <jethrokuan95@gmail.com>
 
 ;; Author: Jethro Kuan <jethrokuan95@gmail.com>
 ;; URL: https://github.com/org-roam/org-roam
@@ -83,6 +83,7 @@
 (require 'emacsql-sqlite)
 
 (require 'org)
+(require 'org-attach)                   ; To set `org-attach-id-dir'
 (require 'org-id)
 (require 'ol)
 (require 'org-element)
@@ -136,9 +137,11 @@ responsibility to ensure that."
   :type '(repeat string)
   :group 'org-roam)
 
-(defcustom org-roam-file-exclude-regexp nil
+(defcustom org-roam-file-exclude-regexp (list org-attach-id-dir)
   "Files matching this regular expression are excluded from the Org-roam."
   :type '(choice
+          (repeat
+           (string :tag "Regular expression matching files to ignore"))
           (string :tag "Regular expression matching files to ignore")
           (const :tag "Include everything" nil))
   :group 'org-roam)
@@ -193,14 +196,25 @@ FILE is an Org-roam file if:
          (ext (when path (org-roam--file-name-extension path)))
          (ext (if (string= ext "gpg")
                   (org-roam--file-name-extension (file-name-sans-extension path))
-                ext)))
+                ext))
+         (org-roam-dir-p (org-roam-descendant-of-p path org-roam-directory))
+         (valid-file-ext-p (member ext org-roam-file-extensions))
+         (match-exclude-regexp-p
+          (cond
+           ((not org-roam-file-exclude-regexp) nil)
+           ((stringp org-roam-file-exclude-regexp)
+            (string-match-p org-roam-file-exclude-regexp path))
+           ((listp org-roam-file-exclude-regexp)
+            (let (is-match)
+              (dolist (exclude-re org-roam-file-exclude-regexp)
+                (setq is-match (or is-match (string-match-p exclude-re path))))
+              is-match)))))
     (save-match-data
       (and
        path
-       (member ext org-roam-file-extensions)
+       org-roam-dir-p
-       (not (and org-roam-file-exclude-regexp
+       valid-file-ext-p
-                 (string-match-p org-roam-file-exclude-regexp path)))
+       (not match-exclude-regexp-p)))))
-       (org-roam-descendant-of-p path (expand-file-name org-roam-directory))))))
 
 (defun org-roam-list-files ()
   "Return a list of all Org-roam files under `org-roam-directory'.
@@ -322,6 +336,7 @@ E.g. (\".org\") => (\"*.org\" \"*.org.gpg\")"
   (require 'org-roam-id)
   (require 'org-roam-capture)
   (require 'org-roam-mode)
+  (require 'org-roam-log)
   (require 'org-roam-migrate))
 
 ;;; org-roam.el ends here

tests/test-org-roam-capture.el

@@ -46,6 +46,11 @@
      :to-equal "foo\n\n")
     (expect
      (org-roam-capture--fill-template "foo\n\t\n")
-     :to-equal "foo\n\t\n")))
+     :to-equal "foo\n\t\n"))
+
+  (it "expands templates when it's a function"
+    (expect
+     (org-roam-capture--fill-template (lambda () "foo"))
+     :to-equal "foo")))
 
 (provide 'test-org-roam-capture)