About me

Writing notes with Vimwiki and Hugo static generator

5 mins read time ❤️ Views

Taking notes is important when you want to remember things. I used to have notebooks, which worked fine, but it’s complicated to search things when you have a lot of things. As a die hard Vim user, I decided to give a try to Vimwiki to help me organize my notes and ideas.

Vimwiki makes easy for you to create a personal wiki using the Vim text editor. A wiki is a collection of text documents linked together and formatted with plain text syntax that can be highlighted for readability using Vim’s syntax highlighting feature.

The plain text notes can be exported to HTML, which improves readability. In addition, it’s possible to connect external HTML converters like Jekyll or Hugo.

In this post I will show the main functionalities of Vimwiki and how to connect the Hugo fast markdown static generator.

Vimwiki notes writing in Vim

Markdown notes converted into HTML


With Vimwiki you can:

  • organize your notes and ideas in files that are linked together;
  • manage todo lists;
  • maintain a diary, writing notes for every day;
  • write documentation in simple markdown files;
  • export your documents to HTML.

Vim shortcuts

One of the main Vim advantages is the fact that it’s a modal editor, which means that it has different edition modes. Each edition mode gives different functionalities to each key. This increases the number of shortcuts without having to include multiple keyboard combinations. In Vimwiki this allows to write notes with ease.

When I want to write some notes, I just open Vim and then I use <Leader>w<Leader>w to create a new note for today with a name based on the current date. <Leader> is a key that can be configured in Vim, in my case it’s comma character (,).

If I want to look at my notes I can use <Leader>ww to open the wiki index file. I can use Enter key to follow links in the index. Backspace acts a return to the previous page.

I use CoC snippets to improve autocompletion. In markdown, I find this plugin very useful to create tables, code blocks and links. You can use snippets for almost every programming language, just take a look at the documentation.

When I want to preview the markdown file, I use <Leader>wh to convert the current wiki page to HTML and I added also a shortcut to open HTML with the browser.

In the following video you can see an example of this workflow in action.

Your browser doesn't support HTML5 video.

Searching in your notes

One of the advantages of digital notes are the fact that you can search quickly in multiple files using queries.

Vimwiki comes with a VimWikiSearch command (VWS) which is only a wrapper for Unix grep command. This command can search for patterns in case insensitive mode in all your notes.

An excellent way to implement labels and contexts for cross-correlating information is to assign tags to headlines. If you add tags to your Vimwiki notes, you can also use a VimwikiSearchTags command.

In both cases, when you are searching in your notes, the results will populate your local list, where you can move using Vim commands lopen to open the list, lnext to go to the next occurence and lnext for the previous occurence.


Vimwiki has a custom filetype called wiki, which is a little bit different from markdown. The native vimwiki2html command only works for wiki filetypes. If you want to transform your files to HTML using other filetypes, like markdown, you have to use a custom parser. Even if I’m not able to use Vimwiki native parser, I prefer markdown format because it’s very popular and simple.

These are some options to use as an external markdown parser:

  • Pandoc, which I think works pretty good, but requires a lot of haskell dependencies.
  • Python vimwiki markdown libraries, which I think has a lot of potential.
  • Static website generators like Jekyll, Hugo or Hexo.

I started using static website generators because it can also publish easily the notes as static webpages, which I wanted to publish in Github Pages.

My first option was Jekyll, which is the Github native supported static website generator. It’s easy to use and the syntax is very straightforward, but I started to regret it when I accumulated a lot of notes. Then I decided to use Hugo, which is claimed to be faster and since it’s been coded in Go, it has no dependencies. In the following table I show my compiling time results for both:

Compiling time Jekyll Hugo
10 pages 0.1 seconds 0.1 seconds
150 pages 48 seconds 0.5 seconds

I should say that I used Jekyll Github gems, which includes some unnecessary ruby Gems, so I think Jekyll performance can be increased. It’s a nice software that I use to publish this post, but still Hugo is faster.

Building Vimiki with Hugo

