Building a lightweight and portable knowledge base for fun and profit
So, you want to create your own, private knowledge base? Maybe you’ve already tried (and adapted) a proprietary solution such as Evernote, Google Docs, Google Keep or Confluence? Maybe you’ve simply decided storing plain/rich text files in your Dropbox, OwnCloud or Spideroak Cloud storage was enough? Or maybe you’ve tried instead to leverage a full-featured CMS such as Drupal or Wordpress?
In the past few years, I’ve tried all of the above solutions, and more. Yes, really. The takeaway with proprietary solutions is they’re subject to change (radical design decisions, pricing model…) and disappoint you along the way. Especially when you want to back up/export your data. Good luck with that.
Storing plain/rich text in the Cloud isn’t bad per se, but you need to build a system to index your files and/or have full-text search. If you go with OwnCloud or a CMS, you also have to maintain a database, a LAMP environment, etc. In a nutshell, run a website/server, while the only thing you want to do is to quickly store and get access to your knowledge base data.
Markdown all the things!
So I slowly drifted to using no-database, Markdown-first solutions like TiddlyWiki (uses WikiText by default but has a Markdown plugin), MkDocs, Renato and GitBook. If you run those locally, you’ll still need to ensure your data is going to be backed up in case something happens to your computer. Having your files under version control then seems like the obvious, safest option, and it’s a requirement for GitBook anyway.
Speaking about requirements, If we step back for a second and think about the requirements we want to have with our knowledge base, what are they, after all?
- Portable: Markdown is portable and compatible with a ton of systems out there
- Lightweight: you shouldn’t have to run a server or administer a database for storing this type of data
- Fast: parsing Markdown files is lightning fast
- Searchable: Markdown files are fully searchable
- Editable: while Markdown code is rather human friendly, we want to see a real preview at any point in time
- Secure: Markdown files should be under version control and the repository should be private
- Reversible: if you want to switch to full HTML from Markdown someday, we should be able to write or use an existing HTML-to-Markdown parser
With this in mind, let’s meet those requirements:
- Portable: find a solution able to parse Markdown code
- Lightweight: find a solution we don’t have to administer ourselves
- Fast: N/A
- Searchable: find a full-text search solution we don’t have to administer ourselves
- Editable: find a good markdown editor/viewer
- Secure: find a Git host able to provide us with private repositories
- Reversible: N/A
Find your Markdown editor/viewer
I’ve tried numerous solutions, but IMO none is as simple as Atom. It ships with Markdown support out-of-the-box, which is not surprising knowing it’s developed by the fine folks at Github.
Atom Markdown Preview package
Atom can both be your lightweight code editor and Markdown editor/viewer. How cool is that? Simply create a new file with a .md extension (not required but rather a convention), add some Markdown code, and then press ctrl+shift+m on Linux (command+shift+m on the Mac) to have real-time preview.
Atom Markdown Preview
There’s a contrib package you might want to install. Since your KB requirement is to be fully trackable under version control, better embrace Git completely and know what files have been changed and when, but also what branch is being checked out, all of this from the Atom UI. In other words, a quick glance through your Git repository can’t hurt and is even quite convenient, to know when it’s time to commit your code. Enter, Tree View Git Status.
Atom Tree View Git Status package
Find your Git host
While choosing a Markdown editor/viewer can really be up to you, finding a good Git host that will meet your requirements is way more restricted. You need to find a host you can trust (Is it popular? Is it here to stay? Are individual developers using it?), offering free private repos (we don’t really want to pay for our knowledge base, do we?), offering full-text search for source code files and Markdown preview/editing of files. Shortlist was quite easy to come up with:
- Github: probably the best Git hosting service out there, but do not offer free private repos
- Bitbucket: Github’s closest competitor, but still doesn’t offer searching in source code
- Google Cloud Source Repositories: probably offers everything but still in beta and I’m trying to avoid any Google product for so many reasons (privacy being one)
- GitLab: dutch company now operating in the US, but with a good reputation and all features I need
I decided to go with GitLab for now and I’m not disappointed. Git hosting is quite minimalistic but works just fine. You have convenient full-text search in your Markdown files, which is key for quickly finding what you need.
GitLab full-text search
Since this is a git tree, well, it means you can also fallback to discovery mode with navigating through your knowledge base directories and files at any point in time.
Viewing Markdown files is very convenient and the minimalistic rendering is just what we need. No custom theming, no complicated layout, no ads in the way.
GitLab Markdown viewer
Last but not least, editing Markdown can be needed for several reasons: you don’t have access to your Git repo and/or don’t have your laptop with you…or you’d simply like to simplify your Git workflow and edit and commit file changes through the GitLab interface instead.
GitLab Markdown editor
Now imagine having GitLab bookmarks to quickly access the root of your knowledge base and even one with a placeholder for instantly searching through your files (TextExpander / AutoHotkey / autokey / Krunner users, does that ring a bell?) Easy:
gitlab.com/{USERNAME}/{REPO}/tree/mastergitlab.com/search?search={QUERY}&project_id={PROJECT-ID}&search_code=true
There you have it. A lightweight, portable, secure, fast, searchable and editable Git and Markdown-powered knowledge base for fun and profit. I’d be glad to read what you think or what are your alternatives!