I have notes on lots of things. When you write notes in markdown it’s called ‘a knowledge base’, which sounds classy. So now I have lots of knowledge bases, and I strive to keep them bland and featureless.

A good knowledge base has no fancy features. Features are bad[i]. They tie you down to particular software, or one workflow. Everything ‘integrated’ with the notes also holds onto your notes, jealously.

Proprietary solutions are prone to the usual abuse[ii], but many open source note apps[iii] aren’t much better - they have their own oddities, and special markdown abilities, which won’t work in other contexts. This leaves you unable to publish notes, as that special in-line image format from a fancy app won’t work on a website.

The websites are no better. I publish with Hugo, and it’s great, but every theme also invites you to place special snippets for graphs or video

It looks harmless, but it’s a trap. The video link won’t work on other web compilers, or gemini, so the knowledge base will be tied to that particular software.

Hence Vim. Vim is harmless. It won’t tell you how to write or organize your notes. It just makes editing easy. Because vim is easy[iv].

The Linux Knowledge Base

The collection of text notes on how to do stuff in Linux has grown and become opinionated. I’m slowly going over the pages to try and tag every single page with knowledge dependencies, i.e. what you need to know before reading the page.

Here’s the head of one page on editing files encrypted with GPG:

That ‘requires’ tag means I can generate a note at the top of the pages saying what you need to know before reading the page.

I have not tagged all pages yet, but once I do, the website[v] will state what’s required to read an article at the front. This will make me happy, because documentation should not have links in the body[vi].

Vim with a Knowledge Base

File Navigation

Open a file at line 20:

Open the file while searching for the word ‘Delete`:

Buffers & Tabs

You can open multiple files with Vim and navigate with ‘buffers’ (the word still feels strange).

The command :ls shows the buffer, and b2 takes you to buffer 2 (writing/vim.md) in this case.

You can also cycle through them.

Tabs are similar, but you can see the tabs at the top.

Open files in tabs with -p.

Then use :tabedit % to open a new tab.

Go-to-File

If you put the cursor on a file’s name, you can go to the file immediately with gf. This is excellent, as it lets you wander your own knowledge base as if a palace.

Weird markdown formats, like Gollum sometimes demand that you leave out the .md suffix in links, so your link to [GPG](gpg.md) won’t work. You have to write [GPG](gpg). Vim lets you navigate to gpg.md anyway by adding a standard suffix:

Now you can go to the word gpg and press gf, and instantly enter that file.

If the file is in another directory, you can link to it like this:

But you might want to link to it like this:

In this case, you can still navigate to it by adding all the other directories to the path where Vim checks. Just add this to your vimrc file:

Edit Jumps

Netwr Navigator

On rare occasions, I’ll use the in-built navigator: Netwr. There’s an excellent setup guide here[vii] as it’s not very good ‘out-of-the-box’.

Editing

Mapping Keys to Output

Notes on Linux means lots of code-blocks, which look like this:

This is boring to type, so now I just type ‘comma’ then ‘grave’, and vim produces the code block. You can map the keypress by sticking this in ~/.vim/vimrc:

Interactive Find and Replace

Sometimes you want to find and replace a word in a lot of files, but also confirm each change. Vim lets you do this by starting up with a ‘find and replace’ command:

Input Command Outputs

Vim can run a command and type out the results for you:

Writing with Markdown

Set up a Spell Checker

I have the standard spell-checking commands in my vimrc, but the command to actually use the spell-checker hides in the markdown-only file, because you don’t always want a spell-checker on.

All those hi-light commands make Vim’s spell-highlights less nauseating.

In the markdown-only setting, add this to actually use those spell-checking commands:

Once you have the spell-checker working, it just has a few commands:

If, like me, you speak a kind of English which people describe as ‘not default’, you should share this spelling file with all your computers, so you don’t have to rebuilt it every time.

This next command is amazing. Once you start using it, you won’t stop, and may look back on all the years you never had it and weep.

If you type a typo, you can press Control + L to jump back, fix the typo (with Vim’s first guess at the correct spelling) and then jump back, all during insert mode.

Formatting Text Lines

I still don’t know how to do this. On the one hand, writing one sentence per line helps when using git, and feels natural. But it feels less natural to read.

As an example, that last paragraph has a new line on each sentence:

Option 1: have a separate markdown reader.[1] Markdown is supposed to wrap lines for you, so you can break anywhere.

Option 2: wrap the lines with vim.

I can press gq2j to reformat two lines down, and it looks better.

However, every time you edit, you need to wrap the lines again.

Not Vim with a Knowledge Base

The best thing about using Vim is not using Vim. After all, it’s just a text editor. As mentioned above, features are bad[viii]. Vim happily works with other tools by integrating those command. Like the Tao, it does nothing, and accomplishes everything.

Having plain text means easy parsing. I have a little bash script which searches markdown files for links, and checks to see if they work, then spits out a list of dead links. I’ll stick the script at the end in case anyone wants to use it for their weighty collection of markdown files.

Make Stuff

The Makefile at the root of knowledge base automates the standard commands. The first command is a help menu. I want the project to be friendly in case anyone else wants to join me in my quest[ix] to rid documentation of links inside the body.

make article will create a standard article template then commit it to the git repository.

The Dependencies Map

Each setup guide and note lists what you need to understand before starting. If you have graph-easy installed, you can run make map and see a full graph of dependencies (example at the end).

Recfiles

Recfiles[x] are plain-text files which are also a relational database. They look like this:

This file is a record of every file in the knowledge base, along with the word-count.

The Commands List

Recently, I’ve begun another recfile database for commands. I have a boat-load of little commands that don’t merit their own page/post/article, and really just exist so I can search for them quickly.

Links

If you want to check the project, it’s available over ssh:

…or at Gitlab[xi].

Thanks to the lazy bear[xii] for hosting a Vim carnival on knowledge bases. I can’t wait to see what the other posts look like.

Appendix A

The Dependencies Map

A lot of work remains, but right now the dependencies map looks like this:

[i]

[ii]

[iii]

[iv]

[v]

[vi]

[vii]

[viii]

[ix]

[x]

[xi]

[xii]

~~~~~~~~

[1] My favourite reader is mdless (which is just a link to mdcat -p).