Variable: denote-file-name-components-order

denote-file-name-components-order is a customizable variable defined in denote.el.

Value

(identifier signature title keywords)

Documentation

Specify the order of the file name components.

The value is a list of the following symbols:

- identifier: This is the combination of the date and time. When it
  is the first on the list, it looks like "20240519T073456" and does
  not have a component separator of its own due its unambiguous format.
  When it is placed anywhere else in the file name, it is prefixed with
  "@@", so it looks like "@@20240519T073456".

- signature: This is an arbitrary string that can be used to qualify
  the file in some way, according to the user's methodology (e.g. to add
  a sequence to notes). The string is always prefixed with the "=="
  to remain unambiguous.

- title: This is an arbitrary string which describes the file. It is
  always prefixed with "--" to be unambiguous.

- keywords: This is a series of one or more words that succinctly
  group the file. Multiple keywords are separated by an underscore
  prefixed to each of them. The file name component is always prefixed
  with "__".

All four symbols must appear exactly once. Duplicates are ignored. Any missing symbol is added automatically.

Some examples:

    (setq denote-file-name-components-order
       '(identifier signature title keywords))
    => 20240519T07345==hello--this-is-the-title__denote_testing.org

    (setq denote-file-name-components-order
       '(signature identifier title keywords))
    => ==hello@@20240519T07345--this-is-the-title__denote_testing.org

    (setq denote-file-name-components-order
       '(title signature identifier keywords))
    => --this-is-the-title==hello@@20240519T07345__denote_testing.org

    (setq denote-file-name-components-order
       '(keywords title signature identifier))
    => __denote_testing--this-is-the-title==hello@@20240519T07345.org

Also see the user option denote-prompts, which affects which components are actually used in the order specified herein.

Before deciding on this, please consider the longer-term implications of file names with varying patterns. Consistency makes things predictable and thus easier to find. So pick one order and never touch it again. When in doubt, leave the default file-naming scheme as-is.

This user option should only be used to build a file name. Custom code should not have behaviors that depend on its value. The reason is that its value can change over time and Denote should be able to handle past and current notes.

This variable was added, or its default value changed, in denote version 3.0.0.

Source Code

;; Defined in ~/.emacs.d/elpa/denote-4.2.3/denote.el
(defcustom denote-file-name-components-order '(identifier signature title keywords)
  "Specify the order of the file name components.

The value is a list of the following symbols:

- `identifier': This is the combination of the date and time.  When it
  is the first on the list, it looks like \"20240519T073456\" and does
  not have a component separator of its own due its unambiguous format.
  When it is placed anywhere else in the file name, it is prefixed with
  \"@@\", so it looks like \"@@20240519T073456\".

- `signature': This is an arbitrary string that can be used to qualify
  the file in some way, according to the user's methodology (e.g. to add
  a sequence to notes).  The string is always prefixed with the \"==\"
  to remain unambiguous.

- `title': This is an arbitrary string which describes the file.  It is
  always prefixed with \"--\" to be unambiguous.

- `keywords': This is a series of one or more words that succinctly
  group the file.  Multiple keywords are separated by an underscore
  prefixed to each of them.  The file name component is always prefixed
  with \"__\".

All four symbols must appear exactly once.  Duplicates are ignored.  Any
missing symbol is added automatically.

Some examples:

    (setq denote-file-name-components-order
       \\='(identifier signature title keywords))
    => 20240519T07345==hello--this-is-the-title__denote_testing.org

    (setq denote-file-name-components-order
       \\='(signature identifier title keywords))
    => ==hello@@20240519T07345--this-is-the-title__denote_testing.org

    (setq denote-file-name-components-order
       \\='(title signature identifier keywords))
    => --this-is-the-title==hello@@20240519T07345__denote_testing.org

    (setq denote-file-name-components-order
       \\='(keywords title signature identifier))
    => __denote_testing--this-is-the-title==hello@@20240519T07345.org

Also see the user option `denote-prompts', which affects which
components are actually used in the order specified herein.

Before deciding on this, please consider the longer-term implications
of file names with varying patterns. Consistency makes things
predictable and thus easier to find. So pick one order and never touch
it again. When in doubt, leave the default file-naming scheme as-is.

This user option should only be used to build a file name.  Custom code
should not have behaviors that depend on its value.  The reason is that
its value can change over time and Denote should be able to handle past
and current notes."
  :group 'denote
  :package-version '(denote . "3.0.0")
  ;; FIXME 2024-05-19: This technically works to display the user
  ;; option in the Custom buffer and to show its current value, though
  ;; it does not allow the user to modify it graphically: they have to
  ;; switch to the Lisp expression.  Find a way to present an
  ;; interface that lets the user reorder those elements.
  ;;
  ;; Still, making this a defcustom helps with discoverability, as
  ;; well as with the use of `setopt' and related.
  :type '(list
          (const :tag "Identifier component (date and time)" identifier)
          (const :tag "File signature (text to qualify a file)" signature)
          (const :tag "The title of the file" title)
          (const :tag "Keywords of the file" keywords)))