Taking linked notes with Vimwiki and integrating it with Forgejo wikis
a boy on the beach, framed by a fishing pole, runs towards the water with a bucket[1]
A couple of days ago, I stumbled over a Mastodon post by @johl[1], in which he shared `vimwiki`[2] 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-taking[^1], 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[1].[^2]
[^1]: 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.
[^2]: I'm sure it would work for _GitHub_ wikis too, but I haven't tried and don't plan on doing so.
_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 `` in normal `vim` mode.
Pressing `` when the cursor is over an existing link opens that file, `` 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[1] 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[1], 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[1].
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[1].
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[1].
_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[1].
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_[1].
As most of my tooling is based on _Python_, I went with that flavor of _vimwiki_markdown_[1], alongside the `markdown-checklist`[2] to allow for correctly formatting to-do items.
To make this work, the `custom_wiki2html` parameter needs to be set[1], and the checklist plugin needs to be loaded[2].
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