Contents

• VimwikiUtils
  • Introduction
• Features
  • Linking And Creating New Notes
    • VimwikiUtilsLink
    • VimwikiUtilsBacklinks
    • VimwikiUtilsRough
  • Organizing Notes
    • VimwikiUtilsTags
    • VimwikiUtilsEmbed
    • VimwikiUtilsGenerateIndex
    • VimwikiUtilsRename
  • Embedding And Editing Of Screenshots
    • VimwikiUtilsSc
    • VimwikiUtilsEditImage
• Installation
  • Packer
• Getting Started

VimwikiUtils

Note

This is a work in progress and my first time implementing a plugin for nvim.

Introduction

This plugin is an extension for VimWiki, trying to add to its many capabilities. It also has a predefined wiki structure, which I use in my bioinformatics studies. The wiki structure was inspired by this YouTube video.

/home/usr/zettelkasten/
.
├── 1_rough_notes/
│  ├── unprocessed_note.md
│  └── ...
├── 2_source_material/
│  ├── lecture_slides_1.pdf
│  └── ...
├── 3_tags/
│  ├── rna.md
│  ├── computer_science.md
│  ├── biochemistry.md
│  └── ...
├── 4_atomic_notes/
│  ├── atomic_note_1.md
│  ├── atomic_note_2.md
│  ├── atomic_note_3.md
│  └── ...
├── assets/
│  ├── screenshots/
│  │  ├── screenshot_1.png
│  │  ├── screenshot_2.png
│  │  └── ...
│  ├── gifs/
│  └── ...
├── templates/
│  ├── template_1.md
│  ├── template_2.md
│  └── ...
└── README.md

Features

Linking And Creating New Notes

VimwikiUtilsLink

Allows you to quickly link to an existing file or to create a new file based on a template. Pressing <C-b> in insert mode opens a telescope prompt showing all files in 4_atomic_notes/. Either hit <CR> on an existing note (creating a link to it), or press <A-CR> (options + enter) to create a new note (based on where you are currently at), which will be named after what you typed into the promt. This helps you to dynamically create new notes or link to already existing notes.
If you accidentally create a new atomic_note in e.g 3_tags/ or at root level of your wiki, just use VimwikiUtilsEmbed in order to move it to 4_atomic_notes/.

Choose a template, which you can create in your templates/ dir. For now, templates support a HEADER token, which gets replaced with the formatted name of your newly created note, and a DATE token, which gets replaced by the current date.

If you link to a new note (pressing <A-CR> while in VimwikiUtilsLink) from within a tag note (a note which is stored 3_tags/), a link to the corresponding tag will automatically be substituted into your template.

Note

This behavior only works, if your template contains the following pattern: > **tags:**.

VimwikiUtilsBacklinks

Find parent files linking to the currently opened file by pressing <leader>fb. Currently implemented pretty janky: The function calls telescope.live_grep() and inserts a formatted backlink pattern into the prompt. While in VimwikiUtilsBacklinks, press <A-CR> (options + enter) to generate an index containing all files linking to the current note.

VimwikiUtilsRough

Press <leader>nn to create a rough_note.md in your 1_rough_notes/ based on a chosen template. I use this for taking notes during the lecture. These notes should only be temperate and serve as additional information when creating an actual atomic_note.

VimwikiUtilsSource

Using this function you can linkt to your soure files (e.g lectures, papers, etc) stored in 2_source_material/. Make sure to name your sources clearly in order to prevent chaos.

Organizing Notes

VimwikiUtilsTags

Easily create or link to existing tags in 3_tags/, which are meant to also structure your wiki. An index can be generated, holding all files tagged by the current tag file. While in insert mode, press <C-e> to open a telescope prompt. Here all your tags will be displayed. Hit <CR> to create a link to the selected tag or hit <A-CR> (options + enter) to create a new tag (named after what you typed in the promt)

VimwikiUtilsEmbed

Helps handling notes stored in 1_rough_notes/ (or anywhere but 4_atomic_notes/) by automatically moving the currently opened note into your 4_atomic_notes/ dir after you abstract and summarize it.

VimwikiUtilsGenerateIndex

Generates a list of all files in 3_tags. You can put this list into your root README.md / index.md.

VimwikiUtilsRename

Due to the adjusted wiki structure, the default VimwikiRename doesn't work as expected. This function fixes said issue, it uses several matching patterns to identify links and replaces them using sed.

Embedding And Editing Of Screenshots

VimwikiUtilsSc

Note

This function calls a bash script which calls gnome-screenshot but you can replace it with any other script.

Take screenshots on the fly by and embed them into the current markdown file. After calling VimwikiUtilsSc you need to provide an image name. If that image already exists, nothing will happen, otherwise nvim will call the screenshot script after a 5 second delay. This way, you have enough time to set everything up.

VimwikiUtilsEditImage

Hovering over an embedded screenshot and pressing <leader>ii opens KolourPaint, a free and simple program for editing images. You can also replace it with any other light weight image editing software.

Default Key mappings

Keymap	Function
INSERT <C-b>	VimwikiUtilsLink
INSERT <C-e>	VimwikiUtilsTags
NORMAL <leader>nn	VimwikiUtilsRough
NORMAL <leader>fb	VimwikiUtilsBacklinks
NORMAL <leader>sc	VimwikiUtilsSc
NORMAL <leader>ii	VimwikiUtilsEditImage
NORMAL <leader>sm	VimwikiUtilsSource
NORMAL <leader>m	VimwikiUtilsEmbed
NORMAL <leader>wm	VimwikiUtilsGenerateIndex
NORMAL <leader>wr	VimwikiUtilsRename

Installation

Packer

use {
    'mweyrich28/vimwiki_utils',
    requires = {
        'nvim-telescope/telescope.nvim',
        'vimwiki/vimwiki'
    }
}

Getting Started

require('vimwiki_utils').setup({})

Or configure your keymaps and dirs like this:

require('vimwiki_utils').setup({
    global = {
        rough_notes_dir = "1_rough_notes",
        source_dir = "2_source_material",
        tag_dir = "3_tags",
        atomic_notes_dir = "4_atomic_notes",
        screenshot_dir = "assets/screenshots",
        kolourpaint = "/snap/bin/kolourpaint"
    },
    keymaps = {
        vimwiki_utils_link_key = '<C-b>',
        vimwiki_utils_tags_key = '<C-e>',
        vimwiki_utils_rough_key = '<leader>nn',
        vimwiki_utils_backlinks_key = '<leader>fb',
        vimwiki_utils_sc_key = '<leader>sc',
        vimwiki_utils_edit_image_key = '<leader>ii',
        vimwiki_utils_source_key = '<leader>sm',
        vimwiki_utils_embed_key = '<leader>m',
        vimwiki_utils_generate_index_key = '<leader>wm'
        vimwiki_utils_rename_key  = '<leader>wr'
    }
})

Make sure to create a wiki in your vimwiki.lua config like so:

vim.g.vimwiki_auto_chdir = 1 # this is currently necessary
vim.g.vimwiki_list = {
    {
        path = '~/path/to/zettelkasten/',
        syntax = 'markdown',
        ext = '.md',
        index = 'README'
    }
}