vw
February 5, 2023
git clone https://github.com/friedev/vw.git
vw (vim wiki) is yet another system for maintaining a simple personal wiki using vim and markdown.
vw (vim wiki) is yet another system for maintaining a simple personal wiki using vim and markdown.
vw was made by Aaron Friesen for CornHacks 2023, where it won 3rd place.
Dependencies
- To compile to HTML:
- make
- lowdown
- To import from TiddlyWiki:
- Python 3
Quick Start
Clone vw:
git clone https://frie.dev/vw.git
Create a new wiki by copying the example:
cp -r vw/example my_wiki
Now you can create and edit articles in my_wiki/md/
as you see fit.
Extras
Install the vw
helper script:
cp vw/vw ~/.local/bin
Add the "insert link" macro to your vimrc:
cat vw/insert_link.vim >> ~/.vimrc
Start tracking the history of your wiki's articles:
git init my_wiki
Compile your wiki to HTML:
make -C my_wiki
Architecture
vw is not a single piece of software, but rather a process and a small collection of tools. A vw wiki is a collection of markdown files in a directory that can link to one another. Each file represents an article in the wiki.
File Naming
The recommended naming convention for vw wikis, and the one used by the included tools, is as follows.
The name of each file should be the article title converted to lowercase, with spaces converted to underscores, and with the .md
file extension.
Navigation
To create links between pages, use the normal markdown syntax:
[vw](vw.md) is a tool for creating wikis.
vw will translate each link to point to its corresponding HTML page when you run make
.
Vim provides some useful built-in keybinds that you can use to navigate the wiki.
To open a link in a new buffer, move the cursor over it and type gf
.
To open an external link in the proper program (like your browser), type gx
instead.
Version Control
To edit collaboratively and track the history of your articles, you can simply create a git repo at the root level of your wiki. For the most granular control, like you would get in a traditional wiki, make a commit after each edit you make to a page. However, unlike a traditional wiki, you can also choose to group related changes to multiple pages together into a single commit, like you might do in a software project.
Tools
HTML Export
vw includes a makefile which you can use to compile your wiki to HTML. This lets you browse your wiki locally with a web browser, or publish it to a website. You can customize this build process to your liking simply by editing the makefile.
The makefile includes options for common use cases, such as adding a CSS stylesheet or a common header and footer. More details about setting these options can be found in comments in the makefile.
Helper Script
vw includes a shell script (also named vw
) which you can use to refactor your wiki and generate various insights.
For more detailed help information, run vw
with no arguments.
For maximum usability, add vw
to your path; for instance, you could copy it to ~/.local/bin
or /usr/local/bin
.
NOTE: vw
must be run from the same directory as your wiki's markdown files.
Link Generation
To speed up editing, vw includes a vim macro that inserts the link corresponding to the article title under the cursor.
For example, if you typed [My Article]
, running the macro would yield [My Article](my_article.md)
.
To install it, append it to your vimrc.
cat vw/insert_link.vim >> ~/.vimrc
Alternatively, check out vim-markdown-wiki, which provides similar functionality in the form of a Vim script plugin. Note that, by default, vim-markdown-wiki replaces spaces with hyphens rather than underscores.
Import from TiddlyWiki
To convert a TiddlyWiki to a vw wiki, you can use the included Python script: tiddlers_to_vw.py
.
The converter doesn't handle all of TiddlyWiki's features, but it should still save you time compared to manual conversion.
Alternatives
Many similar projects of varying complexity attempt to solve the same problem as vw. Some are listed below, roughly in order of similarity to vw. I recommend trying them out and deciding which you prefer.
- vim-markdown-wiki
- wiki.vim
- Vim-Waikiki
- SoyWiki (unmaintained)
- vimwiki