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?

144
doc/denote.txt
View File

@@ -1,17 +1,16 @@
*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.
==============================================================================
CONTENTS *vim-denote* *denote*
1. Introduction |denote-intro|
2. Commands |denote-commands|
3. Settings |denote-settings|
4. Mappings |denote-mappings|
1. Introduction |denote-intro|
2. Commands |denote-commands|
3. Settings |denote-settings|
==============================================================================
*denote-intro*
*denote-intro*
Introduction ~
Denote is a file-naming scheme developed by Protesilaos Stavrou and an Emacs
@@ -37,71 +36,104 @@ prefix of a denote link. This completion also works with titles: by invoking
omni completion after typing "denote:foo", denote links are completed for
entries containing "foo" in the title.
*denote-commands*
*denote-commands*
Commands ~
*:Denote*
Populate the location list of the current window with the denote entries
present in the current directory. This command may be supplemented with any
number of arguments that filter the entries.
*: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.
*:DenoteTag*
This command takes as argument a tag, and populates the location list with all
denote entries of that are tagged accordingly. The tags are autocompleted
(see, |c_<Tab>|).
*:Denote*
:Denote [{keyword ..}]
Populate the location list of the current window with the denote
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.
*:DenoteGrep*
This command is a wrapper around |:lvimgrep| to search for a pattern in the
denote entries. The required argument is a pattern as required by |:vimgrep|,
i.e., /{pattern}/[g][j][f].
*:DenoteTag*
:DenoteTag {tag}
This command takes as argument a tag, and populates the location list
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'|.
*:DenoteNew*
This command takes as argument a note title, and generates a new denote entry
with the specified title. The entry file type is controlled by the setting
|g:denote_new_ft|.
*:DenoteGrep*
:DenoteGrep /{pattern}/[g][j][f]
This command is a wrapper around |:lvimgrep| to search for a pattern
in the denote entries. The required argument is a pattern as required
by |:vimgrep|, i.e., /{pattern}/[g][j][f].
*:DenoteBackReferences*
When called from an opened denote entry, this command populates the location
list with all references to the current note.
*:DenoteNew*
:DenoteNew {title}
This command takes as argument a note title, and generates a new
denote entry with the specified title. The entry file type is
controlled by the setting |g:denote_new_ft|.
*denote-settings*
*:DenoteBackReferences*
:DenoteBackReferences
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*
Settings ~
*g:denote_note_file_extension*
With this setting you may specify the file extensions of all denote entries
within which |:DenoteGrep| will search for the provided pattern. If left
unspecified, it is set to the following default value:
*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
>
g:denote_note_file_extension = ['md', 'org', 'txt']
let g:denote_directories = []
<
*g:denote_loc_title_columns*
This integer specifies the number of columns used to display the titles of
denote entries. Per default, it is set to:
*g:denote_note_file_extension*
g:denote_note_file_extension list
With this setting, you may specify the file extensions of all denote
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_loc_title_columns = 60
let g:denote_note_file_extension = ['md', 'org', 'txt']
<
*g:denote_new_ft*
Newly created notes are of this file type. Possible values are 'md', 'org', or
'txt', with the following default:
*g:denote_loc_title_columns*
g:denote_loc_title_columns number
This integer specifies the number of columns used to display the
titles of denote entries. Per default, it is set to:
>
g:denote_new_ft = 'md'
let g:denote_loc_title_columns = 60
<
*g:denote_fm_md_type*
The front matter of 'md' notes is given as 'yaml' or as 'toml'. By default,
this package uses 'yaml':
*g:denote_new_ft*
g:denote_new_ft string
Newly created notes are of this file type. Possible values are 'md',
'org', or 'txt', with the following default:
>
g:denote_fm_md_type = 'yaml'
let g:denote_new_ft = 'md'
<
*g:denote_identifier_fun*
Denote allows the use of custom identifiers. This variable, if set, points to
a function that generates identifiers for newly created notes. The function is
supposed to return a unique string.
*denote-mappings*
Mappings ~
*g:denote_fm_md_type*
g:denote_fm_md_type string
The front matter of 'md' notes is given as 'yaml' or as 'toml'. By
default, this package uses 'yaml':
>
let g:denote_fm_md_type = 'yaml'
<
<Plug>DenoteList "Populate and open the location list with all
denote entries".
*g:denote_identifier_fun*
g:denote_identifier_fun Funcref
Denote allows the use of custom identifiers. This variable, if set,
points to a function that generates identifiers for newly created
notes. The function is supposed to return a unique string. By default,
the identifiers are computed with
>
strftime('%Y%m%dT%H%M%S')
<
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: