Blogging with Sphinx

After leaving Crate.io at the end of 2020 I am unemployed and actively seeking for a new job for the first time in more than 10 years. So I bought a new domain - you can’t have enough of them, can you? - to prepare a small web presence. It’s kind of embarrassing that even though I’ve been working with web technologies for years I’ve been neglecting blogging. This should definitely change in 2021.

Therefore, I’ve been looking for a set of tools I am familiar with and that could be used for generating a static HTML website - and of course I’ve also considered writing my own static site generator. Eventually I ended up with Sphinx.

Source: sphinx-doc.org

sphinx-doc.org

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.

Why Sphinx?

The decision for Sphinx has multiple reasons.

First, I do have a strong Python background, and Sphinx is one of the most widely used tools to create documentation for Python libraries. However, it is not limited to Python but can be used for documenting all sorts of software projects of various languages. This makes it very suitable for writing programming focussed content.

Second, at my previous job at Crate.io, we’ve been using Sphinx for almost every user-facing documentation and therefore I feel very comfortable using it, despite its slightly quirky default markup language reStructuredText.

reStructuredText is not everyone’s darling and also less common than markdown, but it is much more powerful due to its built-in extensibility. You can easily write extensions (in Python of course!) for your own directives. Furthermore, Markedly Structured Text (MyST) allows you to write your documentation entirely in markdown.

However, Sphinx out of the box, is not intended for blogging and does not provide any functionality to create archive/category/tags pages or RSS feeds. Thankfully, Ahmed Bakan already created a blogging extension called ablog.

Let’s have a closer look on how the blog is configured.

Setup and configuration

In the previous section I already mentioned the core components of which this site/blog consists.

  • Sphinx: The documentation generator that generates HTML output.

  • Ablog: A blogging extension for Sphinx.

  • MyST: An extension to write your Sphinx documentation in markdown.

All of them are installed via pip:

$ pip install Sphinx ablog myst-parser

Additionally, for convenience I use sphinx-autobuild.

Sphinx comes with a default theme named Alabaster. For this site however I use the PyData Sphinx Theme from the PyData community which is both simple and elegant.

Again, they are installed via pip:

$ pip install sphinx-autobuild pydata_sphinx_theme

The initial conf.py that is required for a Sphinx project was generated using the sphinx-quickstart command, which starts an interactive setup wizard. To activate ablog and myst, they need to be added to the extensions:

extensions = [
    ...
    'myst_parser',
    'ablog',
]

The remaining task is to add a few more site specific configuration options to the conf.py, such as author information, sidebars, or Disqus integration.

Writing a blog post

Once configuration is in place, creating new blog posts is just a matter of placing the .. post directive that is provided by the ablog extension at the top of the post file. For example, this page’s markdown source starts like that:

```{post} Jan 17, 2021
:author: Christian
:tags: sphinx, ablog, myst
:category: general
```

# Blogging with Sphinx
...

The equivalent reStructuredText version of this MyST syntax would be:

.. post:: Jan 17, 2021
   :author: Christian
   :tags: sphinx, ablog, myst
   :category: general

Blogging with Sphinx
====================
...

Publishing the site

Sphinx can generate multiple output formats, such as HTML, PDF, or manpages. For a website HTML is usually sufficient perfect for serving it statically via a webserver such as NGINX, via S3 or a CDN.

I host my blog on a small KVM using NGINX. The files of the build/html folder are uploaded using rsync.

$ make html
...

$ rsync --recursive -tUz ./build/html/ haudum.dev:/var/www/website
...

Conclusion

For those who are familiar with Sphinx, using it as a static website/blog generator is straight forward and quickly to implement. The combination with Ablog and MyST is a very compelling alternative to other static site generators such as Jekyll, Pelikan, Hugo, … if your focus is technical or programming content.