120 lines
5.5 KiB
Markdown
120 lines
5.5 KiB
Markdown
[Πρωτεσίλαος](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. 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.
|
|
|
|
[^1]: Run `:help g:denote_directories` for more information.
|
|
|
|
### 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:
|
|
```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
|
|
- Signature handling?
|
|
- Subdirectories
|
|
- Denote query links
|