Publishing

The future of MkDocs: ProperDocs and Zensical

---

Photo source: Roman Synkevych (@synkevych) | Unsplash

---

We have relied on MkDocs for our teaching materials and this website for several years, so its future is more than a passing interest for us.

The slow collapse of MkDocs is, by now, well documented and worth reading if you are interested in the details of it.

In summary, MkDocs is unlikely to get future releases compatible with its current version, which makes the instructions for setting up a GitHub Action for MkDocs deployment in need of an update. Without further ado, here are two good options to move forward.

Serverless URL redirects using JavaScript on GitHub Pages

---

Photo source: Lautaro Andreani (@lautaroandreani) | Unsplash

---

As many readers of this blog are already aware, we make great use of GitHub Pages for hosting this website and several others. In particular, after FIDIT's inf2 server was finally decomissioned, Pages was the obvious choice for replacing the remaining services it offered.

Since the number and variety of applications and services hosted on inf2 server grew and diminished organically over time, what remained afterward was a collection of complex, but unrelated link hierarchies that had to be redirected to new locations (remember that Cool URIs don't change).

Publishing (Material for) MkDocs website to GitHub Pages using custom Actions workflow

---

Photo source: Roman Synkevych (@synkevych) | Unsplash

---

As you can probably see, this website is built using the Material theme for MkDocs, which we have been happily using for over one year after using Sphinx for many years prior to that. GitHub Pages offers built-in support for Jekyll, but not for MkDocs and therefore it requires the manual building and deployment of our website. However, it automates many other things, including HTTPS certificate provisioning on our domain via Let's Encrypt.

There are several somewhat related approaches using GitHub Actions for automating the deployment of MkDocs-generated sites, usually with the Material theme, to GitHub Pages. These guides are not only found on blogs written by enthusiasts; the official Getting started section of the Material for MkDocs documentation describes the usage of GitHub Actions for deployment and provides a generic YAML file for that purpose.

Markdown vs reStructuredText for teaching materials

---

Photo source: Eugenio Mazzone (@eugi1492) | Unsplash

---

Back in summer 2017. I wrote an article explaining why we used Sphinx and reStructuredText to produce teaching materials and not a wiki. In addition to recommending Sphinx as the solution to use, it was general praise for generating static HTML files from Markdown or reStructuredText.

This summer I made the conversion of teaching materials from reStructuredText to Markdown. Unfortunately, the automated conversion using Pandoc didn't quite produce the result I wanted so I ended up cooking my own Python script that converted the specific dialect of reStructuredText that was used for writing the contents of the group website and fixing a myriad of inconsistencies in the writing style that accumulated over the years.

Why we use reStructuredText and Sphinx static site generator for maintaining teaching materials

---

Photo source: Patrick Tomasso (@impatrickt) | Unsplash

---

Yesterday I was asked by Edvin Močibob, a friend and a former student teaching assistant of mine, the following question:

You seem to be using Sphinx for your teaching materials, right? As far as I can see, it doesn't have an online WYSIWYG editor. I would be interested in comparison of your solution with e.g. MediaWiki.

While the advantages and the disadvantages of static site generators, when compared to content management systems, have been written about and discussed already, I will outline our reasons for the choice of Sphinx below. Many of the points have probably already been presented elsewhere.