In­tro­duc­tion

There are a lot of ex­isting tools to con­sider when starting a per­sonal wiki or knowl­edge base (KB). It's im­por­tant that the tools you pick don't create fric­tion. In­stead, they should en­courage reg­ular con­tri­bu­tion and usage of the wiki. It fol­lows that reg­ular usage and ref­er­ence should en­rich the con­tent.

Search, tag­ging, and ci­ta­tion are other im­por­tant fea­tures to con­sider. Along­side these fea­tures, a so­lu­tion that gives you pre­cise con­trol over the data may lend it­self to ex­per­i­men­ta­tion over time. I also ap­pre­ciate an editing in­ter­face that gives rea­son­able freedom to de­sign while still main­taining con­sis­tency and quality across de­vices.

One last sug­ges­tion is to un­der­stand your re­quire­ments. Pick a plat­form that sup­ports the knowl­edge you in­tend to doc­u­ment. For ex­ample, this knowl­edge base was de­signed to sup­port di­verse, quality con­tent— with a spe­cial focus on pro­gram­ming. I made sure I could pro­vide code high­lighting and side notes to make this con­tent easy to record and un­der­stand.

Tools

When I "of­fi­cially" started to col­lect and doc­u­ment per­son­ally im­por­tant knowl­edge, I did so using VimWiki . From there, I gen­er­ated .html output and hosted it along­side my blog.

Now with more ex­pe­ri­ence using mark­down (and MDX— a mix of mark­down and React), I've de­cided to use the same code to gen­erate blog pages and knowl­edge base pages. MDX al­lows the easy ad­di­tion of code blocks with in­ter­ac­tivity (copy button!), styled image blocks (with cap­tions!), auto-an­chored headers for more di­rect linking to con­tent, and a re­al­time com­ment system.

I've been de­vel­oping all these goodies for blog posts— but why not use them for the knowl­edge base as well?

In this page, I'll go over some of the tools I've re­searched and dis­cuss more about the cur­rent setup.

VimWiki

VimWiki, "a per­sonal wiki for Vim", pro­vides a set of hotkeys in the Vim com­mand-line text ed­itor which allow you to in­stantly ac­cess your KB from any­where in the ter­minal. Your notes are saved ei­ther in a .wiki file— or as common mark­down with the fol­lowing set­tings in your ~/.vimrc file:

To search across the KB, you could then simply use:

Telekasten

Mark­down Static-Site Gen­er­a­tion (SSG)

For moving the .md KB to the Web, I had been using generate-md— a func­tion that's in­cluded with the Node package, mark­down-styles :

To quickly con­vert all .md files to .html you could set a longer, more com­plex com­mand to a shorter, mem­o­rable alias. I used a "loosed-tem­plate" theme vari­a­tion on the mark­down-styles-in­cluded jasonm23-dark theme:

Here's a won­derful mark­down cheat­sheet if you forget any syntax.

Ed­i­tors

An ac­ces­sible editing en­vi­ron­ment re­duces fric­tion. More reg­ular usage helps your KB ac­cu­mu­late in­for­ma­tion more readily and al­lows you to pro­vide more in­cre­mental im­prove­ment without added ef­fort.

Part of my de­f­i­n­i­tion of "ac­ces­si­bility" is the ability to edit on dif­ferent de­vices and from dif­ferent lo­ca­tions. Some­times I would like to up­date a KB page from my phone, or from a com­puter that doesn't have all my ap­pli­ca­tions.

The final cri­teria for me— though, not nec­es­sarily a re­quire­ment— is having some­thing key­board- and text-cen­tric. I would prefer using raw .html over a WYSIWYG ed­itor or GUI (graphic user in­ter­face) for building con­tent.

An­other op­tion might be to con­figure on of sev­eral in­cred­ible (and open­source) con­tent man­age­ment sys­tems (CMS)— Me­di­aWiki, Word­Press, Pay­load, Wag­tail, to name a few. How­ever, text-based (.html, .md, .mdx) often makes sim­pli­fies editing and au­toma­tion.

Mo­bile Editing

If you want to edit your KB re­motely, you can use the Spck Ed­itor. It's a nice mo­bile code ed­itor with built-in GitHub func­tion­ality for pulling from or pushing to a re­mote repo.