There are a lot of existing tools to consider when starting a personal wiki or knowledge base (KB). It's important that the tools you pick don't create friction. Instead, they should encourage regular contribution and usage of the wiki. It follows that regular usage and reference should enrich the content.
Search, tagging, and citation are other important features to consider. Alongside these features, a solution that gives you precise control over the data may lend itself to experimentation over time. I also appreciate an editing interface that gives reasonable freedom to design while still maintaining consistency and quality across devices.
One last suggestion is to understand your requirements. Pick a platform that supports the knowledge you intend to document. For example, this knowledge base was designed to support diverse, quality content— with a special focus on programming. I made sure I could provide code highlighting and side notes to make this content easy to record and understand.
Tools
When I "officially" started to collect and document personally important knowledge, I did so using VimWiki
. From there, I generated .html
output and hosted it alongside my blog.
Now with more experience using markdown (and MDX— a mix of markdown and React), I've decided to use the same code to generate blog pages and knowledge base pages. MDX allows the easy addition of code blocks with interactivity (copy button!), styled image blocks (with captions!), auto-anchored headers for more direct linking to content, and a realtime comment system.
I've been developing all these goodies for blog posts— but why not use them for the knowledge base as well?
In this page, I'll go over some of the tools I've researched and discuss more about the current setup.
VimWiki
VimWiki, "a personal wiki for Vim", provides a set of hotkeys in the Vim command-line text editor which allow you to instantly access your KB from anywhere in the terminal. Your notes are saved either in a .wiki
file— or as common markdown with the following settings in your ~/.vimrc
file:
let g:vimwiki_list = [
{
'path': '~/vimwiki/',
'syntax': 'markdown',
'ext': '.md'
}
]
To search across the KB, you could then simply use:
:VWS <search_pattern>
Telekasten
Markdown Static-Site Generation (SSG)
For moving the .md
KB to the Web, I had been using generate-md
— a function that's included with the Node package, markdown-styles
:
npm install -g markdown-styles
To quickly convert all .md
files to .html
you could set a longer, more complex command to a shorter, memorable alias. I used a "loosed-template" theme variation on the markdown-styles-included jasonm23-dark
theme:
# Add a similar alias (i.e., to your ~/.bashrc) to convert your markdown wiki to html
alias markdown-html='generate-md --input ./ --output ./converted/ --layout loosed-template'
Here's a wonderful markdown cheatsheet if you forget any syntax.
Editors
An accessible editing environment reduces friction. More regular usage helps your KB accumulate information more readily and allows you to provide more incremental improvement without added effort.
Part of my definition of "accessibility" is the ability to edit on different devices and from different locations. Sometimes I would like to update a KB page from my phone, or from a computer that doesn't have all my applications.
The final criteria for me— though, not necessarily a requirement— is having something keyboard- and text-centric. I would prefer using raw .html
over a WYSIWYG
editor or GUI (graphic user interface) for building content.
Another option might be to configure on of several incredible (and opensource) content management systems (CMS)— MediaWiki, WordPress, Payload, Wagtail, to name a few. However, text-based (.html
, .md
, .mdx
) often makes simplifies editing and automation.
Mobile Editing
If you want to edit your KB remotely, you can use the Spck Editor. It's a nice mobile code editor with built-in GitHub functionality for pulling from or pushing to a remote repo.