30 Quarto: A Publishing System for the Plain Text Age
Guiding Question: Can publishing itself become reproducible?
Imagine writing a book.
Now imagine maintaining a website based upon the same material.
Later, you prepare a journal article drawn from one chapter.
Finally, you create a presentation for a conference.
Traditionally, each of these tasks required its own workflow.
Different software.
Different files.
Different publishing systems.
The work quickly became fragmented.
Modern publishing asks a different question.
What if every stage of publication could begin from the same source?
Quarto answers that question with remarkable elegance.
30.1 Building Upon a Strong Foundation
Earlier we met Pandoc, the universal document converter.
Pandoc demonstrated that documents could be translated between many different formats while preserving their structure and meaning.
Quarto builds upon that foundation.
If Pandoc is the publishing engine, Quarto is the publishing system.
It provides the organization, project structure, automation, and workflow that allow authors to move naturally from writing to publication.
30.2 From R Markdown to Quarto
Quarto did not emerge from nowhere.
Its roots lie in the work of the team at Posit, whose earlier projects—including R Markdown and knitr—demonstrated that plain text could unite narrative, computation, and publishing within a single document.
Those ideas proved enormously successful.
Quarto expands them beyond a single programming language, creating a publishing system that welcomes writers, researchers, educators, technical authors, and developers alike.
The result is a platform whose primary language is not R or Python.
Its primary language is structured plain text.
30.3 Projects Rather Than Documents
One of Quarto’s most important contributions is the idea of the project.
Rather than treating every document as an isolated file, Quarto encourages authors to organize related work into coherent collections.
Books.
Websites.
Blogs.
Documentation.
Articles.
Presentations.
Everything belongs within a project whose structure is described explicitly.
The result is a publishing workflow that scales gracefully as ideas grow.
30.4 The _quarto.yml File
Every Quarto project begins with a simple text file.
text id="xx2v0u" _quarto.yml
This file describes the project.
Its title.
Its chapters.
Its output formats.
Navigation.
Themes.
Publishing options.
Instead of navigating countless dialog boxes, the author records these decisions once in a human-readable configuration file.
The project itself becomes documentation.
This philosophy should now feel familiar.
Configuration is expressed through plain text.
30.5 One Project, Many Outputs
A single Quarto project may produce:
- websites
- books
- PDFs
- EPUBs
- journal articles
- presentations
- dashboards
The author’s workflow remains remarkably consistent.
Changing the publication target rarely requires rewriting the document itself.
The source remains authoritative.
The outputs multiply naturally.
30.6 Citations and Cross References
Professional publishing requires more than headings and paragraphs.
Books require chapters.
Research requires citations.
Technical documents require figures, tables, and cross references.
Quarto integrates these capabilities directly into the publishing workflow.
Because everything remains within the same project, references remain consistent regardless of the final publication format.
This integration allows authors to concentrate on developing ideas rather than managing formatting details.
30.7 Reproducible Publishing
One of Quarto’s greatest strengths is reproducibility.
A project can be regenerated at any time.
Corrections propagate naturally.
New editions inherit the same structure.
Entire websites can be rebuilt from source.
Books can be republished with confidence.
Publishing becomes a repeatable process rather than a sequence of manual steps.
30.8 Why Quarto Matters
Quarto represents more than another markup language.
It represents the maturation of the plain-text publishing philosophy.
Writing.
Computation.
Documentation.
Presentation.
Web publishing.
Books.
Research.
These activities no longer require separate workflows.
They become different expressions of the same carefully structured source.
30.9 Lessons for the Textsmith
Throughout this primer we have repeatedly encountered the power of separation.
Content remains separate from presentation.
Structure remains separate from formatting.
Automation remains separate from manual effort.
Quarto extends that philosophy once more.
Writing becomes separate from publishing.
The author creates one carefully maintained source.
Quarto quietly handles the journey from manuscript to finished publication.
The result is not merely greater efficiency.
It is greater freedom.
30.10 Key Ideas
- Quarto builds upon Pandoc to provide a complete publishing workflow.
- Its origins in R Markdown and knitr illustrate the evolution of reproducible publishing.
- Projects organize related documents into coherent publishing systems.
_quarto.ymlcaptures project configuration in plain text.- A single Quarto project can produce books, websites, articles, presentations, dashboards, and more.
- Reproducibility allows publications to be regenerated consistently from a single source.
- Quarto embodies the philosophy of separating writing from publication.
In the next chapter, we turn our attention from documents to the Web itself.
Can an entire website be written in plain text?
There we discover how static site generators and modern publishing systems transform simple text files into websites that are fast, durable, accessible, and surprisingly elegant.