A new blog with Sphinx

I recently re-wrote all of the infrastructure for my blog so that it now builds on top of the Sphinx ecosystem! This is a short post to describe the reasons for doing so, and a bit about the implementation.

https://www.sphinx-doc.org/en/master/_static/sphinxheader.png

Why did you re-write your blog?

This is a great question. The answer to “should you re-work your blog to use a new SSG” is almost always “no, it’s a waste of your time”, but I think I had a few good reasons ;-)

🐶 Dog Fooding

First, I’ve been doing a lot of work with the Executable Books Project lately. As a result, Jupyter Book now depends on Sphinx. The more I use Sphinx in my own workflows, the more I’ll be equipped to improve the Sphinx ecosystem and Jupyter Book in ways that will benefit its users.

🎁 Upstreaming

A big reason for moving Jupyter Book to Sphinx was to give ourselves more excuse to upstream improvements to the broader community. Switching over my own blog is for the same reason.

🌷 Simplicity

I understand the Sphinx ecosystem relatively well, and use it across many of my projects. It’s got a number of great themes and a ton of extensions to do more things with my content. Moreover, it’s 💯 Python and I don’t have to worry about installing extra languages etc to build my pages.

🚀 Features

It turns out that building your blog (or any content for that matter) on top of a documentation engine gives you a lot of extra things to try that you don’t usually get from a SSG. Being able to use Sphinx roles/directives from within a page is pretty cool. I can do stuff like this:

Wow, a tip!

What a great tip!

🪐 Executable content and notebooks

On top of the base Sphinx features, MyST-NB now lets me write my entire post in notebooks, and will execute and cache the content for me if I wish. I can also write the whole notebook as markdown which keeps my posts easily diff-able.

The components that make up this blog

OK so how is this blog actually built now? Here is a quick rundown.

Specifically, my website is hosted here and all of the blog posts are in this folder. I’m configuring ABlog to find any markdown files in this folder and treat them as blog posts.

In conclusion

So far, I quite like this new blog setup. Sphinx is familiar to me, and I think that using this for my own blog will help me understand how the ecosystem could be further-improved to support blogs in other contexts. If you want to check out this blog’s setup, see this blog’s repository to get started! Next up, I’m going to see how easy it is to do this in Jupyter Book!

Comments

comments powered by Disqus