amin/vim-denote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc/help: adjusted to current version

Browse Source
This commit is contained in:
Ämin Baumeler
2026-02-26 11:27:57 +01:00
parent 2015c0e32c
commit d6bc3cbb04
2 changed files with 153 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files

131
README.md
View File

@@ -4,8 +4,8 @@ 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 not complete, and more features are expected. Note that this
is not the first attempt to handle denote notes within vim.
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
@@ -14,91 +14,90 @@ script](https://github.com/shuckster/denote-md) for denote and an accompanying
### 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.
[`gf`](https://vimhelp.org/editing.txt.html#gf) to follow links.
The vim option
[|'includeexpr'|](https://vimhelp.org/options.txt.html#%27includeexpr%27),
[`'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 plugins require the denote note identifiers to follow the rigid
format `YYYYMMDDTHHMMSS`. Per denote manual, the identify may be [any
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, place a copy of this
package in `~/.vim/pack/tools/start`. Then, run `:helptags ALL` to regenerate
the help files. This will allow you to get more help using `:help denote` or
similar commands.
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
For _following links,_ simply move your cursor to the denote link, and press
`gf`.
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.
This package also provides denote _link completion_ using the
[|'omnifunc'|](https://vimhelp.org/options.txt.html#%27omnifunc%27) option. So,
the link is completed after pressing `<C-X><C-O>` while typing any prefix of a
denote link `denote:<identifier>`. 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.
After specifying the denote directory, the following functionalities are
available.
_Browsing_ and _searching notes_ is implemented using the [location
list](https://vimhelp.org/quickfix.txt.html#location-list).
This means that you may navigate your notes using, e.g., `:lopen` to open the
list, `:lnext` and `:lprev`, to move to the next or previous entry (the list
does not need to be opened for that), and `:lclose` for closing the location
list.
_Following links:_ Simply place your cursor on a denote link and press `gf` or
similar keys.
#### Commands
This package defines the following user commands:
_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.
- `:Denote [{keyword ..}]`:
This command places all denote entries in the location list.
You may supply any number of arguments to filter the notes by the given
keywords.
_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).
- `:DenoteTag {tag}`:
With this, all notes of a given tag are listed.
The `{tag}` may be autocompleted by hitting the tab key.
_Adding notes:_ Run `:DenoteNew {title}` to add a new note with the given
title.
- `:DenoteGrep /{pattern}/[g][j][f]`:
This command builds around
[:vimgrep](https://vimhelp.org/quickfix.txt.html#%3Avimgrep) and can be used to
search for patterns within your notes.
[^1]: Run `:help g:denote_directories` for more information.
- `:DenoteBackReferences`:
With this, you may populate the location list with all links to the currently
opened note.
- `:DenoteNew {title}`:
With this, a new note entry is generated with the supplied title.
#### Key mappings
This package also defines the following interface for key mappings, which
automatically open the location window:
- `<Plug>DenoteList` to list all denote notes, and
- `<Plug>DenoteBackReferences` to list all back references.
So, you may want to configure your keys like this:
```
nnoremap <silent> <Leader>d <Plug>DenoteList;
nnoremap <silent> <Leader>D <Plug>DenoteBackReferences;
```
You may also find the following keys favorable for navigation:
```
### 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>
```
### 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`.
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`).
### Future features
These features are planned:
### 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?