As part of my never-ending search for the ultimate blog theme, I stumbled across other static site generators similar to Jekyll (which this blog uses). This new site generator is called MkDocs and it generates absolutely stunning project documentation.
I first came across the Material theme (Github) when I created the reverse proxy some time ago. Check out Traefik's documentation page, it is beaufiful.
So why is there a whole post on this blog about a documentation tool. I think it's important to make people aware of how easy it is to create good project documentation (from a navigation and readability point of view, leave actual content aside for the moment).
Here's why im endorsing endorsing MkDocs:
- makes writing documentation efficient – uses Markdown
- makes writing documentation fast
- installation was incredibly easy, get a fully generated documentation site hosted on Github Pages in 15 minutes!
- generates beaufiful, very easy to navigate, responsive HTML with built in JavaScript. Completely responsive, mobile friendly searchable.
- contains additional styling for documentation specific elements such as Bug warnings, Example boxes etc. (Just have a look here at all the goodies they supply.)
- contains support for cross-referencing other doc pages, footnotes, bookmarkable headings, JavaScript full text live-search (every programmers dream) It's basically project documentation writing heaven!
In other words, in the same sense that Jekyll is a blog-aware site generation engine, MkDocs is a site generator specifically for project documentation.
Maybe it's just me but being able to easily create and deploy documentation that is easy on the eyes and incredibly intuitive to navigate is very cool!
Do what you want with this knowledge 😉
