249 lines
9.2 KiB
Plaintext
249 lines
9.2 KiB
Plaintext
*denote.txt* Handling denote entries – the vim way
|
||
|
||
Last change: 2026 Feb 28
|
||
|
||
This is the documentation for the denote plugin.
|
||
|
||
==============================================================================
|
||
CONTENTS *vim-denote* *denote*
|
||
|
||
1. Introduction |denote-intro|
|
||
2. Commands |denote-commands|
|
||
2.1 Universal commands |denote-universal-commands|
|
||
2.2 Note command |denote-note-command|
|
||
2.3 Denote-list commands |denote-list-commands|
|
||
3. Settings |denote-settings|
|
||
4. Keys |denote-keys|
|
||
|
||
==============================================================================
|
||
INTRODUCTION *denote-intro*
|
||
|
||
Denote is a file-naming scheme developed by Protesilaos Stavrou and an Emacs
|
||
tool for handling such files. Notes and other files that follow this scheme
|
||
can be linked, and the links are preserved even when the files are renamed due
|
||
do adjusting the tags or changing the title of a note. The official manual is
|
||
available online:
|
||
https://protesilaos.com/emacs/denote
|
||
|
||
The denote plugin adds denote functionality to vim — the vim way. We are aware
|
||
of two other plugins, but we fear that these plugins are not flexible enough,
|
||
and more importantly, do not follow the vim philosophy for handling denote
|
||
notes. These mentioned plugins are available here:
|
||
https://github.com/shuckster/denote-md
|
||
https://git.sr.ht/~ashton314/vim-denote
|
||
|
||
In contrast to these plugins, the present package relies on the
|
||
|location-list| features for displaying denote entries, and on the options
|
||
'quickfixtextfunc', 'includeexpr', and 'omnifunc'. With these, denote links
|
||
can be followed using |gf|, and completed using omni completion (see,
|
||
|compl-omni|). For link completion, press |i_CTRL-X_CTRL-O| after typing any
|
||
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.
|
||
|
||
==============================================================================
|
||
COMMANDS *denote-commands*
|
||
|
||
After loading this package, only the first of the following commands is
|
||
available. This first command, as descried below, sets the directory to be
|
||
used for the denote entries. After that command has been issued, several other
|
||
commands become possible, such as |:DenoteTag|. Some command are available
|
||
within any window, others only in denote notes, and yet other again only in
|
||
the location-list that lists denote entries.
|
||
|
||
|
||
*denote-universal-commands*
|
||
Universal 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.
|
||
|
||
After the denote directory has been specified, the following commands become
|
||
available. They all operate on that specified directory.
|
||
|
||
*:Denote*
|
||
:Denote [{keyword ..}]
|
||
Populate the location list of the current window with the denote
|
||
entries present in the specified 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.
|
||
|
||
*:DenoteByTag*
|
||
:DenoteByTag {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'.
|
||
|
||
*: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].
|
||
|
||
*: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|.
|
||
|
||
*:DenoteCopy*
|
||
:DenoteCopy {file}
|
||
With this, the specified file is copied into the denote directory. The
|
||
file name is taken as the title, and the identifier is freshly
|
||
generated. Any file, i.e., not only those specified using
|
||
|g:denote_note_file_extension| may be chosen.
|
||
|
||
|
||
*denote-note-command*
|
||
Note command~
|
||
|
||
This is the only command exclusive to the windows that hold denote note
|
||
entries, i.e., files with an extension in |g:denote_note_file_extension|.
|
||
|
||
*: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-list-commands*
|
||
Denote-list commands~
|
||
|
||
The denote list may be opened using one of the commands |:Denote| or
|
||
|:DenoteByTag|. Also the commands |:DenoteGrep| and |:DenoteBackReferences|
|
||
open the location list, but not as a list of entries, but as a list of
|
||
matching patterns. The following commands are available in the denote list
|
||
(first case).
|
||
|
||
*:DenoteSetTitle*
|
||
:DenoteSetTitle {string}
|
||
The title of the selected entry is changed as specified.
|
||
|
||
*:DenoteTagAdd*
|
||
:DenoteTagAdd {tag}
|
||
With this, the provided tag is added to the list of tags of the
|
||
selected entry. The tag may be autocompleted. This command also
|
||
accepts a range, resulting in adding the tag to every entry within
|
||
that range.
|
||
|
||
*:DenoteTagRm*
|
||
:DenoteTagRm {tag}
|
||
Just as above, but for removing the specified tag.
|
||
|
||
*:DenoteDelete*
|
||
:DenoteDelete[!]
|
||
With this, the selected entry is deleted from the denote directory
|
||
(and from the disk). This command also accepts a range, to delete a
|
||
bunch of entries. After the deletion command has been invoked, the
|
||
user is asked to confirm the deletion. With the optional bang, no
|
||
confirmation will be asked.
|
||
|
||
|
||
==============================================================================
|
||
SETTINGS *denote-settings*
|
||
|
||
All settings described below are set to default values. For this package to
|
||
function, it is not necessary to specify a setting manually.
|
||
|
||
|
||
*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 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:
|
||
>
|
||
let g:denote_note_file_extension = ['md', 'org', 'txt']
|
||
<
|
||
|
||
*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:
|
||
>
|
||
let g:denote_loc_title_columns = 60
|
||
<
|
||
|
||
*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:
|
||
>
|
||
let g:denote_new_ft = 'md'
|
||
<
|
||
|
||
*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'
|
||
<
|
||
|
||
*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 variable set as
|
||
>
|
||
let g:Denote_identifier_fun = function('denote#meta#identifier_generate')
|
||
<
|
||
which calls |strftime('%Y%m%dT%H%M%S')| if |strftime()| is available,
|
||
and |rand()| otherwise. Another reasonable setting would be to use
|
||
some uuid generator and to specify, e.g.,
|
||
>
|
||
let g:Denote_identifier_fun = { -> system('uuidgen')
|
||
\ ->substitute('[^[:xdigit:]]', '', 'g') }
|
||
<
|
||
|
||
|
||
==============================================================================
|
||
KEYS *denote-keys*
|
||
|
||
The location lists generated by the present package, e.g., through the command
|
||
|:DenoteGrep| or |:DenoteByTag|, have the following key key-bindings.
|
||
|
||
*denote-r*
|
||
r Reload the location list.
|
||
|
||
*denote-q*
|
||
q Close the location list.
|
||
|
||
|
||
In addition, denote lists (see |denote-list-commands|) come with the following
|
||
keys:
|
||
|
||
*denote-list-C*
|
||
C Change the title of the selected entry.
|
||
|
||
*denote-list-+*
|
||
+ Add a tag to the selected entries (also in visual mode).
|
||
|
||
*denote-list--*
|
||
- As |denote-list-+| but for removing tags.
|
||
|
||
*denote-list-dd*
|
||
dd Delete the selected entry.
|
||
{Visual}d Delete the visually selected entries.
|
||
|
||
|
||
vim:tw=78:sw=4:ts=8:noet:ft=help:norl:
|