Hello. I work in the humanities, writing academic articles and books. I use Pandoc, via Scrivener and VS Code, to output to docx and PDF via Typst. I have a small set of (hard-earned) Pandoc defaults, filters, shell scripts, templates, and csl files. I don’t use data sets, but I do use cross-refs (to pages, sections and objects), tables, and bibliographies.
I’ve noticed a few of the experienced Scriveners here sometimes advocating for Quarto (and creating Scrivener templates for it), and others at other times cautioning. I understand from some of @nontroppo’s posts that Quarto is effectively an opinionated set of filters and templates for Pandoc.
I am looking for advice, from those who’ve one or the other (or both!), on whether someone with my writing profile might benefit from moving to Quarto, or whether I should just stick with my custom-built Pandoc set up. I manage my writing projects in Scrivener, while sometimes deploying “Sync with external folder” to draft in VS Code.
My question is driven primarily by considerations of (a) ease of use (for example, cross-referencing) and (b) ease of maintenance of the system (in light of all the many extra installations or files a custom-built Pandoc system requires). TIA.
Hello. If you have a Pandoc workflow that works for you, I would stick with it. As you know, it takes a good bit of time and energy to get the system up and running, so any switches need to be worth it. When it comes to these things, the grass is never greener on the other side – it’s just different types of grass
I chose to set up my process using Quarto because it was a newer framework that could allow me to produce different type of content (articles, books, web sites, and slides), dealt capably with figures/tables/equations/citations, and could also run executable code (Python and R). Quarto allows for Markdown, LaTeX, and the newer Typst. There’s even an offshoot called quarto-docs that allows creation of code documentation using Quarto. Best of all, Quarto is very actively maintained.
That said, setting everything up so that I could write in Scrivener but then export to Quarto has taken considerable time. I ended up coding an intermediary app that I named squarto in order to do all the things that I needed/wanted to do, effectively creating a different preprocessor/postprocessor that could extend or replace Scrivener’s Compiler. This is a work-in-progress and kind of my hobby. (Makers gonna make!) Simpler solutions exist (mainly, specialized project templates for Scrivener), and if you wanted to try Quarto but use a workflow similar to the Scrivomatic/Pandocomatic system, I would go that route.
My main suggestion, thought, is that you identify what is not working well in your present Pandoc-based system. There may be a way to improve what you have over switching to something new. Avoid the FOMO!
For cross-referencing, if that is your main interest in it, there is the pandoc-crossref filter that is worth taking a look into. I think I recall hearing somewhere that this is in fact what Quarto uses rather than having reinvented the wheel. I intend to investigate this option myself, when I start the process of migrating our user manual projects from MultiMarkdown to Pandoc.
I think this is very much a personal preference. Personally I don’t use Quarto largely because I dislike their requirement to keep all filters/templates in the compile folder. They do this to make the compile more “reproducible” as everything is folder-specific and so updating a package elsewhere should not trigger a change in the project. It makes sense of course, but I hate it, so I personally prefer sticking with a lower-level (where files are managed in the pandoc data directory). Quarto offers me nothing feature-wise that I can’t get from Pandoc + filters, and a file organisation workflow I dislike.
I do think their cross-referencing is quite nice and unified, and I like their document aesthetics (especially the web site setup and html outputs). I think for many users Quarto offers a more unified, controlled workflow, so especially for less technical users it certainly can be a better fit. Quarto actually includes Typst CLI and so it also makes setup simpler (only install one tool rather than two) to make PDF generation is a bit simpler.
I get the feeling from what you have said that you are comfortable enough to manage Pandoc directly, so unless there is a compelling feature you need, stick to Pandoc. As for Scrivener, I think both Pandoc or Quarto work equivalently. Quarto does need some post-processing for things like cross-reference labels to work more smoothly with Scrivener’s tools. But these are quite minor, and as Quarto is Pandoc at its core, it is easy to run most pandoc projects through Quarto without many changes…
For cross-referencing there are several Pandoc filters that work well, in addition to using either Scrivener’s placeholders and/or replacements as needed. So far I’ve been happy with placeholders as I only really cross-ref figures, rarely more things.
For my students, I have suggested Quarto rather than Pandoc due to this slightly simpler interface. Also collaborating via github with plain text, then Quarto’s all-one-folder approach has advantages over Pandoc. Thus for collaborative writing online (where Scrivener sucks), Quarto with VS Code and Github seems better (VS Code is free and cross-platform, great for poor and often Windows-based students).
I second this. If someone were starting from scratch and wanting the power and flexibility of pandoc-based processing I would recommend they learn Quarto. But since you have a workflow that works for you, I don’t think there’s compelling reason to change. That’s the choice I made, at least. I do use pandoc-crossref, and the fact that Quarto doesn’t rely on the author of pandoc-crossref still caring about the project is a plus (he’s great, but he often stresses in his github discussions that he is frequently pressed for time). But the way I think of it is that Quarto will be there if I ever need it. Meanwhile, I’ve got my Scrivener setup just where I want it, so why mess with a good thing.
Last thing from me: I often have a fair number of equations in my text, but even if you don’t you’ll still have things like blockquotes after which you’ll want to force the output not to indent the next line of text. I have my Scrivener template set up in a fairly complicated way that enables me to do this, but there is a simpler way that you may not know about. I described it here.
This is very, very thoughtful advice—thank you all! As a global response to the general question of why Quarto seemed attractive:
The ability to produce different types of content from a single installed software package, with one command.
A single syntax for cross-references that simply work, regardless whether the output is TypstPDF, docx, or otherwise.
Less clutter in cross-referenced headings and other objects, thus remaining truer to ‘easy to read’ markdown.
Simpler YAML that contains all output types, without needing to maintain separate Pandoc ‘default’ files or pandocomatic recipes.
Staying out of the rabbit hole of dependencies and installations for full (humanities) functionality, and simply installing (and maintaining) one package. Think ruby, paru, pandocomatic, pandoc-crossref, a stable of Lua filters, shell scripts, etc.
Instead of being dependant on packages (such as for cross-referencing) maintained by one person, having an integrated installation backed by a large team (itself built on Pandoc’s solid team).
Built-in advanced bibliography support, such as multiple bibliographies, easily interspersing citations in footnotes full of prose, etc.
However, after some experimentation and in light of your responses, perhaps some of these hopes are overstated or misplaced. For example, cross-referencing page numbers for both Typst-PDF and docx, from one source, still requires customisation or lua filters for both Quarto and plain Pandoc. Quarto’s YAML appears simpler, but for more complex cases, probably not by much. Advanced bibliography supports seems to require @bernardo_vasconcelos’s excellent Cite Tools, for both plain Pandoc and Quarto alike.
As @nontroppo said, Quarto’s defaults are tasteful. And perhaps slide-making and static website production would be easier and faster. With monographs or translations, I assume the difficulty levels are the same. At the end of the day, time is most precious, and any easements help in day-to-day academic life. But from what you’ve all written, it appears plain Pandoc, once setup, permits the same.
I also work in the humanities. While learning to set up a very basic Scrivener+Pandoc workflow, I came across Quarto and felt curious but discouraged from delving further into it, since Pandoc is already very demanding for me.
But in contrast to @talazem, my workflow is still at a very early stage, as shown by this recent thread where I basically was taught to tell the difference between reference documents and templates.
So, judging from that thread, I probably still do not have a proper workflow that works for me, because what I can do is pretty basic. Before I move into more advanced uses of Pandoc, and effectively create my set of templates, reference documents, filters, and so on, would anyone advise that I take a step back and learn Quarto instead? Would things be easier for me, at least at this basic stage?
For background: I started learning Pandoc because I need to use Scrivener alongside Zotero for handling references. Scrivener’s default MultiMarkdown to .odt and Pandoc to .docx do not give me that option. Following this wiki, I obtained the desired results. I would probably not have tried to learn Pandoc were it not for this need.
I finally had a chance to give Quarto a spin. I ‘transferred’ the article I am currently writing into it and also prepared some slides for a lecture.
I have found the collective wisdom above to be true, and will stick with plain Pandoc. The extra ‘layer’ of Quarto actually slowed me down. It could just be that I have grown accustomed to making my way around basic Pandoc. But any customisation of output, such as to Typst and Word, will require crafting templates, defaults, and bibliographic reference files anyhow. So you’re back to direct exposure to Pandoc (and reading its user manual) in any case, and then have to learn to work Quarto’s way, on top.
Like @nontroppo, I might encourage new, technically-inclined humanities grad students to Quarto, if they wish to write and archive their writing in plain text. One installation, and you’re up and running. But for humanities authors writing long-form via Scrivener anyhow, I think Pandoc can be faster, as it is one less layer to worry about. A lot of the learning curve and time investment simply comes from setting up Scrivener with Pandoc or Quarto. @tqctc, perhaps try it with a live writing project, and see which of the two camps you fall into.
Yes, absolutely I would. Quarto is an advanced use of Pandoc. But its created and supported by a team that is accountable to its users and who can help you through difficulties. At early stages of creating a Pandoc workflow I hit roadblocks that I wasn’t sure I was going to be able to surmount, and there was no one whose job it was to help me through it.
That said, AI has gotten absurdly good with providing nuanced tech help. So no matter which route you go, consider enlisting that when you hit a snag.
While I agree to some level, Quarto’s dev team and userbase is quite small compared to Pandoc, and many Pandoc power users plus the main developers John and Tarleb are all active and do answer github issues / discussions. Quarto being a free open-source tool is probably not the main priority of the company (Posit, that develop a cool statistics IDE and great packages for the R programming language), and for more advanced tweaking you actually use pandoc filters and templates whether you are using pandoc or quarto under the hood…
And I do agree that there is some security in having a company invested in a tool. Posit is awesome, if anyone has had to use any of their R packages can attest they utterly rock. As a scientist mostly used to MATLAB and building my own statistical pipelines and visualisation, using ggplot and their tidyverse packages really blew my mind. It is hard to underestimate the beauty in how their tools transform and manipulate data. So it didn’t surprise me when they wanted to build an R reports and more general publishing tool, Quarto, what they made (and the fact they chose to build on pandoc) was also awesome. Documentation is great, the default templates and bespoke features are great.
Sadly, however, one of the main people answering tech questions on their forum is a bit of a curt meanie. Something I’ve not once experienced on this here forum.
Edit: I guess I should correct that to say he’s more of a grump than a meanie.
