Πρωτεσίλαος built the note-taking tool denote for Emacs. In essence, denote is a straightforward and handy file-naming scheme for all kinds of files. This, e.g., allows altering the title of a note without breaking the web of links.

The present vim package reproduces some of the denote features for vim. The implementation is yet incomplete; more features are expected. Note that this is not the first attempt to handle denote notes within vim. Conan developed a bash script for denote and an accompanying vim plugin. Also Ashton built such a plugin.

Why?

The present package aims at handling denote notes the vim way. For instance, both plugins do not bind the default key combination gf to follow links. The vim option 'includeexpr', however, exists precisely for solving the problem at hand: following custom-made links.

Also, the present package aims at remaining flexible. Again, both above-mentioned plugins require the denote note identifiers to follow the rigid format YYYYMMDDTHHMMSS. Per denote manual, however, the identify may be any string (free of field delimiters, of course). This package offers great flexibility in configuration (see :help denote-settings).

Installation

You may use any of your favorite plugin managers, or, manually place a copy of this package in, e.g., ~/.vim/pack/tools/start. For such a manual installation, you may want to run :helptags ~/.vim/pack/tools/start/vim-denote/doc to regenerate the help files. This allows you to display the package documentation using :help vim-denote and similar commands.

Usage

vim needs to know where your denote entries are stored. To do so, run the command :DenoteDirectory! <path> where <path> points to your denote directory. You may also define the g:denote_directories¹ variable in your vimrc as a list of paths to denote directories. The benefit of doing so is that the :DenoteDirectory command (without bang) auto completes the paths to these directories.

After specifying the denote directory, the following functionalities are available.

Following links: Simply place your cursor on a denote link and press gf or similar keys.

Link completion: When editing a note, write any prefix of a denote link (denote:<identifier>) and invoke Omni completion by pressing <C-X><C-O>. Even more so, if this completion is invoked after typing denote:<str>, then the link is completed for denote entries that have <str> as part of the title.

Browsing and searching notes: Browsing and searching is done using vim's location list. The benefit of doing so is that commands like :lnext, :lprev etc. become available.

• The command :Denote [{keyword ..}] lists all denote entries. The optional argument filters these entries by the appearance of the keyword in the file name.
• The command :DenoteByTag {tag} lists all denote entries of a given tag. This command come with auto completion.
• On an open note, the command DenoteBackReferences lists all references to that note.
• Finally, the command :DenoteGrep /{pattern}/[g][j][f] searches within the denote entries for the given pattern.

Adding notes: Run :DenoteNew {title} to add a new note with the given title. You may also copy a file (any file) to your denote directory. To do so, run :DenoteCopy {file}.

Managing entries: You can change the title of denote entries using :DenoteSetTitle {newtitle}. Also, you can add and remove tags using :DenoteTagAdd {tag} and :DenoteTagRm {tag}, respectively. These latter two commands offer auto completion for the tags. Also, they accept line ranges that may be given via, e.g., visual selection. Finally, denote entries are deleted using :DenoteDelete. This command again accepts line ranges.

Basic keys

The denote location-list window comes with a set of keys:

• q: close the list
• r: reload the list
• C: rename the selected entry
• +: add a tag to the entry (also in visual mode)
• -: remove a tag from the entry (also in visual mode)
• dd: delete the selected entry (also in visual mode, using a single d)

Example setup

You get a possibly useful setup with a single default denote directory at ~/Documents/notes/ by placing these lines in your vimrc file:

au VimEnter * DenoteDirectory ~/Documents/notes/
nnoremap <silent> <Leader>d :Denote<CR>
nnoremap <silent> <Leader>D :DenoteBackReferences<CR>
nnoremap ]l :lnext<CR>
nnoremap [l :lprevious<CR>

After starting vim (in any directory), you can display all denote entries by using the <Leader>d key, move forwards and backwards in the list using the ]l and [l keys, and list all back references to an opened note with the <Leader>D key (again, you can jump around the references using [l and ]l).

Customization

You can customize the behavior of this package using several global variables. Customization is explained in the help file, also accessible through :help denote-settings.

Future features

• Signature handling?
• Subdirectories
• Denote query links

---

1. Run :help g:denote_directories for more information. ↩︎