11  Quarto Book Authoring Tips

Quarto allows you to combine code, narrative, figures, and results into a polished, reproducible technical document.
Throughout this Tools-in-Action project, Quarto served as the publishing engine that ties together each tool you learned:
Git, Linux, Shell scripts, Makefiles, SQL, pandas, HTML scraping, pytest, and PyTorch.

This chapter summarizes useful practices for authoring clean, organized, and reliable Quarto books.

11.1 Structuring a Quarto Book

A Quarto book is controlled by the _quarto.yml file, which defines:

  • The book title and author
  • The order of chapters
  • Themes and formatting options
  • Execution settings (freeze, echo, warnings, etc.)

Example structure:

book/
  _quarto.yml
  index.qmd
  01_git.qmd
  02_linux_basics.qmd
  03_shell_essentials.qmd
  04_makefile.qmd
  05_sql_sqlite.qmd
  ...
  10_quarto_book.qmd

The index.qmd file is the homepage, while each chapter appears in the left-hand navigation sidebar.
Numbering chapters (01, 02, 03…) ensures they appear in the intended order.

11.2 11.2 Executable Code Blocks

One of Quarto’s most powerful features is its ability to run code inside the document and automatically display both the code and its output.
This makes your book fully reproducible—anyone who renders it will get the exact same results.

11.2.1 Basic Example

Here is a simple Python code block:

x = 5 * 5
x

When Quarto renders the book, it will show:

  1. The code you wrote
  2. The output produced by the code

In this case, the rendered output would be:

25

11.2.2 Why This Matters

Executable code blocks allow you to:

  • Demonstrate concepts with live examples
  • Show real outputs instead of screenshots
  • Keep your analysis reproducible
  • Ensure consistency across chapters

Whenever the data or code changes, Quarto automatically updates the results—no manual editing required.

11.2.3 Showing or Hiding Code

You can control what appears in the final book using chunk options:

#| echo: false
x = 10 * 3
x

This will display only the output, not the code itself.

Use this when you want the reader to focus on the result, not the computation.

This section lays the foundation for writing clean, readable, and reproducible technical documents using Quarto.