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.
- Create a new file in the yyyy/mm folder.
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.
A few independent tools make the whole thing work together:
- vim for editing markdown, Jupyter for more involved notebooks
mkdocsfor creating the static site
- AWS S3 for static site hosting
- Gitlab CI for pulling the whole thing together
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
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).