Generate documentation site from Markdown

Posted by Andy Huggins on January 08, 2016

For a project I was working on, the client requested user documentation for their employees so that they would have some things as a reference. 

Reasonable request, but how am I going to maintain yet another part of their site?

Well, I did some Googling and found this: http://www.mkdocs.org/


It's a pretty simple site generator that is written in Python. Crap. I don't have much experience with Python, but I gave it a try anyway and it all worked pretty easily.

Basically, as I recommended in my last post, I really like making a docs folder and creating a Markdown file for any notes about an application I am working on. It's quick, it's easy, and goes in Git so that the docs are always with the code. (Seriously, do yourself a favor and start doing this!)

Any domain concept that I think needs explanation gets a little markdown file explaining the thinking or maybe some quick and dirty api definition. Anything that I think may take longer than a minute to figure out, I spend 10 minutes writing something about it.

So assuming you also have a docs folder with MD files, what if someone not on your dev team wanted to review them? MkDocs to the rescue. This means that some of the more technical stuff may not be so helpful, or maybe you create a couple folders in the docs folder "dev-notes" and "user-notes" or something along those lines. Regardless, MkDocs allows you to generate static html files from these Markdown files.

More importantly, it takes very little time and is pretty painless, which makes me think that people will actually do this. The ease of this package means you can have a good looking site with very little work. You look like a champion and can still focus on the work you want to do instead of worrying about a docs site.

Did I mention the Search feature?

Oh I forgot to mention the Search feature. It's not a robust search feature, in fact it's pretty bare bones. But again, if it takes you more than a few minutes are you going to bother with setting up the docs site? Be honest.

So for very little effort and no money, you get a barebones site, that's easy to edit, easy on the eyes, with a bare bones search function. Tell me your boss wouldn't be happy with that?