The file-naming scheme
Notes are stored in the denote-directory. The default path is ‘~/Documents/notes’. The denote-directory can be a flat listing, meaning that it has no subdirectories, or it can be a directory tree. Either way, Denote takes care to only consider “notes” as valid candidates in the relevant operations and will omit other files or directories.
Every note produced by Denote follows this pattern by default (Points of entry):
@@ID==SIGNATURE--TITLE__KEYWORDS.EXTENSIONThe ‘ID’ field represents the identifier which, by default, is the date in year-month-day format followed by the capital letter ‘T’ (for “time”) and the current time in hour-minute-second notation. The presentation is compact: ‘20220531T091625’. When it has this format (the default), the delimiter (‘@@’) is optional. The ‘ID’ serves as the unique identifier of each note and, as such, is also known as the file’s ID or identifier. The ‘ID’ can be any string: it does not need to be associated with a date (Define a completely custom identifier scheme).
File names can include an arbitrary string of alphanumeric characters in the ‘SIGNATURE’ field. Signatures have no clearly defined purpose and are up to the user to define. They can serve as special labels, such as ‘part1’ and ‘part2’ of a large file, or as priority indicators like ‘a’, ‘b’, ‘c’, or even context/scope specifiers like ‘home’ and ‘work’. Another use-case is to write sequences of thoughts, such that notes form a hierarchy, something we support with the optional and comprehensive extension ‘denote-sequence.el’ (Write sequence notes or “folgezettel”). Signatures are an optional extension to Denote’s file-naming scheme. In the simplest form, they can be added to newly created files on demand, with the command denote-signature, or by modifying the value of the user option denote-prompts (The denote-prompts option).
The ‘TITLE’ field is the title of the note, as provided by the user. It can contain any character, though the default is to have it downcased and hyphenated (Sluggification of file name components). An entry about “Economics in the Euro Area” produces an ‘economics-in-the-euro-area’ string for the ‘TITLE’ of the file name.
The ‘KEYWORDS’ field consists of one or more entries demarcated by an underscore (the separator is inserted automatically). Each keyword is a string provided by the user at the relevant prompt which broadly describes the contents of the entry.
Each of the keywords is a single word, with multiple keywords providing the multi-dimensionality needed for advanced searches through Denote files. Users who need to compose a keyword out of multiple words such as camelCase/CamelCase and are encouraged to use the denote-file-name-slug-functions user option accordingly (Sluggification of file name components).
The ‘EXTENSION’ is the file type. By default, it is ‘.org’ (org-mode) though the user option denote-file-type provides support for Markdown with YAML or TOML variants (‘.md’ which runs markdown-mode) and plain text (‘.txt’ via text-mode). Consult its docstring for the minutiae. While files end in the ‘.org’ extension by default, the Denote code base does not actually depend on org.el and/or its accoutrements.
Examples:
20220610T043241--initial-thoughts-on-the-zettelkasten-method__notetaking.org
20220610T062201--define-custom-org-hyperlink-type__denote_emacs_package.md
20220610T162327--on-hierarchy-and-taxis__notetaking_philosophy.txtThe different field separators, namely ‘--’ and ‘__’ introduce an efficient way to anchor searches (such as with Emacs commands like isearch or from the command-line with find and related). A query for ‘_word’ always matches a keyword, while a regexp in the form of, say, ‘"\\([0-9T]+?\\)--\\(.*?\\)_"’ captures the date in group ‘\1’ and the title in ‘\2’ (test any regular expression in the current buffer by invoking ‘M-x re-builder’).
Features of the file-naming scheme for searching or filtering.
All file name fields can contain any character, are optional and can appear in any order. The following permutations are valid:
ID.EXT
ID--TITLE.EXT
ID__KEYWORDS.EXT
ID==SIGNATURE.EXT
ID==SIGNATURE--TITLE.EXT
ID==SIGNATURE--TITLE__KEYWORDS.EXT
ID==SIGNATURE__KEYWORDS.EXTCommands such as denote or denote-rename-file will prompt for the file name fields configured in denote-prompts.
When in doubt, stick to the default design, which is carefully considered and works well (Change the order of file name components).
While Denote is an Emacs package, notes should work long-term and not depend on the functionality of a specific program. The file-naming scheme we apply guarantees that a listing is readable in a variety of contexts. The Denote file-naming scheme is, in essence, an effective, low-tech invention.