Summary: Convenience functions for using Denote in multiple silos
Requires: emacs-28.1, denote-3.1.0
Website: https://github.com/protesilaos/denote-silo
Maintainer: Protesilaos Stavrou <i...@protesilaos.com>
Author: Protesilaos Stavrou <i...@protesilaos.com>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DENOTE-SILO: CONVENIENCE FUNCTIONS TO WORK WITH
MULTIPLE DENOTE SILOS
Protesilaos Stavrou
i...@protesilaos.com
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
This manual, written by Protesilaos Stavrou, describes the customization
options for the Emacs package called `denote-silo' (or
`denote-silo.el'), and provides every other piece of information
pertinent to it.
The documentation furnished herein corresponds to stable version 0.0.0,
released on N/A. Any reference to a newer feature which does not yet
form part of the latest tagged commit, is explicitly marked as such.
Current development target is 0.1.0-dev.
⁃ Package name (GNU ELPA): `denote-silo' (⚠️ Not available yet)
⁃ Official manual: <https://protesilaos.com/emacs/denote-silo>
⁃ Git repository: <https://github.com/protesilaos/denote-silo>
⁃ Backronym: Denote… Silos Insulate Localised Objects.
If you are viewing the README.org version of this file, please note that
the GNU ELPA machinery automatically generates an Info manual out of it.
Table of Contents
─────────────────
1. COPYING
2. Overview
.. 1. Create new notes in silos
.. 2. Switch to a silo directory
.. 3. Make Org export work with silos
3. Installation
.. 1. GNU ELPA package
.. 2. Manual installation
4. Sample configuration
5. Acknowledgements
6. GNU Free Documentation License
7. Indices
.. 1. Function index
.. 2. Variable index
.. 3. Concept index
1 COPYING
═════════
Copyright (C) 2022-2025 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify
this document under the terms of the GNU Free
Documentation License, Version 1.3 or any later version
published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover Texts being “A
GNU Manual,” and with the Back-Cover Texts as in (a)
below. A copy of the license is included in the section
entitled “GNU Free Documentation License.”
(a) The FSF’s Back-Cover Text is: “You have the freedom to
copy and modify this GNU manual.”
2 Overview
══════════
The `denote-silo' package makes it easier to work with multiple
“silos”, as explained in the Denote manual. In short, a “silo” is a
localised `denote-directory' that is not connected to the
default/global `denote-directory' and other silos.
The code of `denote-silo' used to be bundled up with the `denote'
package before version `4.0.0' of the latter and was available in the
file `denote-silo-extras.el'. Users of the old code will need to adapt
their setup to use the `denote-silo' package. This can be done by
replacing all instances of `denote-silo-extras' with `denote-silo'
across their configuration.
2.1 Create new notes in silos
─────────────────────────────
The user option `denote-silo-directories' specifies a list of
directories that the user has set up as `denote-directory' silos.
The command `denote-silo-create-note' prompts for a directory among
`denote-silo-directories' and runs the `denote' command from there.
Similar to the above, the command `denote-silo-open-or-create' prompts
for a directory among `denote-silo-directories' and runs the
`denote-open-or-create' command from there.
The command `denote-silo-select-silo-then-command' prompts with
minibuffer completion for a directory among `denote-silo-directories'.
Once the user selects a silo, a second prompt asks for a Denote
note-creation command to call from inside that silo (read about the
“Points of entry” in the Denote manual).
2.2 Switch to a silo directory
──────────────────────────────
The command `denote-silo-dired' prompts for a silo directory among
those specified in the user option `denote-silo-directories' and
switches to it using `dired'.
The command `denote-silo-cd' is the same as above, except it used the
`cd' to perform the switch. This is more subtle because the current
buffer does not change, even though the “current directory” is
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.
2.3 Make Org export work with silos
───────────────────────────────────
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:
┌────
│ (setq org-export-allow-bind-keywords t)
└────
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:
┌────
│ #+bind: denote-directory "/path/to/silo/"
└────
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:
┌────
│ ;;; 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"))))
└────
[ 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. ]
3 Installation
══════════════
3.1 GNU ELPA package
────────────────────
The package is available as `denote-silo'. Simply do:
┌────
│ M-x package-refresh-contents
│ M-x package-install
└────
And search for it.
GNU ELPA provides the latest stable release. Those who prefer to
follow the development process in order to report bugs or suggest
changes, can use the version of the package from the GNU-devel ELPA
archive. Read:
<https://protesilaos.com/codelog/2022-05-13-emacs-elpa-devel/>.
3.2 Manual installation
───────────────────────
Assuming your Emacs files are found in `~/.emacs.d/', execute the
following commands in a shell prompt:
┌────
│ cd ~/.emacs.d
│
│ # Create a directory for manually-installed packages
│ mkdir manual-packages
│
│ # Go to the new directory
│ cd manual-packages
│
│ # Clone this repo, naming it "denote-silo"
│ git clone https://github.com/protesilaos/denote-silo denote-silo
└────
Finally, in your `init.el' (or equivalent) evaluate this:
┌────
│ ;; Make Elisp files in that directory available to the user.
│ (add-to-list 'load-path "~/.emacs.d/manual-packages/denote-silo")
└────
Everything is in place to set up the package.
4 Sample configuration
══════════════════════
┌────
│ (use-package denote-silo
│ :ensure t
│ ;; Bind these commands to key bindings of your choice.
│ :commands ( denote-silo-create-note
│ denote-silo-open-or-create
│ denote-silo-select-silo-then-command
│ denote-silo-dired
│ denote-silo-cd ))
└────
5 Acknowledgements
══════════════════
Denote Silo is meant to be a collective effort. Every bit of help
matters.
Author/maintainer
Protesilaos Stavrou.
6 GNU Free Documentation License
════════════════════════════════
7 Indices
═════════
7.1 Function index
──────────────────
7.2 Variable index
──────────────────
7.3 Concept index
─────────────────
