I’ve been going back and forth about how I want to approach a personal wiki (i.e. an information repository that I can stash and refer to my technical tribal knowledge for, often times, very specific “me-tech-things” that I don’t want to forget). What I used to do isn’t a very fluid process anymore, as things have changed in my workflow as well as the product itself.

Looking around, there is definitely no shortage of tools out there already developed to handle just this. For whatever reason, I didn’t fall in love with any of them. So as programmers we often do, I figured I might as well just create my own solution. I had a few requirements:

It had to be version-controllable I had to be able to create content in my favorite text editor The content had to be in markdown It had to be searchable and a pleasant viewing experience It had to be simple (to use, to maintain, and to reproduce)

Here’s what I ended up with…

Git repository

Done right, this pretty much knocks out the 80% solution for me right out of the gate. I went with a flat directory structure, in that the root of the repository has directories for each different technology (“section”) that I care about (obviously capable of endlessly expanding). Here’s what this structure looks like…

.

├── ansible

│ └── readme.md

├── docker

│ └── readme.md

├── git

│ └── readme.md

├── jenkins

│ └── readme.md

├── linux

│ └── readme.md

├── python

│ └── readme.md

├── vim

│ └── readme.md

├── auto_index.py

└── readme.md 7 directories, 9 files

Note: I’ll get to auto_index.py and the resulting root readme.md shortly.

The format of the per-tech-readme file is this (and very important)…

# Index - [First item](#first-item)

- [Second item](#second-item) ### First item ...content... ### Second item ...content...

Hosting the git repository

This was one of the only items I was really torn on. I’m all about all things open source, but in this case for now I think I’ll be keeping my wiki behind a private repository until I see how it shapes up. The primary use for this is personal technical use. I don’t think I want to always be thinking that what I’m writing will be publicly viewable. But the minute I do, I’ll move it from a private GitLab repo into a public GitHub repo.

Much like GitHub, GitLab does a pretty good job of taking your markdown and displaying it nicely, which checks off an import item for me…

But I didn’t want to have to create this index myself…

This is where a little Python scripting came in handy. Point is, when I’m adding an “excerpt” of knowledge to this thing, I didn’t want to have to do too much work. This should be a painless and easy process.

This is where auto_index.py comes into play here. This Python script simply combs through each of the sub dirs’ readme files and generates the super index for the readme in the root of the repo. About 50 lines of Python, and done…

As you can probably see here, this is why convention for the readme files is really important, as I’m regex’ing through them to determine what should be part of the super index in the repo root.

But I don’t want to have to manually kick off this script

At first I thought I was probably done (which is a relative word with all things computer). But then I wasn’t loving the fact that after I added a knowledge snippet I had to kick off this script manually.

I created a pre-commit git hook (located in .git/hooks/pre-commit ) to do this automatically. The git hook itself is only two lines…

./auto-index.py

git add .

Now when I do a git commit git will automatically run the Python script, generating the super index, and then adding these changes to the staging area and of course being lumped into the commit that kicked off the hook in the first place.

Summary

There it is. A homegrown solution, but extremely simple. Version controlled, enjoyable and easy to work with, and no extra steps. I’ll definitely be using this workflow for my personal wiki, perhaps others would want to as well! Enjoy!