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/command.ts
• src/command/inspect/cmd.ts
• src/command/render/cleanup.ts
• src/command/render/cmd.ts
• src/command/render/filters.ts
• src/command/render/flags.ts
• src/command/render/output.ts
• src/command/render/pandoc.ts
• src/command/render/render.ts
• src/command/run/run.ts
• src/config/constants.ts
• src/config/format.ts
• src/config/metadata.ts
• src/config/types.ts
• src/core/console.ts
• src/core/lib/yaml-intelligence/paths.ts
• src/core/lib/yaml-intelligence/types.ts
• src/core/log.ts
• src/core/progress.ts
• src/dev_import_map.json
• src/format/formats-shared.ts
• src/format/formats.ts
• src/format/markdown/format-markdown.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/docs/smoke-all/2023/03/22/gha-toc-4917.qmd
• 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) 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.

Key capabilities include:

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

The system is implemented in TypeScript for the Deno runtime and orchestrates external binaries including Pandoc and Typst.

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 monkey-patching early in the lifecycle to enhance compatibility and path management.

Major Architectural Components

Component	Description	Code Location
CLI Entry Point	The main function quarto() responsible for CLI initialization, argument parsing, and command dispatch.	src/quarto.ts src/quarto.ts122-140
Command Registry	Collection of available CLI commands (render, preview, serve, etc.).	src/command/command.ts src/command/command.ts35-63
Project System	Manages different project types such as websites, books, and extensions for shared configuration and rendering.	src/project/types/register.ts src/quarto.ts49-50
Language Handlers	Engine discovery and management for computational languages (Python, R, Julia).	src/core/handlers/handlers.ts src/quarto.ts46-47
Format Registry	Registers output formats and rendering templates to support HTML, PDF, RevealJS, and others.	src/format/imports.ts src/quarto.ts52-53
Binary Passthrough	Direct invocation of bundled binaries like Pandoc and Typst when appropriate.	src/quarto.ts src/quarto.ts85-120
Execution Engines	Abstraction for computational code execution engines such as Jupyter, Knitr, and Observable JS.	src/execute/engine.ts src/command/render/render-files.ts37-38
Logging & Console	Multi-level logging, progress bars, and console output management.	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 src/command/render/render.ts69-72 src/command/render/pandoc.ts207

---

Mapping Natural Language Subsystems to Code Entities

This diagram illustrates the association between conceptual subsystems and key source code entities within Quarto CLI, helping bridge understanding from the domain vocabulary to the codebase.

Sources: src/quarto.ts122-126 src/command/command.ts35 src/command/run/run.ts14 src/core/log.ts49 src/command/render/pandoc.ts207 src/execute/engine.ts27-29 src/core/handlers/base.ts24-27

---

CLI Commands and Entry Points

Quarto CLI uses the cliffy framework for defining its command-line interface. The entry point is responsible for environment setup, validation of version requirements, and possible reconfiguration before dispatching to specific command handlers.

Main CLI Commands

Command	Handler	Description
render	renderCommand	Renders documents or projects to specified output formats.
preview	previewCommand	Provides live preview with hot-reloading during editing.
serve	serveCommand	Serves projects over HTTP for local testing and sharing.
create	createCommand	Helps create new projects or documents with templates.
run	runCommand	Runs code scripts (TypeScript, R, Python, Julia).
inspect	inspectCommand	Outputs metadata information for projects or files as JSON.

Initialization Flow

1. Monkey Patching: Patches Deno runtime globals for compatibility with Quarto features.
2. Reconfiguration: Detects and applies dev configuration changes to keep the system current.
3. Temporary Directory Setup: Creates an isolated temp directory for session use.
4. Argument Parsing: Delegates commands and arguments to appropriate handlers using cliffy.

For details, see CLI Commands and Entry Points.

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

---

Document Processing Pipeline

The document processing pipeline covers the end-to-end flow from raw input documents to their rendered outputs. The workflow includes computational execution, format recipe resolution, AST transformations, filtering via Lua, and final rendering.

Pipeline Stages

• Execution: Code chunks within documents are executed by engines corresponding to Python, R, Julia, and others. Execution results including outputs and metadata are produced. Caching and freeze mechanisms optimize repeated rendering.
• Recipe Resolution: The system determines output file paths, extensions, and any required post-processing steps (such as invoking LaTeX engines or Typst). This also manages how output is streamed or saved.
• Pandoc Invocation: Pandoc is the core document transformation engine, enhanced by Quarto-specific filters and metadata normalization. Quarto provides a custom Pandoc reader for .qmd files to preprocess content before AST parsing.
• Post-processing: Additional transformations such as embedding notebook artifacts, injecting dependencies, and applying code tools are applied after Pandoc finishes.

For details, see Document Processing Pipeline.

Sources: src/command/render/render-files.ts122-215 src/command/render/output.ts58-100 src/command/render/pandoc.ts207

---

Summary

Quarto CLI delivers a modular, extensible platform for scientific and technical document publishing. Its architecture bridges declarative project management, computational code execution, and complex document rendering built on a robust integration with Pandoc and other tooling. This modular design facilitates advanced publishing workflows with support for custom filters, engines, and output formats.

Sources: src/quarto.ts1-60 README.md10-24