Skip to content

Using mkdocs to host a static site

This site has been neglected for a while. Even slight obstacles to writing can turn out to be sufficient obstacles to getting words out and published. Ideally a publishing system has zero friction to writing and needs to maintenance to keep running.

Desired workflow

  1. Create a new file in the yyyy/mm folder.
  2. Write
  3. git commit && git push

Ideally there is no messing around with metadata or databases. My existing primary toolchain for writing -- vim and/or Jupyter, depending on task -- work without modification.

Tooling

A few independent tools make the whole thing work together:

  • vim for editing markdown, Jupyter for more involved notebooks
  • mkdocs for creating the static site
  • AWS S3 for static site hosting
  • Gitlab CI for pulling the whole thing together

Custom tools

Things didn't quite work "out of the box" for my needs so I made a few small adjustments.

A slight patch to mkdocs adds a plugin extensibility point to allow plugins to say whether they can support other types of files. This opens the door to the mkdocs-nbconvert plugin which lets mkdocs publish ipynb files just as easily as markdown. A slightly patched nbconvert puts image attachments into the converted output which seems to be an omission.

A few other mkdocs plugins, one called mkdocs-jinaj2 adds simple templating support. Another called mkdocs-blog creates some data structures that make it easier to work with time-based posts. And finally, mkdocs-navtitles parses every page in the site navigation to get its friendly title (otherwise just filename is used).