Simplify Your Writing Process with Quarto

A tool for books, ebooks, reports, websites, ....

Technical writing is a part of data science, a part of the process where you share results.

Let’s say you analyzed some data, or you trained a machine learning model and you want to create a report. Or, as in my case, you write technical books. But there are some problems if you just use Microsoft Word or LaTeX:

• The document should include computed results like graphs, tables, and some numbers. Copy-pasting is tedious, so you want it to be interwoven with your writing in an automated fashion.

• You are used to having your code version-controlled. You want the same for your texts so you sleep better at night, knowing that your work is tracked.

• You want more than just one type of output. Or maybe your boss wants more than one type. So maybe the produced result should be a PDF that is printed, but you also want a searchable website.

• You want to avoid, at all costs, writing in LaTeX. At least I learned to hate it.

There’s a technical solution to all of these problems. And the solution is to write both code and text in markdown and then use a program called Quarto to do all the heavy lifting of executing the code, including the results in the markdown and converting it to all possible formats.

That’s how I write my books.

If you don’t know markdown, it’s a plain text file usually with the ending .md. There are commands, like “#” for titles, using “-” for lists, and representing links like this: [link to my website](christophmolnar.com). And this markdown file can be converted to an ebook, a report, a book, a website, and so on.

Getting Started With Quarto

• First, install Quarto on your machine

• Then write whatever you want to say in Markdown. In fact, it’s a special Quarto markdown format (.qmd), but if you know markdown you will feel right at home.

• A configuration file called _quarto.yml controls your project:

  • Which output files are created (PDF, ebook, website, slides)

  • Order of text inputs

  • Citations style

  • Title, subtitle, author

• Then you call “quarto render” to produce the file types defined in your configuration

Quarto offers many options to configure your projects and documents. And Quarto comes with great documentation, where I always found what I was looking for.

How does Quarto work?

• Write: Write plain text, in the form of Markdown files (qmd).

• Render (part 1): Only executed if there are code snippets in the text:

  • Convert: The markdown files are converted to Jupyter notebooks.

  • Execute: To create all the numbers and figures that are included in your texts, the notebooks are executed.

  • Convert: Convert notebooks + results like plots back to markdown

• Render (part 2): With Pandoc as engine, Quarto then renders the markdown to the desired outputs (PDF/epub/html/…)

• Publish / Share

That’s the beauty of it: Write everything in one file format and convert to any format that you like.

Like all my other books, Interpretable ML is completely written in Markdown. And with the click of a button, it’s turned into a website, an ebook that I sell on Leanpub, and a PDF that turns into the print version for Amazon.

And that makes me happy.

And I almost don’t have to touch any LaTeX, just a little bit for the first pages.

Let me know if you are interested in a more in-depth description of how I write my books with Quarto, and I can go deeper here.

Btw. this post was not sponsored in any way by Posit, the company behind Quarto. I’m just a big fan of Quarto and it has helped me immensely so far.