About a month ago I saw a post on Hacker News that led me to check out Quarto. Quarto claims to be “an open-source scientific and technical publishing system built on Pandoc”. I love writing in Markdown for both academic publications (especially during the draft process) and for course content. I write my lecture notes (destined for slides), homework assignments (either PDF or MediaWiki output), and personal notes (destined for nvAlt / Obsidian) in Markdown already. I quickly noticed that some of the same folks who develop R-Markdown are involved with Quarto, and it has backing from R-Studio. I think the R-Markdown project is doing some awesome things, so that really grabbed my attention.

I installed Quarto on January 23, so I’ve been using it for about a month now. Here are some things (good and bad) that I’ve noticed so far…

General Impressions

Quarto tries to be an end-to-end publishing experience. It works with regular Markdown format, the Pandoc flavor of Markdown, and also adds some of its own extensions in places. Mostly, it looks and feels like Pandoc markdown with Citeproc, Fignos, and Tablenos filters active. It can also understand R-Markdown and Jupyter notebooks as input (and output) formats. It can also convert between formats pretty effectively – in this way, it is doing the same thing as the Jupytext project which I have been an avid user of for a couple of years. So, with one install, you get Markdown/R-Markdown/Jupyter to «choose your favorite output format - Quarto supports practically anything», and the input formats are also supported output formats! Nice.

How I’m using Quarto (some are aspirational at the moment)

Creating Exams (pdf)

I use a very custom template for my in-class exams, so I wasn’t sure how well Quarto would adapt to it. I ran into one small issue with the YAML option margin somewhere in the Quarto pipeline clashing with the custom variable I had in my template, but it was easy to update my template to avoid the name collision. The output is now exactly the same as the old way (with raw Pandoc and a lot of flags).

Lecture Notes (pdf)

I use PDF (Beamer) lecture notes for some of my graduate courses, again with a custom template. I was pleasantly surprised to find that it all worked flawlessly just by setting the template in the YAML front matter. Easy! I haven’t used any algorithmic figure output yet, but I have experimented with it in a toy deck, and it seems that it will work fine.

Lecture Notes (HTML-via-Markdown)

I keep many of the slides for my undergraduate online as a website hosted on Github Pages, and generated by Hugo with Remark.js (see my repo here). Quarto is capable of generating Reveal.js output, but actually my system only requires Hugo-compatible Markdown with all the assets (images, etc) in the right places. I think I can make it work with the Hugo output options Quarto offers, but I haven’t had time to experiment with this yet. I’m really not sure it would save much time/effort, but maybe the citation management and auto-generated figures would be nice… I look forward to trying it out soon.

Academic publications

TBD. I have not had a chance to start any new academic writing using Quarto yet – but I absolutely intend to start my next manuscript this way to see how far I can get.

Pros

Here are a few things that really stand out about Quarto so far:

YAML front matter support for selecting output formats and templates.

This was a big gripe of mine with respect to Pandoc alone (and a feature I love in R-Markdown). I want to be able to specify the output format and template right in the front matter. Yes, I know that personal taste in YAML-in-Markdown varies out there, but for my use case this makes a lot of sense.

Better figure positioning options

This is another big one. Positioning figures and tables in Pandoc/Markdown can be infuriating, let alone if you have multiple output format targets. Quarto brings its own extensions for doing this, and they work pretty well (at least in my short time using them so far). Not just the things you would think would be considered table stakes, like left/center/right justification… I mean, multiple figures in a row? Figures with sub-figures? Finally.

Unified preview, render, convert

Before Quarto, I used some tools that could live preview (Hugo can do this). I used Pandoc for the rendering, and for some type-conversion functions. I used Jupytext for type conversion where Jupyter Notebooks were involved… Quarto can do all of this in one tool. That is super convenient.

Page layout options

I’m not sure how much I would use this, but it is nice that you can choose to position content in the margin, or to make a section that is wider than the rest (maybe for a figure or large table). Before, it was a pain. Quarto makes it easy. (Or, they make it look easy - I haven’t had a chance to make any real use of this yet.)

Cons

