First impressions of blogging with Quarto

…and how I ported content from my Sphinx based blog


Mark Isken


February 3, 2023

As I mentioned in a recent short post, I’ve moved my blog to Quarto. I’ve been using various static blogging tools since 2014 when I moved my blog from Drupal to Pelican. Pelican served me well for many years and allowed me to write posts in either restructured text or markdown and I could even create blogs from Jupyter notebooks or R Markdown documents. Yes, there was quite a bit of extension installing and fiddling with, but all in all, it worked really well.

Based on my experience with creating my teaching websites with Sphinx, I decided to give it a try for blogging when I happened to run across the ablog Sphinx extension. There was lot of exciting things happening in the Python publishing world such as JupyterBook, the MyST parser, and MyST-NB. I was already a huge fan of Sphinx. Again, I was able to author posts in either reSt or markdown and could use Jupyter and R Studio. Some fiddling involved to make all these things play nicely together, but it all worked. I also moved my blog off of a commercial hosting site and used GitHub Pages. The workflow of pushing a commit to a repo resulting in a website refresh was a nice benefit.

So, why switch to Quarto?

The community

While the Sphinx community is terrific, not a lot of people seem to be blogging with it. The ablog extension changed hands and there’s not much active development aimed at new features for general users. As a long time member of both the Python and R communities, I really wanted a similar experience specific to blogging. When Quarto made it clear that it wasn’t just about R, I started paying attention. Then, a few Quarto based blogs caught my eye, such as Notes from a data witch (easily the best data science blog title I’ve ever run across), Data Science Bytes - Blog and Crosstab Data Science. They looked great. The authors seemed happy with the authoring tools and experience. I got the feeling that this thing was really going to take off. Then I found these incredibly useful blog posts by new Quarto users and I was sold.

Multi-language support that just works

I want to be able to blog from within R Studio, Jupyter Lab, or by writing markdown with some text editor. I also want a command line interface that I can use if I want. Quarto supports all of this. You can even mix R and Python (and more) within the same Quarto markdown document.

Great documentation


Not too painful to port Sphinx blog to Quarto blog

My Sphinx based blog was made up of a mix of reStructuredText, markdown and Jupyter notebook documents. I did end up touching every post (~60 posts) as this gave me a chance to fix up some tags and add some update notices at the top for some of my more dated posts. The strategy for each document type was as follows.

I used a Quarto folder structure in which each post lived in its own subfolder inside of a folder named posts. Inside of each individual post folder there were folders for images and data as needed.

Markdown files

I replaced the existing YAML header with a Quarto specific version and renamed the file to have a .qmd extension. I made sure any necessary image and data files got put into the appropriate subfolders. All of my previous posts had used the same images and data subfolders so no path changes were needed. That’s it.

reStructuredText files

For these, I first converted them to markdown format using pandoc.

pandoc -f rst -t markdown some-post.rst -o some-post.qmd

Then I did the same things I did with markdown files.

Jupyter notebooks

These already had a raw cell at the top of the notebook containing a YAML header. I just replaced the existing header with the Quarto version. I reran the entire notebook and then just plopped it into its new home in a subfolder of posts. The images get encoded and embedded in the notebook itself.

Ongoing authoring

I’ve authored a number of new posts using both R Studio and Jupyter notebooks. It’s extremely simple to just click “Render” from within R Studio and the site gets updated locally. Then using git to stage, commit, and push the changes to GitHub is all that’s needed to publish the updates to my Netlify hosted site. Setting up Netlify was super easy - I just followed Step 6 in Creating a blog with Quarto in 10 steps and the Netlify docs.

The workflow for authoring and publishing is so simple that I find it motivates me to write more often.

As I get more time, I’ll dig back into some of the helpful blog posts mentioned above and do some more site customizaton. But for now, I’ve got it looking ok and I’m just focusing on creating and posting content.