Custom templates in vimwiki

I got myself into a habit of using vimwiki for the past year: it helps me to keep track of random bits of information, work and project notes, as well as daily goals and achievements. You can read more about vimwiki in an article I wrote a while back: “Personal wiki with vimwiki”.

HTML page generated by vimwiki with a custom navigation bar.

One of vimwiki’s features I really like is an ability to convert whole wiki to HTML with a single command: :VimwikiAll2HTML. There is one annoyance though: HTML vimwiki pages don’t have any navigation elements: the only way to navigate between pages is by clicking through links within a page or using browser’s “back” button.

Luckily, vimwiki has a setting which allows using custom templates for generating HTML. Assuming your wiki is in $HOME/Dropbox/wiki (can be anywhere else though), make following changes to your .vimrc:

let g:vimwiki_list = [{
  \ 'path': '$HOME/Dropbox/wiki',
  \ 'template_path': '$HOME/Dropbox/wiki/templates',
  \ 'template_default': 'default',
  \ 'template_ext': '.html'}]

After that, create a $HOME/Dropbox/wiki/templates/default.html using vimwiki/autoload/vimwiki/default.tpl as a base. I added simple navigation bar to my default template:

<html>
<head>
    <link rel="Stylesheet" type="text/css" href="%root_path%style.css" />
    <title>%title%</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
</head>
<body>
    <a href="%root_path%index.html">Index</a> |
    <a href="%root_path%diary/diary.html">Diary</a>
    <hr>
    <div class="content">
    %content%
    </div>
</body>
</html>

Now it’s much easier to jump between wiki entries. Of course, customization doesn’t end there: you can change styles, add JavaScript and make your wiki all fancy and advanced.

If you’d like to get even better about using Vim, I wrote a book about it: Mastering Vim. I’m pretty proud of how it turned out, and I hope you like it too.

Comments