DEV Community

loading...
Cover image for A Personal Git Repo as a Knowledge Base Wiki

A Personal Git Repo as a Knowledge Base Wiki

adam_b profile image Adam B Updated on ・4 min read

While it's not something that everyone likes to do, I've always found it essential to write notes. There are the project-specific notes that only have relevance within a particular workplace and are of course confidential, but then the stacks of notes that cover everything from the content of the training course you last went on to "what's the command-line way to add a new project again?" - and that second category is the one we're going to discuss here.

Besides good old pen and paper I've tried all sorts, with tools like Evernote, Keep, the original Catch Notes (RIP), and Apple Notes each having very different levels of support for formatting, embedding, and crucially, portability of stored data. The latter becomes especially significant if the service closes down, or if (in the case of Apple Notes) you hand back the computer at the end of a job. As I looked at the pages of pencilled notes I'd written while following an online tutorial recently, I realised that a more unified and durable approach would be extremely useful. A solution flashed into my head while updating the wiki for a personal project on Bitbucket - why not have a private repo consisting entirely of Markdown notes, rather than code?

Benefits

  • Markdown is familiar to a large proportion of developers, is easy to write, and widely-supported - but also fairly readable even as plain text without a parser.
  • Markdown has great support for inserting the kinds of things we so often need - code snippets, links, tables, and multi-level bullet lists - with minimal effort, allowing you to concentrate on the content.
  • Using a Git repo makes it easy to quickly sync the notes across machines.
  • This approach removes the reliance on proprietary sites. As each copy of the repo is just the same as any other, even the loss of your online Git account is not catastrophic.

Basic Structure

The root of the repo has an index.md file, with each overall topic being contained in a folder - and each of these also contains an index.md. If it's a big enough topic, there might be an extra level, but the aim is just organised enough without having a crazy directory tree structure.
Directory structure of repo shown in VS Code

The root index.md contains links to the index files in each folder.
Main index file of repo shown with preview in VS Code
Those index files, in turn, link to other .md files within their own directories for each article.

Article Content

The beauty of this being your private repo is that you're not beholden to any particular standard - you can be free to write in as formal or as loose a way as you'd like. At some times you might have nothing but a raw text braindump, at others you may have topics that you can write on in a more structured way. The point that is central is that you write in the way that works for you, in the terms that make it the most useful for the way you read, think, and recall.

Code snippets (with the original spacing preserved) and shell commands can be inserted easily, as can links to external resources that might be useful for each topic.
Code snippet shown as part of a Markdown document
Link block shown as part of a Markdown document

In addition, now that everyone has a camera in their pocket, diagrams can be sketched, photographed, and included as inline images, rather than being laboriously reproduced with a computerised drawing tool.
Sketched diagram shown as part of a Markdown document

As an aside, if you need to copy/paste formatted text from other document formats, PuppyPaste is a very handy tool which will convert the formatting to the Markdown equivalent, which you can then copy/paste/edit as necessary.

Reading

The main online Git sites will support the viewing of Markdown files, but if you want to view them outside of this framework then a small amount of extra work is needed. As web browsers don't generally have native support for Markdown files, you can't get the benefit of using one as a viewer directly, but some very kind people have provided solutions to this. Someone recommended MDwiki and having used it, I will too.

Simply download the HTML file into the root of your repo, and rename it to index.html. Pointing a web server at this folder (I wrote an absolutely minimal one with Node.js and Express) makes it an HTML web-browsable wiki.
HTML-translated version of MD wiki, shown in browser

Uses and Conclusion

I now have copies of my own repo on a Windows desktop, Mac laptop, and a USB flash drive, as well as on Bitbucket. A quick git pull on each grabs the latest changes as needed, and after that the notes are available even if there is no network available. I'll be continually adding to it and think that this is a solid way of preserving the jewels picked up along my development journey. I hope some of you find this approach useful too!

Discussion (18)

pic
Editor guide
Collapse
chadalen profile image
Chad Alen • Edited

I did this too but thought instead of making it private why not make it public. Seems like every developer I know does this in some way.

I started a project a couple weeks ago to fix this problem. It’s in the concept phase so a lot of design can change. I’m looking for some feedback so if you want to check it out that would be great. :)

syntaxrecall.dev
github.com/syntaxrecall/syntaxrecall

Collapse
adam_b profile image
Adam B Author • Edited

I've actually never known another developer do this (or if they have, they've been quiet about it), but I guess writing about it attracts other people who think the same way!

