Overview and Architecture

Relevant source files

• .gitignore
• README.md
• dev-docs/add-typescript-dependency.md
• package/scripts/deno_std/deno_std.ts
• package/scripts/deno_std/download.bat
• package/scripts/deno_std/download.sh
• src/command/capabilities/capabilities.ts
• src/command/capabilities/cmd.ts
• src/command/command.ts
• src/command/inspect/cmd.ts
• src/command/run/run.ts
• src/core/console.ts
• src/core/jupyter/capabilities.ts
• src/core/jupyter/exec.ts
• src/core/jupyter/jupyter-shared.ts
• src/core/jupyter/kernels.ts
• src/core/log.ts
• src/core/progress.ts
• src/dev_import_map.json
• src/execute/jupyter/jupyter-kernel.ts
• src/import_map.json
• src/quarto.ts
• src/resources/deno_std/deno_std.lock
• src/resources/deno_std/import_map.json
• src/resources/deno_std/run_import_map.json
• tests/docs/books/simple/.gitignore
• tests/docs/books/simple/_quarto.yml
• tests/docs/books/simple/chapter2/chapter2.qmd
• tests/docs/books/simple/cover.png
• tests/docs/books/simple/index.qmd
• tests/docs/books/simple/intro.qmd
• tests/docs/books/simple/notebooks/computations.ipynb
• tests/docs/books/simple/references.bib
• tests/docs/books/simple/references.qmd
• tests/docs/books/simple/summary.qmd
• tests/docs/run/test-stdlib.ts
• tests/smoke/check/check.test.ts
• tests/smoke/run/command-passthrough.test.ts
• tests/smoke/run/run-script.test.ts
• tests/smoke/run/stdlib-run-version.test.ts

This document provides a high-level introduction to the Quarto CLI system, explaining its purpose as a scientific and technical document publishing system and outlining the major architectural components and how they interact. For detailed information about specific subsystems, see:

• System Architecture and Core Components — Detail the major subsystems (schema, execution, rendering, project management) and how they interconnect, including the role of Pandoc as the document transformation engine.
• CLI Commands and Entry Points — Document the main CLI commands (render, preview, serve, create, check, publish, convert) and their command-line interfaces, explaining how user commands flow through the system.
• Document Processing Pipeline — Explain the end-to-end flow from input document to output format, covering execution, AST transformation, filtering, and format generation.

---

Purpose and Scope

Quarto is an open-source scientific and technical publishing system built on Pandoc. It transforms source documents—including Quarto markdown (.qmd), Jupyter notebooks (.ipynb), and R Markdown (.Rmd) files—into publication-ready outputs in a variety of formats such as HTML, PDF, EPUB, and RevealJS presentations. README.md10

Key capabilities include:

• Computational Execution: Embedding code and output from Python, R, Julia, and JavaScript via integration with Jupyter, Knitr, and Observable. README.md14
• Document Transformation: Extensions to Pandoc Markdown for technical writing including cross-references, sub-figures, layout panels, callouts, and more. README.md16-17
• Project System: Rendering groups of documents at once (websites, books) and sharing options across documents. README.md18
• Authoring Support: Integration with JupyterLab, RStudio, and VS Code, including a visual Markdown editor. README.md20-22

The system is implemented in TypeScript for the Deno runtime and orchestrates external binaries including Pandoc and Typst. src/quarto.ts129-134

Sources: README.md10-24 src/quarto.ts122-140

---

High-Level System Architecture

Quarto CLI is organized into layered subsystems centered around command processing, document execution, rendering, and output generation. The system is built on Deno and uses a monkey-patching approach for path handling early in the lifecycle. src/quarto.ts7-9

Major Architectural Components

Component	Description	Code Location
CLI Entry Point	The main function quarto() responsible for CLI initialization, argument parsing, and dispatch.	src/quarto.ts src/quarto.ts122
Command Registry	Collection of available CLI commands (render, preview, serve, etc.).	src/command/command.ts src/command/command.ts35
Project System	Handles registration and management of project types (websites, books, etc.).	src/project/types/register.ts src/quarto.ts49-50
Language Handlers	Discovery and management of computational language backends.	src/core/handlers/handlers.ts src/quarto.ts46-47
Format Registry	Registration of writer formats and output targets.	src/format/imports.ts src/quarto.ts52-53
Binary Passthrough	Logic for directly invoking bundled binaries like Pandoc and Typst.	src/quarto.ts src/quarto.ts85-120
Logging & Console	System for progress bars, spinners, and multi-level logging.	src/core/log.ts, src/core/console.ts

Architecture Diagram: Quarto System Orchestration

Sources: src/quarto.ts43-56 src/quarto.ts122-140 src/command/command.ts35-63

---

Mapping Natural Language Subsystems to Code Entities

This diagram links conceptual subsystems of Quarto to their primary codebase entities.

Sources: src/quarto.ts122-126 src/command/command.ts35 src/command/run/run.ts14 src/core/log.ts49 src/core/console.ts90 src/execute/jupyter/jupyter-kernel.ts59

---

CLI Commands and Entry Points

Quarto CLI uses the cliffy framework to define its command structure. The entry point handles environment setup, version checks, and reconfigurations before dispatching to specific command handlers. src/quarto.ts170-184

Main CLI Commands

Command	Handler	Description
render	renderCommand	Renders documents or projects. src/command/command.ts38
preview	previewCommand	Live preview with hot-reloading. src/command/command.ts39
serve	serveCommand	Serves projects over HTTP. src/command/command.ts40
create	createCommand	Creates new projects or documents. src/command/command.ts41
run	runCommand	Runs TypeScript, R, Python, or Lua scripts. src/command/run/run.ts48-49
inspect	inspectCommand	Emits project/input metadata as JSON. src/command/inspect/cmd.ts16-24
publish	publishCommand	Deploys documents/projects to hosting providers. src/command/command.ts55

Initialization Flow

1. Monkey Patching: Deno globals are patched for compatibility. src/quarto.ts8-9
2. Reconfiguration: Checks if the installed dev config matches the source. src/quarto.ts73-83
3. Temp Directory: A session-specific temporary directory is initialized. src/quarto.ts191-192
4. Command Dispatch: cliffy parses the arguments and executes the registered action. src/quarto.ts194-195

Sources: src/quarto.ts122-218 src/command/command.ts35-63 src/command/inspect/cmd.ts16-24

---

Document Processing Pipeline

The processing pipeline is the sequence of transformations that turn source markdown into a final format. While detailed in child pages, the high-level flow involves:

• Metadata Resolution: Merging configuration from multiple levels (system, project, directory, file).
• Execution: Invoking engines like Jupyter to process code cells. The system can manage kernel lifecycles via executeKernelKeepalive for persistent sessions. src/execute/jupyter/jupyter-kernel.ts59-149
• AST Transformation: Using Pandoc with Quarto's Lua filters to manipulate the document structure.
• Post-processing: Final adjustments to the output (e.g., HTML dependency injection, PDF engine invocation).

For details, see Document Processing Pipeline.

---

Summary

Quarto CLI is a modular system that orchestrates complex document transformations by bridging high-level project management with low-level AST manipulation. It provides a type-safe, schema-driven environment for technical publishing while maintaining deep integration with computational data science ecosystems like Jupyter and Knitr.

Sources: src/quarto.ts1-60 README.md10-24 src/execute/jupyter/jupyter-kernel.ts34-57