This is a Vim plugin that implements ideas of the Zettelkasten method using Vimwiki. It supports both Vimwiki and Markdown syntaxes.
You can read the full documentation using
:help vim-zettel
command in Vim after package installation.
Using Vundle:
Plugin 'vimwiki/vimwiki'
Plugin 'junegunn/fzf'
Plugin 'junegunn/fzf.vim'
Plugin 'michal-h21/vim-zettel'
Silver Searcher is used for searching in the notes by default.
The used command can be changed by setting the g:zettel_fzf_command
variable.
First of all, it is necessary to configure Vimwiki, as Vim-zettel
builds on top of it.
" Settings for Vimwiki
let g:vimwiki_list = [{'path':'~/scratchbox/vimwiki/markdown/','ext':'.md','syntax':'markdown'}, {"path":"~/scratchbox/vimwiki/wiki/"}]
To open the index page of your wiki, invoke Vim with the following parameters:
vim -c VimwikiIndex
Vim-zettel
also provides some custom configurations. The following sample
contains default values for available settings. It is not necessary to use
them in your .vimrc
unless you want to use a different value.
" Filename format. The filename is created using strftime() function
let g:zettel_format = "%y%m%d-%H%M"
" command used for VimwikiSearch
" default value is "ag". To use other command, like ripgrep, pass the
" command line and options:
let g:zettel_fzf_command = "rg --column --line-number --ignore-case --no-heading --color=always "
" Disable default keymappings
let g:zettel_default_mappings = 0
" This is basically the same as the default configuration
augroup filetype_vimwiki
autocmd!
autocmd FileType vimwiki imap <silent> [[ [[<esc><Plug>ZettelSearchMap
autocmd FileType vimwiki nmap T <Plug>ZettelYankNameMap
autocmd FileType vimwiki xmap z <Plug>ZettelNewSelectedMap
autocmd FileType vimwiki nmap gZ <Plug>ZettelReplaceFileWithLink
augroup END
" Set template and custom header variable for the second Wiki
let g:zettel_options = [{},{"front_matter" : {"tags" : ""}, "template" : "~/mytemplate.tpl"}]
By default, Vim-zettel
creates filename in the form YYMMDD-HHMM
. This
format can be changed using the g:zettel_format
variable. Any date and time
formats supported by the strftime()
function.
It is also possible to use other formatting strings:
%title
-- insert sanitized title%raw_title
-- insert raw titlefile_no
-- sequentially number files in wikifile_alpha
-- sequentially number files in wiki, but use characters instead of numbers
To use filename based on current time and note title, you can use the following format:
let g:zettel_format = "%y%m%d-%H%M-%title"
For sequentialy named files use:
let g:zettel_format = "%file_no"
It is possible to populate new notes with basic structure using templates.
Template can be declared using the g:zettel_options
variable:
let g:zettel_options = [{"template" : "~/path/to/mytemplate.tpl"}]
Sample template:
= %title =
Backlink: %backlink
----
%footer
Variables that start with the %
will be expanded. Supported variables:
%title
- title of the new note%backlink
- back link to the parent note%footer
- text from the parent note footer. Footer is separated from the main text by horizontal rule (----
). It can contain some information shared by notes. For example notes about publication can share citation of that publication.
Vim-zettel
adds some commands and mappings on top of
Vimwiki. See Vimwiki documentation on how to set up a
basic wiki and navigate it.
-
:ZettelNew
command – it will create a new wiki file named as%y%m%d-%H%M.wiki
(it is possible to change the file name format usingg:zettel_format
variable). The file uses basic template in the form%title Note title %date current date
where title is the first parameter to
:ZettelNew
. -
:ZettelOpen
command - perform fulltext search using FZF. -
:ZettelBackLinks
command – insert list of notes that link to the current note. -
:ZettelInbox
command – insert list of notes that no other note links to. -
:ZettelGenerateLinks
command – insert list of all wiki pages in the current page. It needs updated tags database. The tags database can be updated using the:VimwikiRebuildTags
command. -
:ZettelGenerateTags
command – insert list of tags and pages that used these tags in the current page. It needs updated tags database. The tags database can be updated using the:VimwikiRebuildTags
command. It only supports theVimwiki
style tags in the form:tag1:tag2
. These work even in theMarkdown
mode. -
z
command in the visual mode – create a new wiki file using selected text for the note title -
[[
command in the insert mode – create a link to a note. It uses FZF for the note searching. -
T
command in the normal mode – yank the current note filename and title as a Vimwiki link -
gZ
command in the normal mode – replace file path under cursor with Wiki link
Vim-zettel
provides way to search notes in your Zettelkasten and insert the
selected notes in the current document. The notes are automatically converted
to the document syntax format using Pandoc.
:ZettelInsertNote
- select notes using FZF. Multiple notes can be selected using the<TAB>
key. The selected notes are inserted in the current document.
:VimwikiBacklinks
- display files that link to the current page:VimwikiCheckLinks
- display files that no other file links to
-
:ZettelCapture
- create a new Zettel from a file. This command is useful for scripting. It can be used in the following way:vim -c ZettelCapture filename
The original file contents will be replaced with a path to the new wiki file. It should be used with temporary files!
The following packages may be useful in conjunction with Vimwiki and Vim-zettel:
- Notational FZF - fast searching
notes with preview window. Similar functionality is now built in in
Vim-Zettel
using:ZettelOpen
command.
To search in the Zettelkasten, set the following variable with path to the Zettelkaster direcory in .vimrc
:
let g:nv_search_paths = ['/path/to/zettelkasten/dir']
- Vimwiki-sync - automatically commit changes in wiki and synchronize them with external Git repository.