Making content public or private is down to personal choice of course, but I think there's something to be said about removing the pressure of the public gaze and tailoring the content to exactly what you need. There's also a benefit if you want to use code snippets/examples/diagrams (or entire topics) that you explicitly don't want to share for whatever reason. However, using an open source format like MD means that it's very easy to port content out from one repo to another if there's something to share more widely.

Thanks for the link! I tried to launch the site itself but couldn't get it to respond to any searches - are there any pre-requisites for the browser running it?

Collapse
chadalen profile image
Chad Alen • Edited

Some of the devs I've worked with use cacher.io/. I tried it, but I didn't want to pay for it. I like the personal wiki approach but I prefer the devhints.io approach more. Everyone can contribute and knowledge share. Saves everyone time, making everyone more productive.

For my site yeah there's not much content currently cause I just started it. Try searching for one of these though.

Cheatsheets

  • Git
  • VSCode
  • Lua
  • Markdown
  • Sass
  • Screen
  • Vim
  • Yarn

Tools

  • JSON Editor
  • Phobia
  • Tailwind playground
Collapse
timothydjones profile image
Tim Jones

Hi, Adam. Thanks for the tip about MDwiki. I'm going to look into that.

I have recently started my own TIL repository on GitHub following several of the concepts that you described. I don't have much there yet, but it seems to be a good fit for me so far. Check it out and let me know what you think.

Collapse
adam_b profile image
Adam B Author

I like where you're going with that! I might borrow the idea of having a section specifically for tools - little cheat sheet pages that would be really useful on a second monitor 👍🏿

Collapse
chadalen profile image
Chad Alen • Edited

If you don't mind check these out and give me some feedback. :)
syntaxrecall.dev/vscode-keyboard-s...
syntaxrecall.dev/vim

Collapse
adam_b profile image
Adam B Author

Looking good! I'll definitely be making use of some of those VS code shortcuts.
(as an aside, it is a classic of dev life that you need a cheat sheet to exit vi 🙂)

Collapse
mrrcollins profile image
Ryan Collins

I learned of Obsidian last week from harshibar. It looks promising, unfortunately, it doesn't recognize .markdown as a Markdown file. :-(

From my limited testing, it looks like it could be useful, especially being able to create links.

Collapse
adam_b profile image
Adam B Author

Thanks for the tip!

Collapse
subbramanil profile image
Subbu Lakshmanan

Love the idea of browsing & viewing the notes on a browser!! I have been using markdown + VSCode + git for my notes for over 4 years now. Absolutely love it!!

Notes

I will give it a try on MDWiki!! Thanks for the great post!!

Collapse
adam_b profile image
Adam B Author

Thank you! I love that you've got your actual daily project notes there too - great for recalling design decisions from the distant past :)

Collapse
kevlatus profile image
Kevin Latusinski • Edited

it sounds like foam might be for you: it uses exactly your type of markdown and file based layout, while simplifying the process of linking content. All while being a VSCode plugin.
I recently started using it and must admit that I'm hooked 🤷‍♂️

Collapse
maxivanov profile image
Max Ivanov

Like it. What's your process of adding images to the pages? Is it: take a picture with a smartphone → icloud/dropbox sync to computer → move the file to the repo → add an image in markdown?
I'm yet to find a perfect solution for a personal knowledge base. I like to add diagrams next to the text (often a doodle is worth a hundred words) and I want the process to be as easy as possible. I found Notability app to serve best my needs. Using it on my iPad and computer. Also tried OneNote, GoodNotes and (Apple) Notes but they didn't click with me.

Collapse
adam_b profile image
Adam B Author

Thank you! Yes, that's basically the process for adding images - I've only had to do that with one or two hand-drawn ones so far, for screenshots it's of course even simpler than that.
When I was first introduced to Apple Notes, I got into using it but getting the information out was ridiculous - I ended up connecting it to my Google account and so the notes now live in a Gmail folder as though they're emails. I've started the process of copying/reformatting the info to live in this repo, where it'll be a bit more useful!

Collapse
timster profile image
Tim Shaffer

If you want a super easy http server, python has one built in. Just go to the directory and run this:

python3 -m http.server

Collapse
adam_b profile image
Adam B Author

That's a great tip! 👍🏿

Collapse
lamartire profile image
Konstantin Epishev

Like your idea. Honestly, there is really no need to do website to collect something. Never thought about "just repository" as about a knowledge base!

Collapse
eelstork profile image
Tea

Also - try Notational Velocity if you're on macOS