Reviving the blog with Quarto
Following the tradition, we have decided that our first post after migrating to Quarto would be about the migration itself!
Why change?
The HoloViz blog dates back to 2018 and at the time Pelican was chosen as the static site generator together with the pelican-jupyter plugin to add support to authoring blog posts from Jupyter Notebooks. While this combination served us well over the years, we observed that the notebook plugin was deprecated and that there was not much interest among our maintainers and contributors to update the existing site which was starting to show its age. We were in desperate need of a change!
Choosing a framework
One of our key requirements was to build the site from Jupyter Notebooks as the HoloViz tools have first-class notebook support and that is how we generally build our documentation websites. For that purpose we’re usually using Sphinx together with MyST-NB and some other custom extensions. However, except from the ABlog extension, the Sphinx ecosystem didn’t seem to provide what we were looking after and ABlog lacked some features we were potentially interested in (e.g. good integration for sharing on social media). This didn’t leave us with many options other than Quarto!
Quarto is a recent open-source project that was announced in July 2022 and that is sponsored by Posit (formerly known as RStudio). It extends R Markdown, adding for instance, Jupyter Notebook support. We started experimenting with Quarto once we noticed increasing discussion about it from HoloViz users; we wanted to make sure our tools were working well in that ecosystem and the blog seemed to be a good place to start.
We were quickly convinced that Quarto was the right choice: the user experience was smooth, their documentation was clear and all in one place (unlike the Sphinx ecosystem where we had to navigate between various extension websites) and it appeared to support all the features we required. The only point that made us hesitate was that Quarto extensions have to be authored in Lua and none of us had any experience in that language. We decided that this wasn’t a blocker and went ahead with the migration.
Migrating to Quarto
The migration all happened in this PR:
- We had to convert the
<post>.ipynb-metasidecar files used by thepelican-jupyterfiles to the special header Quarto needs at the beginning of every document. - The notebooks themselves needed few changes, except to handle the nested and indented raw HTML included in Markdown cells that wasn’t displayed as HTML by Quarto but partially wrapped in a
<code>HTML element. Removing the indentation fixed this problem (wrapping it in:::{=html} <... :::would also have worked). - We had to move all the posts to the
/postsdirectory which meant that the links to our old blog posts changed. We set up redirect links using thealiasesdocument option to preserve these old links. - We decided that we preferred the default listing layout instead of grid.
- We made some minor styling changes to align it with the styling of other HoloViz websites.
While the migration was quick and went smoothly, we listed a few issues that we might fix in future iterations. We are not too surprised that we have a few minor issues as our blog posts often contain a lot of complex HTML and Javascript that aren’t always easy to handle. We welcome contributions!
Easier contribution
Moving to Quarto improved the contributor experience, with a solid VSCode extension and a nice and fast preview mode, and again their excellent documentation.
We also made our infrastructure easier to manage which improved the contributor experience:
- the site is no longer hosted on AWS but on Github Pages
- a development version has been deployed, it is re-built and re-deployed automatically on every Pull Request event
- the main site is re-built and re-deployed whenever a Pull Request is merged
If you feel like contributing to the HoloViz blog, head over to its Github repo and follow the instructions!