Wednesday. December 10, 2025
A couple of days ago, I stumbled over a Mastodon post by @johl, in which [he shared vimwiki](https://github.com/vimwiki/vimwiki) as his approach for taking notes in vim. Which immediately piqued my interest, as I have so far been just taking my notes in plain vim without a way of linking them. While I’m not someone that really uses (or feels any benefits from) second brain note-taking1, I do take enough project-related notes that being able to cross-reference prior notes c…
Wednesday. December 10, 2025
A couple of days ago, I stumbled over a Mastodon post by @johl, in which [he shared vimwiki](https://github.com/vimwiki/vimwiki) as his approach for taking notes in vim. Which immediately piqued my interest, as I have so far been just taking my notes in plain vim without a way of linking them. While I’m not someone that really uses (or feels any benefits from) second brain note-taking1, I do take enough project-related notes that being able to cross-reference prior notes could be useful for me. And in the process of trying, I also found out that it also works great for interacting with forgejo wikis – as e.g. used in many FLOSS projects on Codeberg.2
Vimwiki allows you to set up one or multiple folders as (different) wikis. When opening a Wiki, you can create a link to another existing or new file, by just pressing <Enter> in normal vim mode. Pressing <Enter> when the cursor is over an existing link opens that file, <Backspace> takes you back to the prior page. Plus, there’s a diary function, where one can create pages for specific dates, which can handle daily note-taking, to-do lists with checkboxes etc.
By default, Vimwiki uses its own syntax for taking notes, which seems to be a dialect/mashup of Markdown and MediaWiki formatting. But it also supports Markdown and MediaWiki as optional syntax settings. The support for Markdown is particularly key for me, as I’m already taking all my notes using that particular format, so there’s very little additional learning required. It just requires a little bit of setup in your vim settings to make it use Markdown formatting and use *.md as the file extension. Plus, the folding of vim-markdown can be made to work too, which is useful for larger wiki pages.
The other benefit of using Markdown, given my pre-existing setup, is that I have already written Markdown templates that can be chosen when editing a new *.md file in vim. Beyond having templates for blog posts (like this one) – that provide all the necessary front matter – I also have a note-taking template for daily notes & todos. It automatically fills in the current date as a top-level heading, and creates a section for to-do items and notes.
There is one more cool feature that comes with using Markdown as the syntax for Vimwiki: Forgejo, the forge software that powers e.g. Codeberg, has a feature for hosting wikis alongside code repositories. These wikis in turn are just their own Git repositories that collect a bunch of – you have guessed it – Markdown files. This means you can just check the wiki out locally, and set it up to be used as an extra wiki inside Vimwiki.
Such a joint Forgejo & Vimwiki setup allows you to pull/push changes from/to forgejo and locally interact with the wiki right in vim. You can see a toy example in my vim configuration repo. Forgejo wikis also have some special page names, including Home for the frontpage. If you setup your local vimwiki configuration to use Home as the name of the index page, your local wiki will also default to using the correct page when opening the wiki (see my example setup).
Lastly, Vimwiki can also do a full export of all of your wiki pages into HTML, structured as to allow you to still follow the internal links and ready to be put on some web server. By default, the exporter works for the internal Vimwiki format, but there’s a rich set of options to also export Markdown. As most of my tooling is based on Python, I went with that flavor of vimwiki_markdown, alongside the markdown-checklist to allow for correctly formatting to-do items. To make this work, the custom_wiki2html parameter needs to be set, and the checklist plugin needs to be loaded. When those are done, one can export all pages via :VimwikiAll2HTML.
So far, I’ve been enjoying the Vimwiki integration. It’s great to be able to quickly go back and forth between notes, and also to have them right at my fingertips when writing/editing other docs in vim. Plus, being able to more quickly interact with externally hosted & displayed wikis on Forgejo is great for editing those in a more comfortable place than the web interface.
References
- Greshake Tzovaras, B. (2025, February 18). Using vim templates for markdown writing. Bastian Greshake Tzovaras. https://doi.org/10.59350/qfa6t-c645
Footnotes
After many failed attempts, I’m convinced that there’s just large differences in how people’s brains work for note-taking. I know some people swear by tools like Roam, Obsidian et al. but I have tried many of them, but they just don’t work for me. ↩ 1.
I’m sure it would work for GitHub wikis too, but I haven’t tried and don’t plan on doing so. ↩
Bastian Greshake Tzovaras
Generally, things are better if you put open* in front of them.
Thanks to Rogue Scholar, you can cite this blog post using the DOI https://doi.org/10.59350/81yzn-1vv27.
This page was last built on 2025-12-10 @ 14:07:59 -0300, from git commit cd726fb.