mykb/docs/vimwiki.md

# Vim-Wiki

## TL:DR - keybindings

- `<Leader>ww` -- Open default wiki index file.
- `<Leader>wt` -- Open default wiki index file in a new tab.
- `<Leader>ws` -- Select and open wiki index file.
- `<Leader>wd` -- Delete wiki file you are in.
- `<Leader>wr` -- Rename wiki file you are in.
- `<Enter>` -- Follow/Create wiki link.
- `<Shift-Enter>` -- Split and follow/create wiki link.
- `<Ctrl-Enter>` -- Vertical split and follow/create wiki link.
- `<Backspace>` -- Go back to parent(previous) wiki link.
- `<Tab>` -- Find next wiki link.
- `<Shift-Tab>` -- Find previous wiki link.


## General

Vim wiki is a vim plugin making it possible to effectivly keep wiki-style knowledge sorted on your local machine.
The single pages are written in markdown and are interlinked.
It can further be used as a Diary or to manage TODO lists, and to export the whole wiki in to an website, meaning single HTML files, which are interlinked and can be published.
Since every entry is a simple markdown file, this makes it easy to collaborate on a common wiki using git.

### Installation

The vim-wiki plugin can be installed like every vim plugin.
To test if the install was successful, execute `:VimwikiIndex` in the command prompt of vim.
You have to add the following lines to your `.vimrc`, irrespective of the installation method used.
```vim
set nocompatible
filetype plugin on
syntax on
```

#### [Vim-Plug](https://github.com/junegunn/vim-plug)

Add `Plug 'vimwiki/vimwiki'` to the Plug-Section of your `init.vim` or `.vimrc`.
Afterwords run `:PlugInstall` in the command prompt of vim.

#### [Pathogen](https://www.vim.org/scripts/script.php?script_id=2332)

Go to your vim config folder and clone the vimwiki github repository into the `bundle` folder.
```sh
cd $CONFIG/vim
mkdir bundle
cd bundle
git clone https://github.com/vimwiki/vimwiki.git
```
Afterwords run `:Helptags` in the command prompt of vim.

#### [Vundle](https://github.com/VundleVim/Vundle.vim)

Add `Plugin 'vimwiki/vimwiki'` to the `init.vim` or `.vimrc`.
Afterwords run `vim +PluginInstall +qall` in the shell to install it.

### Configuration

To go to the index page you enter `<leader>ww`.
For a bare vim-install this is `\ww`.
To change this, put the following line to your `.vimrc`:
```vim
map <leader>v :VimwikiIndex <Enter>
```
On default the directory for the markdown files is `~/vimwiki/index.wiki`.
To change this, add the following line to your `.vimrc`:
```vim
	let g:vimwiki_list = [{'path': '/PATH/TO/DIRECTORY/vimwiki', 'syntax': 'markdown', 'ext': '.md'}]
```
Here you can also add several wikis.
Assuming you want to have one wiki exclusively for coding related matters and an other one for every day related knowledge, add
```vim
let g:vimwiki_list = [
	\ {'path': '/PATH/wiki_code', 'syntax': 'markdown', 'ext': '.md'},
	\ {'path': '/PATH/wiki_household', 'syntax': 'markdown', 'ext': '.md'} ]
```
to your `.vimrc`.
To then select the correct wiki to go to, use `<leader>ws` to select which wiki you want to choose.
You can also use `[number] <leader>ww` to directly move to the corresponding wiki.

All the key bindings and how to remap them are listed under `:h vimwiki-mappings`.

### Basic Usage

#### Navigation

To navigate the vimwiki you need to know 3 basic commands.

1. Add a new page
	- To add a new page, you write the name of the main wiki-index page. Visually select the title of the page and press `<Enter>`. This creates a link to a new markdown file.
2. Go to a new page
	- To follow a link, press `<Enter>` on the link again, this opens the new markdown file.
3. Go one page back
	- To go back to the previous page, press `<Backspace>`.

#### Diary

To keep a diary in your vimwiki, use the `:VimwikiMakeDiaryNote` command. This opens a markdown file with the current date as its name.
Write your entry and save it.
To link the new entry to the diary index page, use `:VimwikiDiaryIndex` to go to the index page itself.
Then execute `:VimwikiDiaryGenerateLinks`. This adds all unlinked diary entries to the diary index page.
The default keybindings for this are
- `[number] <leader> wi`: Move to the diary index of wiki i.
- `[number] <leader> w <leader> w`: Open todays diary file for wiki i.
- `[number] <leader> w <leader> t`: Open todays diary file for wiki i in a new tab.

#### Encryption of pages

Using the [vim gnupg](https://github.com/jamessan/vim-gnupg) plugin, you can encrypt your pages.
This is done by first adding the folling line to your `.vimrc`.
```vim
let g:GPGFilePattern = '*.\(gpg\|asc\|pgp\)\(.md\)\='
```
To then create an encrypted entry, you have to add `.asc` to your link.
The new file will then be named `filename.asc.md`.
Opening it initially, a prompt will ask you which key to choose.
Select thee correct key and close the prompt.

#### Conversion to HTML

Vimwiki has the built in feature to export your wiki in to an HTML wiki.
The build in version only supports the vimwiki markup language.
If you write in this language, you should change the `vimwiki_list` command such that it includes `'syntax': 'vimwiki', 'ext': '.wiki'`.
Afterwords you can just run
```
:VimwikiAll2HTML
```
To only convert the current page to html, use `:Vimwiki2HTML`.
which converts all existing `.wiki` files in to html files and links them against each other.

To expand this capability to markdown, you have to include certain wrapper scripts.
 -  TODO