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. 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 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 implementation is yet incomplete; more features are expected. Note that this is
is not the first attempt to handle denote notes within vim. not the first attempt to handle denote notes within vim.
[Conan](https://zansh.in/) developed a [bash [Conan](https://zansh.in/) developed a [bash
script](https://github.com/shuckster/denote-md) for denote and an accompanying script](https://github.com/shuckster/denote-md) for denote and an accompanying
[vim plugin](https://github.com/shuckster/vim-denote-md). Also [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? ### Why?
The present package aims at handling denote notes the _vim way._ For instance, The present package aims at handling denote notes the _vim way._ For instance,
both plugins do not bind the default key combination 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 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. however, exists precisely for solving the problem at hand: following custom-made links.
Also, the present package aims at remaining flexible. Also, the present package aims at remaining flexible. Again, both
Again, both plugins require the denote note identifiers to follow the rigid above-mentioned plugins require the denote note identifiers to follow the rigid
format `YYYYMMDDTHHMMSS`. Per denote manual, the identify may be [any format `YYYYMMDDTHHMMSS`. Per denote manual, however, the identify may be [any
string](https://protesilaos.com/emacs/denote#h:3048f558-7d84-45d6-9ef2-53055483e801) string](https://protesilaos.com/emacs/denote#h:3048f558-7d84-45d6-9ef2-53055483e801)
(free of field delimiters, of course). (free of field delimiters, of course).
### Installation ### Installation
You may use any of your favorite plugin managers, or, place a copy of this You may use any of your favorite plugin managers, or, manually place a copy of
package in `~/.vim/pack/tools/start`. Then, run `:helptags ALL` to regenerate this package in, e.g., `~/.vim/pack/tools/start`. For such a manual
the help files. This will allow you to get more help using `:help denote` or installation, you may want to run `:helptags
similar commands. ~/.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 ### Usage
For _following links,_ simply move your cursor to the denote link, and press vim needs to know where your denote entries are stored. To do so, run the
`gf`. 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 After specifying the denote directory, the following functionalities are
[|'omnifunc'|](https://vimhelp.org/options.txt.html#%27omnifunc%27) option. So, available.
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.
_Browsing_ and _searching notes_ is implemented using the [location _Following links:_ Simply place your cursor on a denote link and press `gf` or
list](https://vimhelp.org/quickfix.txt.html#location-list). similar keys.
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.
#### Commands _Link completion:_ When editing a note, write any prefix of a denote link
This package defines the following user commands: (`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 ..}]`: _Browsing_ and searching notes:_ Browsing and searching is done using vim's
This command places all denote entries in the location list. [location list](https://vimhelp.org/quickfix.txt.html#location-list). The
You may supply any number of arguments to filter the notes by the given benefit of doing so is that commands like `:lnext`, `:lprev` etc. become
keywords. 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}`: _Adding notes:_ Run `:DenoteNew {title}` to add a new note with the given
With this, all notes of a given tag are listed. title.
The `{tag}` may be autocompleted by hitting the tab key.
- `:DenoteGrep /{pattern}/[g][j][f]`: [^1]: Run `:help g:denote_directories` for more information.
This command builds around
[:vimgrep](https://vimhelp.org/quickfix.txt.html#%3Avimgrep) and can be used to
search for patterns within your notes.
- `:DenoteBackReferences`: ### Example setup
With this, you may populate the location list with all links to the currently You get a possibly useful setup with a single default denote directory at
opened note. `~/Documents/notes/` by placing these lines in your vimrc file:
```vim
- `:DenoteNew {title}`: au VimEnter * DenoteDirectory ~/Documents/notes/
With this, a new note entry is generated with the supplied title. nnoremap <silent> <Leader>d :Denote<CR>
nnoremap <silent> <Leader>D :DenoteBackReferences<CR>
#### 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:
```
nnoremap ]l :lnext<CR> nnoremap ]l :lnext<CR>
nnoremap [l :lprevious<CR> nnoremap [l :lprevious<CR>
``` ```
### Customization After starting vim (in any directory), you can display all denote entries by
You can customize the behavior of this package using several global variables. using the `<Leader>d` key, move forwards and backwards in the list using the
Customization is explained in the [help file](doc/denote.txt), also accessible `]l` and `[l` keys, and list all back references to an opened note with the
through `:help denote-settings`. `<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 - Tag manipulation
- Title manipulation - Title manipulation
- Signature handling? - Signature handling?

114
doc/denote.txt
View File

@@ -1,4 +1,4 @@
*denote.txt* For Vim version 9.0. Last change: 2026 Feb 18 *denote.txt* For Vim version 9.0. Last change: 2026 Feb 26
This is the documentation for the denote plugin. This is the documentation for the denote plugin.
@@ -8,7 +8,6 @@ CONTENTS *vim-denote* *denote*
1. Introduction |denote-intro| 1. Introduction |denote-intro|
2. Commands |denote-commands| 2. Commands |denote-commands|
3. Settings |denote-settings| 3. Settings |denote-settings|
4. Mappings |denote-mappings|
============================================================================== ==============================================================================
*denote-intro* *denote-intro*
@@ -39,69 +38,102 @@ entries containing "foo" in the title.
*denote-commands* *denote-commands*
Commands ~ Commands ~
*:DenoteDirectory*
*:DenoteDirectory!*
:DenoteDirectory[!] {path}
Set the provided {path} as the denote directory that will be used by
all following commands. The {path} argument is autocompleted. With the
bang, the autocompletion works for all directories available on your
system. Without the bang, only directories listed in the
|g:denote_directories| variable are autocompleted.
*:Denote* *:Denote*
Populate the location list of the current window with the denote entries :Denote [{keyword ..}]
present in the current directory. This command may be supplemented with any Populate the location list of the current window with the denote
number of arguments that filter the entries. entries present in the current directory. This command may be
supplemented with any number of arguments that filter the entries
according to the appearance of the keywords in the file name.
*:DenoteTag* *:DenoteTag*
This command takes as argument a tag, and populates the location list with all :DenoteTag {tag}
denote entries of that are tagged accordingly. The tags are autocompleted This command takes as argument a tag, and populates the location list
(see, |c_<Tab>|). with all denote entries of that are tagged accordingly. The tags are
autocompleted (see, |c_<Tab>|). Also fuzzy matching is possible when
"fuzzy" is contained in |'wildoptions'|.
*:DenoteGrep* *:DenoteGrep*
This command is a wrapper around |:lvimgrep| to search for a pattern in the :DenoteGrep /{pattern}/[g][j][f]
denote entries. The required argument is a pattern as required by |:vimgrep|, This command is a wrapper around |:lvimgrep| to search for a pattern
i.e., /{pattern}/[g][j][f]. in the denote entries. The required argument is a pattern as required
by |:vimgrep|, i.e., /{pattern}/[g][j][f].
*:DenoteNew* *:DenoteNew*
This command takes as argument a note title, and generates a new denote entry :DenoteNew {title}
with the specified title. The entry file type is controlled by the setting This command takes as argument a note title, and generates a new
|g:denote_new_ft|. denote entry with the specified title. The entry file type is
controlled by the setting |g:denote_new_ft|.
*:DenoteBackReferences* *:DenoteBackReferences*
When called from an opened denote entry, this command populates the location :DenoteBackReferences
list with all references to the current note. This command populates the location list with all references to the
current note. This command can only be called from an opened denote
note.
*denote-settings* *denote-settings*
Settings ~ Settings ~
*g:denote_directories*
g:denote_directories list
With this option, may may specify a list of your denote directories.
This list is used for the autocompletion of the |:DenoteDirectory|
command. The default value is
>
let g:denote_directories = []
<
*g:denote_note_file_extension* *g:denote_note_file_extension*
With this setting you may specify the file extensions of all denote entries g:denote_note_file_extension list
within which |:DenoteGrep| will search for the provided pattern. If left With this setting, you may specify the file extensions of all denote
unspecified, it is set to the following default value: entries within which |:DenoteGrep| will search, and for which files
denote link completion and the |:DenoteBackReferences| command will be
available. If left unspecified, it is set to the following default
value:
> >
g:denote_note_file_extension = ['md', 'org', 'txt'] let g:denote_note_file_extension = ['md', 'org', 'txt']
< <
*g:denote_loc_title_columns* *g:denote_loc_title_columns*
This integer specifies the number of columns used to display the titles of g:denote_loc_title_columns number
denote entries. Per default, it is set to: This integer specifies the number of columns used to display the
titles of denote entries. Per default, it is set to:
> >
g:denote_loc_title_columns = 60 let g:denote_loc_title_columns = 60
< <
*g:denote_new_ft* *g:denote_new_ft*
Newly created notes are of this file type. Possible values are 'md', 'org', or g:denote_new_ft string
'txt', with the following default: Newly created notes are of this file type. Possible values are 'md',
'org', or 'txt', with the following default:
> >
g:denote_new_ft = 'md' let g:denote_new_ft = 'md'
< <
*g:denote_fm_md_type* *g:denote_fm_md_type*
The front matter of 'md' notes is given as 'yaml' or as 'toml'. By default, g:denote_fm_md_type string
this package uses 'yaml': The front matter of 'md' notes is given as 'yaml' or as 'toml'. By
default, this package uses 'yaml':
> >
g:denote_fm_md_type = 'yaml' let g:denote_fm_md_type = 'yaml'
< <
*g:denote_identifier_fun* *g:denote_identifier_fun*
Denote allows the use of custom identifiers. This variable, if set, points to g:denote_identifier_fun Funcref
a function that generates identifiers for newly created notes. The function is Denote allows the use of custom identifiers. This variable, if set,
supposed to return a unique string. points to a function that generates identifiers for newly created
notes. The function is supposed to return a unique string. By default,
*denote-mappings* the identifiers are computed with
Mappings ~ >
strftime('%Y%m%dT%H%M%S')
<Plug>DenoteList "Populate and open the location list with all <
denote entries". or with |rand()| if the function |strftime()| is unavailable.
<Plug>DenoteBackReferences "Populate and open the location list with all
denote entries that link to the currently opened one".
vim:tw=78:sw=4:ts=8:noet:ft=help:norl: vim:tw=78:sw=4:ts=8:noet:ft=help:norl: