Convenience commands for note creation

Sometimes the user needs to create a note that has different requirements from those of denote (Standard note creation). While this can be achieved globally by changing the denote-prompts user option, there are cases where an ad-hoc method is the appropriate one (The denote-prompts option).

To this end, Denote provides the following interactive convenience commands for note creation. They all work by appending a new prompt to the existing denote-prompts.

Create note by specifying file type

The denote-type command creates a note while prompting for a file type.

This is the equivalent of calling denote when denote-prompts has the ‘file-type’ prompt appended to its existing prompts. In practical terms, this lets you produce, say, a note in Markdown even though you normally write in Org (Standard note creation).

The denote-create-note-using-type is an alias of denote-type.

Create note using a date

Normally, Denote reads the current date and time to construct the unique identifier of a newly created note (Standard note creation). Sometimes, however, the user needs to set an explicit date+time value.

This is where the denote-date command comes in. It creates a note while prompting for a date. The date can be in YEAR-MONTH-DAY notation like ‘2022-06-30’ or that plus the time: ‘2022-06-16 14:30’.

The denote-date-prompt-use-org-read-date option.

This is the equivalent of calling denote when denote-prompts has the ‘date’ prompt appended to its existing prompts.

The denote-create-note-using-date is an alias of denote-date.

Create note in a specific directory

The denote-subdirectory command creates a note while prompting for a subdirectory. Available candidates include the value of the variable denote-directory and any subdirectory thereof (Denote does not create subdirectories).

This is the equivalent of calling denote when denote-prompts has the ‘subdirectory’ prompt appended to its existing prompts.

The denote-create-note-in-subdirectory is a more descriptive alias of denote-subdirectory.

Create note and add a template

The denote-template command creates a new note and inserts the specified template below the front matter (The denote-templates option). Available candidates for templates are specified in the user option denote-templates.

This is the equivalent of calling denote when denote-prompts has the ‘template’ prompt appended to its existing prompts.

The denote-create-note-with-template is an alias of the command denote-template, meant to help with discoverability.

Create note with a signature

The denote-signature command first prompts for an arbitrary string to use in the optional ‘SIGNATURE’ field of the file name and then asks for a title and keywords. Signatures are arbitrary strings of alphanumeric characters which can be used to establish sequential relations between file at the level of their file name (e.g. 1, 1a, 1b, 1b1, 1b2, …).

This is the equivalent of calling denote when denote-prompts has the ‘signature’ prompt appended to its existing prompts.

The denote-create-note-using-signature is an alias of the command denote-signature intended to make the functionality more discoverable.

1. Write your own convenience commands

   The convenience commands we provide only cover some basic use-cases (Convenience commands for note creation). The user may require combinations that are not covered, such as to prompt for a template and for a subdirectory, instead of only one of the two. To this end, we show how to follow the code we use in Denote to write your own variants of those commands.

   First let’s take a look at the definition of one of those commands. They all look the same, but we use denote-subdirectory for this example:

   (defun denote-subdirectory ()
     "Create note while prompting for a subdirectory.
   
   Available candidates include the value of the variable
   `denote-directory' and any subdirectory thereof.
   
   This is the equivalent of calling `denote' when `denote-prompts'
   has the `subdirectory' prompt appended to its existing prompts."
     (declare (interactive-only t))
     (interactive)
     (let ((denote-prompts (denote-add-prompts '(subdirectory))))
       (call-interactively #'denote)))

   The hyphenated word after defun is the name of the function. It has to be unique. Then we have the documentation string (or “docstring”) which is for the user’s convenience.

   This function is interactive, meaning that it can be called via ‘M-x’ or be assigned to a key binding. Then we have the local binding of the denote-prompts to the desired combination (“local” means specific to this function without affecting other contexts). Lastly, it calls the standard denote command interactively, so it uses all the prompts in their specified order.

   The function call (denote-add-prompts '(subdirectory)) will append the subdirectory prompt to the existing value of the denote-prompts. If, for example, the default value is ‘'(title keywords)’ (to prompt for a title and then for keywords), it will become ‘'(subdirectory title keywords)’ inside the context of this let. Remember that this is “local”, so the global value of denote-prompts remains unaffected.

   Now let’s say we want to have a command that (i) asks for a template (ii) for a subdirectory (The denote-templates option), and (iii) then goes through the remaining denote-prompts. All we need to do is tweak the let bound value of denote-prompts and give our command a unique name:

   ;; Like `denote-subdirectory' but also ask for a template
   (defun my-denote-subdirectory-with-template ()
     "Create note while also prompting for a template and subdirectory.
   
   This is the equivalent of calling `denote' when `denote-prompts' has the
   `subdirectory' and `template' prompts appended to its existing prompts."
     (declare (interactive-only t))
     (interactive)
     (let ((denote-prompts (denote-add-prompts '(subdirectory template))))
       (call-interactively #'denote)))

   The tweaks to denote-prompts determine how the command will behave (The denote-prompts option). Use this paradigm to write your own variants which you can then assign to keys, invoke with ‘M-x’, or add to the list of commands available at the denote-command-prompt (Choose which commands to prompt for).

   In the above scenario, we are using the denote-add-prompts function, which appends whatever prompts we want to the existing value of denote-prompts. If the user prefers to completely override the denote-prompts, they can set the value outright:

   (defun my-denote-subdirectory-with-template-title-and-keywords ()
     "Create a note while prompting for subdirectory, template, title, and keywords.
   
   This is the equivalent of calling `denote' when `denote-prompts' has the
   value '(template subdirectory title keywords)."
     (declare (interactive-only t))
     (interactive)
     (let ((denote-prompts '(subdirectory template title keywords)))
       (call-interactively #'denote)))