239

A simple personal wiki using a little Python and a small Git hook

 6 years ago
source link: https://medium.com/@trstringer/a-simple-personal-wiki-using-a-little-python-and-a-small-git-hook-c352fc5cca8b
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.

A simple personal wiki using a little Python and a small Git hook

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:

  1. It had to be version-controllable
  2. I had to be able to create content in my favorite text editor
  3. The content had to be in markdown
  4. It had to be searchable and a pleasant viewing experience
  5. 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.md7 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…

1*fpFpY_eaGjTY_JlXtzNRiA.png?q=20
a-simple-personal-wiki-using-a-little-python-and-a-small-git-hook-c352fc5cca8b

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!


report

Recommend

About Joyk


Aggregate valuable and interesting links.
Joyk means Joy of geeK