Write the Docs: Tom Christie – Designing MkDocs

I’m at Write the Docs today in Budapest and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Tom started day 2 of talks at Write the Docs. He works as a software engineer at a web development startup in Brighton, UK.

MkDocs is a software project for producing nice-looking documentation from markdown files. Tom uses it with a lot of his own open source projects. Previously he handled documentation through Sphinx, which Markus talked about yesterday. This uses restructured text for documentation. Writing the actual docs, though, was not the most attractive process.

To help create more attractive docs with a clearer design Tom started drafting docs in Markdown. As he said, “The documentation is really the design of the product.” Using editors like Mou he was able to cleanly assemble and visualize his documentation. It helps to see what your readers will see.

From that experience he decided to tear up the existing tools and start again. Writing a custom little script he built the documentation for the django REST framework. The downside was that everything was hard-wired to this one project; it wasn’t the most reusable piece of code. Tom sought a more reusable solution; thus, MkDocs.

MkDocs is written in Python so you’ll need to install that as well as pip. Once installed you can create and start running a new document project. New projects start with a single configuration file, where all settings are optional, and a /docs directory which contains the Markdown source files. From a clean demo MkDocs handles presenting the docs in a nice, clean-looking design. Built-in is live reloading; so anytime you edit an underlying document the site will reload upon saving. There’s no build process or deployment that needs to happen.

The docs directory handles all your documentation source. While it requires an index.md file you can include images, other media, and any CSS or JavaScript to tweak the basic theme. Theme’s all change on the fly and don’t impact the documentation content. It takes just one line in the configuration file to change the design.

You can also interlink all the docs with regular hyperlinks within Markdown. You can also use relative links, though, if you’re working within your documentation folder. You can also use references to target a page or title anywhere in the documentation.

To push your documentation site live to a server you can run mkdocs build and MkDocs will create a static HTML site with your content, theme, and all necessary resources. Since it’s static HTML you can deploy it on any server or even GitHub Pages. There’s some GitHub Pages integration baked in to MkDocs that lets you run one command, gh-deploy, and let the software build a full GitHub Pages site for your project.

The 1.0 release for MkDocs is in-progress. You can help Tom make it happen by contributing on GitHub.