[Πρωτεσίλαος](https://protesilaos.com/about/) built the note-taking tool
[denote](https://protesilaos.com/emacs/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](https://zansh.in/) developed a [bash
script](https://github.com/shuckster/denote-md) for denote and an accompanying
[vim plugin](https://github.com/shuckster/vim-denote-md). Also
[Ashton](https://lambdaland.org/) built such a [plugin](https://git.sr.ht/~ashton314/vim-denote).

### Why?
The present package aims at handling denote notes the _vim way._ For instance,
both plugins do not bind the default key combination
[`gf`](https://vimhelp.org/editing.txt.html#gf) to follow links.
The vim option
[`'includeexpr'`](https://vimhelp.org/options.txt.html#%27includeexpr%27),
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](https://protesilaos.com/emacs/denote#h:3048f558-7d84-45d6-9ef2-53055483e801)
(free of field delimiters, of course).

### 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` 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`[^1] variable in your
[vimrc](https://vimhelp.org/starting.txt.html#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](https://vimhelp.org/insert.txt.html#compl-omni) 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](https://vimhelp.org/quickfix.txt.html#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](https://vimhelp.org/quickfix.txt.html#%3Avimgrep).

_Adding notes:_ Run `:DenoteNew {title}` to add a new note with the given
title.

[^1]: Run `:help g:denote_directories` for more information.

### 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:
```vim
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](doc/denote.txt), also accessible through `:help denote-settings`.

### Future features These features are planned:
- Tag manipulation
- Title manipulation
- Signature handling?
- Note deletion?