No tool is perfect. This one is still new and in active development, so of course there will be some rough edges. Here are a couple that I hope are worked out soon (or eventually, at least):

.qmd extension (sometimes) required

Just what the world needs - another file extension that may be Markdown. I tend to just use .md for all my markdown files - and my editors all understand what that means. Quarto introduces .qmd to denote their own flavor of Markdown. It makes sense to avoid confusion if a plain Markdown converter doesn’t give the desired results because of the extensions - but that is also the case with e.g. Pandoc Markdown extensions, or «choose your Markdown flavor» extensions. We live with it and move on. My complaint is that Quarto requires .qmd on files that contain code that should be executed while rendering the document. Internally, they also use a slightly different syntax for these code blocks, so the renderer should be able to tell the difference anyway – why also require the extension? The extension doesn’t seem to be required for any of the other “magic” to work… Let me have my executable block cake and eat my .md extension too, Quarto – please?

YAML options are sometimes flaky

As much as I love the added functionality Quarto brings to the YAML front matter – I find some of the options are flaky at times and seem to have no effect for reasons I can’t figure out. For example, I have had no luck setting the font size with the fontsize option. I’m not sure if it is something I’m doing wrong, or whether something in Quarto is broken, or maybe it is something in my LaTeX template (and also the HTML output???). I just don’t know. I am quite impressed with how many of these options do work though, across the different output formats. It gives me hope that they will all be solid eventually (or I will figure out that it was my mistake all along).

Markdown extensions are a double-edged sword

Let me reiterate that I love some of the extensions the Quarto team have added to allow things like rational figure positioning options in Markdown. I love it. But, if Quarto ever goes away you are stuck with non-standard Markdown files that no longer render the way you want in vanilla Pandoc. It would be nice if the Quarto team could work with John MacFarlane and the Pandoc community to get some of these features into Pandoc proper. This is a minor nitpick, but I’ve had fantastic tools go away before, and it leaves a bitter taste when you lose features.

Final (early) impression and hopes for the future

Well, I can sum this up simply as: “Try Quarto – if you create a variety of scientific or academic content using Markdown, you’re going to love it!” It isn’t perfect, and there are some bugs here and there, but the team is strong and I am optimistic about this tool. I suppose I’ll have to check back in a year or two to see if I still feel the same. Until the, give Quarto a try. Let’s all work on bringing plain-text manuscript development into the academic mainstream so that we can collaborate with modern tooling like git and stop fighting “styles” and terrible equation editing and reference management in Word documents.

My biggest “wish” for Quarto at the moment would be that they drop the requirement for the .qmd extension for files that contain code blocks intended to be executed. If they are worried about the user being surprised, or wanting the blocks to not execute sometimes - why not add YAML options to turn it on/off? The custom fenced code block syntax already seems to guard against unintended behavior. Sure, you might have to make a one-pass edit to bring old .md files in line, e.g convert ```{python} to ```{.python} to prevent execution – but that’s a simple find-and-replace-all operation. As an aside: I wonder why they didn’t decide to make the “dotted” version mean “executable” instead – thus removing the most common conflict here? ¹

Don’t forget a little dash a.

Typos are too easy. I have to laugh about this one though…

I needed to quickly add a user to a server I administer and make sure they could read/write within the web server’s document root without giving them sudo rights. Simple; create the user newuser and add a new group webadmin real quick to allow that group write permissions in the directory. Put the new user into the webadmin group and Bob’s your uncle. Simple.

Why not add myself to that group too, so that I don’t have to sudo to modify the directory either? We had locked the files in there to remove write permissions earlier, but if I’m setting up group permissions, I might as well take advantage of that as well. Probably should have done that a long time ago… Let me just add myself to the group:

sudo usermod -G webadmin myusername

Done and done.

Did you catch the error?     (I didn’t until it was too late.)     The correct command was:

sudo usermod -aG webadmin myusername

Yep. I just replaced all my groups (including sudo) with just one: webadmin. Sure, I can write in the document root now, but I’m not really the admin anymore. And I’m working remotely, so there is nothing I can do on this machine to fix that without going on site.¹ 🤦‍♂️

Sometimes it’s the easy things that get you.

-a