A New Blog Built with Sphinx on Azure

Why did you re-write you blog?

20, November 2020 was the day I last day I used Netlify to build errbufferoverfl.me. But don’t be fooled! This time it wasn’t by choice. The Hugo site that I had finally settled on suddenly failed to build, even if I went back as far as a month to the last successful build.

Normally, I’m up for a challenge, but the reality is, my blog isn’t something I want to spend 5 days deep diving just to work out why a 2000-word blog post on Canary Tokens isn’t working, which is also the reason I tried to move away from Pelican, where I spent more time trying to tweak JavaScript of change the theme than I did blog.

I didn’t have a long list of things I expected but ideally it was static, easy to build and deploy, and supported Markdown. While using Hugo and Jekyll are nice, they aren’t in my primary languages, so setting up and debugging was always a bit of a PITA. So the list was:

✅ Static

✅ Easy to build and deploy

✅ Supported Markdown

✅ Python Oriented

✅ Had a “Just the Docs” style theme

The first thing that came to mind was Sphinx, it supports Markdown, but more importantly, it supports reST, but I wasn’t too sure it supported blogging very well, until I came across a Python package called ablog.

If you haven’t heard of it, I wouldn’t be surprised as it doesn’t seem to be a very well known package if the GitHub stats are anything to go by:

GitHub stats showing: 11 watchers, 84 stars, 22 forks

About ablog

Github Link | Documentation

ABlog is a Sphinx extension that converts any documentation or personal website project into a blog and supports:

  • Atom feeds

  • Archive pages

  • Blog Sidebars

  • Disqus integrations

  • Supports Font-Awesome

  • Native reST support

  • Markdown support

  • Supports Sphinx themes

My Favourite Parts

♥️ Simplicity

I’m a big fan of Sphinx, and have used it across a heap of professional and personal projects! It has well supported themes and there are a bunch of extensions that you can use if you need to do more than just document. It’s also a big help that Sphinx has native support for reST and is 100% Python which means when things go wrong there is a good chance I’ll be able to diagnose or in some cases, fix the problem myself.

🚀 Features

As I mentioned Sphinx supports a bunch of additional extensions that you can easily install and get working without much effort, so one of my favourite parts of my new site is I’ve been able to put together a timeline of talks and training I have delivered which normally would have required a bit more work to get going! On top of that, I get all the benefit of Sphinx directives which means my writing will hopefully be more meaningful!

🏃🏻‍♀ JUPYTER NOTEBOOK SUPPORT

While I haven’t got it installed yet (one step at a time) my new blog setup allows me to write full blog posts in Jupyter Notebook, this is amazing because it can also be configured to execute and cache the content!

It also means that even though Jupyter doesn’t support restructured I can easily switch between the two languages depending on the goal, instead of being forced to use a reduced styling set!

Ingredients Needed to Make Your Own

Conclusion

Even though I’m still waiting for Azure CDN to verify my domain (which means this site hasn’t actually been published yet) I’m a big fan of my new setup. I have a slick “just the docs” type theme.

If you enjoyed this post and want to build your own blog on Sphinx using Azure I’ll be putting together a few short posts on how I got there.

👋🏻 Cya next time!