The .vimrc file contains vim configuration and it’s the place where one can put the definition about Vimwiki syntax and writing directory. As you can see in my configuration, I use markdown syntax and save my files under ~/Documents/vimwiki/.

" ~/.vimrc

let g:vimwiki_list = [{
  \ 'auto_export': 1,
  \ 'automatic_nested_syntaxes':1,
  \ 'path_html': '$HOME/Documents/vimwiki/_site',
  \ 'path': '$HOME/Documents/vimwiki/content',
  \ 'template_path': '$HOME/Documents/vimwiki/templates/',
  \ 'syntax': 'markdown',
  \ 'ext':'.md',
  \ 'template_default':'markdown',
  \ 'custom_wiki2html': '$HOME/.dotfiles/wiki2html.sh',
  \ 'template_ext':'.html'

The custom wiki2html file correspond to a script which is executed to transform markdown into HTML. This scripts calls Hugo executable file and tells Hugo to use the Vimwiki file path as a baseurl in order to maintain link dependencies.

# ~/.dotfiles/wiki2html.sh

env HUGO_baseURL="file:///home/${USER}/Documents/vimwiki/_site/" \
    hugo --themesDir ~/Documents/ -t vimwiki \
    --config ~/Documents/vimwiki/config.toml \
    --contentDir ~/Documents/vimwiki/content \
    -d ~/Documents/vimwiki/_site --quiet > /dev/null

The complete version of my ~/.vimrc can be found in my dotfiles repository.

Deploy Vimwiki to Github Pages

Hugo projects can be easily published to Github using Github Actions. The following script tells GitHub worker to use Hugo to build html at each push and publish the HTML files to Github pages.

name: 🚀 Publish Github Pages

on: push
    runs-on: ubuntu-latest

      - name: Git checkout
        uses: actions/checkout@v2

      - name: Setup hugo
        uses: peaceiris/actions-hugo@v2
          hugo-version: 'latest'

      - name: Build
        run: hugo --config config-gh.toml

      - name: 🚀 Deploy to GitHub pages
        uses: peaceiris/actions-gh-pages@v3
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          publish_branch: gh-pages
          publish_dir: ./public
          force_orphan: true

I like having one part of my notes published on Github Pages, at least the configuration notes, which can be found in my Github page. But there is also a part of notes that I keep private, for example my diary notes, where I may have some sensible information, so I keep it away from publication just by adding it to the .gitignore file. Here you can find my Github notes repository.


I like that fact that Hugo has no dependencies since it’s written in Go, so it’s very easy to install, just download it from the github project releases page. In addition is also a blazing fast static website converter, you can find benchmarks in the internet.

I have been using Vimwiki very often, it allows me to take notes very easily and also find information about things that happen in the past. When people ask things about last month meeting I can find what I have written easily by searching by dates, tags or just words.

Publishing my notes to github allows me to have a have a place where I can keep track of my vimwiki configuration and also publish simple notes that are not meant to be a blog post, like my install for arch linux or my text editor configuration.

In relation with 🏷️ vim, hugo, jekyll, github-actions:

Algolia search engine in Jekyll static pages

This article shows how to implementent Algolia searching engine in a static website and update the entries using Github Actions.

Muse: Mopidy web client with Snapcast support

Services like Mopidy and Snapcast are ideal to create a multiroom streaming audio player using devices like the RaspberryPi or android telephones. This posts presents a web interface that uses the state of the art web technologies and integrates nicely with Mopidy and Snapcast.

Search posts functionality in AMP static website make with Jekyll

Good web reference is related with how fast your web page loads. Google works in a web format called AMP, which makes loading pages faster but also imposes some restrictions, like no external javascript. It's not simple to add API calls in AMP so this post shows how to implement a search fonctionality in a static page.

Interactive dashboard using Google Analytics, Github Actions and Dc.js

This article shows how to use google analytics api to build a customized dashboard using javascript library dc.js and deploy them using Github Actions

Subscribe to my newsletter 📰

and share it with your friends: