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.
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:
Here’s a dropdown!
And here’s some stuff inside!
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.
Where is the blog source code? At this github repository
What engine builds the website? The Sphinx documentation engine is the core documentation engine.
What engine builds the blog? I use the ablog Sphinx blog extension to host the actual blog.
What theme do you use for the blog? I use the PyData Sphinx Theme
How do you write Sphinx docs in markdown? I use the myst-parser package
How do you write content in notebooks? I use the MyST-NB package.
How did you make those fancy buttons and dropdowns? That was the sphinx-panels Sphinx extension.
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!