branch: externals/denote-silo
commit 6f6695f6784d686a2a024a57e08338a90b1c59e0
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Add section in the manual about binding silo denote-directory in Org export
---
README.org | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 58 insertions(+)
diff --git a/README.org b/README.org
index f26a19e81f..4c848a5911 100644
--- a/README.org
+++ b/README.org
@@ -120,6 +120,64 @@ different. Such an action is useful to, for example,
affect what a
shell or search command will consider as the current directory,
without necessarily changing context completely.
+** Make Org export work with silos
+:PROPERTIES:
+:CUSTOM_ID: h:make-org-export-work-with-silos
+:END:
+
+The Org export infrastructure is designed to ignore directory-local
+variables. This means that Denote silos, which depend on setting the
+local value of the variable ~denote-directory~, do not work as
+intended. More specifically, the Denote links do not resolve to the
+right file, because their path is changed during the export process.
+
+I brought this to the attention of the Org maintainer. The guidance
+from their side is to use the =#+bind= keyword to specify a local
+value for the ~denote-directory~:
<https://lists.gnu.org/archive/html/emacs-orgmode/2024-06/msg00206.html>.
+The prerequisite is to set ~org-export-allow-bind-keywords~ to a
+non-nil value:
+
+#+begin_src emacs-lisp
+(setq org-export-allow-bind-keywords t)
+#+end_src
+
+I do not think this is an elegant solution, but here are two possible
+ways to go about it, anyway:
+
+1. Manually add the =#+bind= keyword to each file you want to export.
+ It has to be like this:
+
+ #+begin_src emacs-lisp
+ ,#+bind: denote-directory "/path/to/silo/"
+ #+end_src
+
+2. Alternatively, you can make the Org front matter that Denote uses
+ for new files automatically include the =#+bind= keyword with its
+ desired value. Here is a complete =.dir-locals.el= which (i)
+ defines the silo and (ii) modifies the ~denote-org-front-matter~
+ accordingly:
+
+ #+begin_src emacs-lisp
+ ;;; Directory Local Variables. For more information evaluate:
+ ;;;
+ ;;; (info "(emacs) Directory Variables")
+
+ ((nil . ((denote-directory . "/path/to/silo/")
+ (denote-org-front-matter .
+ "#+title: %s
+,#+date: %s
+,#+filetags: %s
+,#+identifier: %s
+,#+bind: denote-directory \"/path/to/silo/\"
+\n"))))
+ #+end_src
+
+ [ Note that if you are reading the Org source of this manual, you
+ need to use the command ~org-edit-special~ on the above code
+ blocks before copying the code. This is because Org automatically
+ prepends a comma to disambiguate those entries from actual
+ keywords of the current file. ]
+
* Installation
:PROPERTIES:
:CUSTOM_ID: h:installation
