I set out a few days ago to put together a documentation site. I had a few criteria for this site: A static site that I could push to Github to use with their github pages feature. The static site is generated from markdown. It just works. It’s easy to get it into a workflow without breaking the tool or breaking a solid workflow. That was it, what I’d consider some pretty straight forward criteria. However it wasn’t that easy, until it was. Here’s a few of the issues I ran through on the way to getting a solid tool with a solid workflow working together. Beware however if you have fickle reading eyes, the following is a rant about what does and does not work.