Hello World!Bonjour Tout Le Monde!
quarto
hello-world
setup
english
In which we say hello to the world.
Photo by Artturi Jalli on Unsplash
Executive Summary
At long last, we have finally re-launched a new blog at great expense. I’m writing this in Markdown in Visual Studio Code, but can choose to add in visualisations or AI results through code-chunks. I can even write mathematical equations such as this easily: \[f(c)=\dfrac{1}{b−a}∫^b_af(x)\,dx. \nonumber \]
(That’s the equation for the Mean Value Theorem, if you’re wondering)
When I’m done, I push the changes to Github Pages, which through the magic of Quarto, somehow publishes it for free under my own quirky domain. I control my content fully, and choose to move it anywhere I want to.
Here’s how I did it.
The Setup
I’ve set this blog up using the Quarto framework, which is a new way of writing documents that are a mix of code and text. It’s like Jupyter Notebooks, but with a lot more flexibility. The official documentation was reasonably clear, but really, the crux was to publish it to Github Pages. Albert Rapp’s guide was very helpful in this regard, as was Bea Milz’s 10 step formulation Some bits over and above Quarto’s official documentation include getting comments (look below), and also setting up a newsletter (to be done). Lots of good content there, won’t be repeating it here. Instead, let me tell you about features and gotchas.
The Features
2. Search
Just love the built-in search in Quatro. Simple but works.
3. Visual Studio Code
Now this is mainly for me, but I don’t have to context-switch away from Visual Studio Code just to make a post. In fact, I can even write code in the same document, and it will be executed and the results shown. This also means… I have AI enabled automatically, through GitHub Copilot. Not that it’s helpful, mind you, in fact, for long-form writing, it’s quite annoying. But hey, it exists, and is particularly helpful in all those settings files, and of course, code-chunks.
4. Code Chunks
Need I say more? How cool is this, that I can just write this and it’ll be executed inline?
5. Table of Contents
See the nice bar to the right listing down all the sections? That’s the Table of Contents. It’s automatically generated, and is a nice way to navigate through the document.
6. Internationalisation
తెలుగు, తదితర భాషలలో కూడా సునాయాసంగా టపాయించచ్చు! Je peux facilement écrire en français aussi!
The Gotchas
It’s not all roses though, there are a few gotchas too.
1. RSS Feed
The RSS feed somehow should work, but doesn’t. I’m still trying to figure out why. Fixed it.
2. Posting Comments
You need to have a GitHub account to post comments. I’m not sure if that’s a good thing or a bad thing for you; it certainly is a good thing for me, as I can leverage on GitHub’s plumbing to manage comments. It also acts as a sort of gatekeeper for spam, for now at least.
Also, I really really REALLY wanted Giscus to work, but it doesn’t. Comments on one page show up on all pages. I’m not sure why; presuming it’s a settings thing, but I can’t figure out how to fix it.
Instead, I’m using Utterances, which is a free open-source service that uses Github Issues to store comments. Same-same for you, but different for me in that Giscus uses GitHub Discussions and not Issues. Ah well.
3. No WYSIWYG
There’s no WYSIWYG editor, so you have to write in Markdown. I don’t mind it, but you might.
4. Executing Python code-chunks
Oh boy, this one was a doozy.
So the main attraction for Quarto/ QMD is that you can write code-chunks in any language, and it’ll be executed and the results shown. However, in Python, I typically create a new conda virtual environment for each project, with a limited set of packages for that project. Now, in the Visual Studio Code - Jupyter notebook world, this is crystal-clear; there’s a convenient dropdown to select the environment. But in Quarto, it’s not so clear.
This is made even harder by the fact that the Quarto plug-in for Visual Studio Code pops up an interactive window when you execute a code-chunk. And that window somehow does have a dropdown to select the environment. But hitting Render on the QMD file doesn’t use that selected environment. Instead, you need to hit command/ctrl-shift-p and select the environment there.
It’s all listed in this issue raised in August 2022. Some helpful checks there too. If you hit an error reading the following:
No module named 'nbformat'
.. then it’s very likely that Quarto is referencing the wrong Python executable. On Macs, this is likely to be the flavour that comes with the OS, not Miniconda/ Anaconda or the environment you just chose. You can check on that by running the following in a code-chunk:
import sys
print(sys.executable)
If the output (in the render) is not the virtual environment you expect, then you know what the problem is. Hit command/ctrl-shift-p and select the right environment.
Conclusion
So there you have it. A new blog, with all the bells and whistles, and a few gotchas. I’m sure I’ll find more as I go along, but for now, I’m partying like it’s 1999.
1. Comments
I have set up comments using Utterances. It’s a free open-source service that uses Github Issues to store comments. You can see the comments on the bottom of this page. Pretty neat, non ?