Overview and Architecture

Relevant source files

• .gitignore
• README.md
• src/command/command.ts
• src/command/render/cmd.ts
• src/command/render/filters.ts
• src/command/render/flags.ts
• src/command/render/freeze.ts
• src/command/render/output.ts
• src/command/render/pandoc.ts
• src/command/render/project.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/pdf.ts
• src/config/types.ts
• src/core/jupyter/display-data.ts
• src/core/jupyter/jupyter.ts
• src/core/jupyter/labels.ts
• src/core/jupyter/preserve.ts
• src/core/jupyter/tags.ts
• src/core/jupyter/widgets.ts
• src/core/log.ts
• src/core/path.ts
• src/execute/engine.ts
• src/execute/jupyter/jupyter.ts
• src/execute/markdown.ts
• src/execute/rmd.ts
• src/execute/types.ts
• src/format/formats-shared.ts
• src/format/formats.ts
• src/format/markdown/format-markdown.ts
• src/project/project-resources.ts
• src/project/types/types.ts
• src/quarto.ts
• src/resources/rmd/execute.R
• src/resources/rmd/hooks.R
• src/resources/rmd/patch.R
• src/resources/rmd/rmd.R
• src/resources/schema/cell-table.yml
• tests/docs/smoke-all/2023/03/22/gha-toc-4917.qmd
• tests/docs/smoke-all/2023/09/29/filter.lua
• tests/docs/smoke-all/2023/09/29/test.js
• tests/docs/smoke-all/2023/09/29/test.qmd
• tests/docs/smoke-all/2023/10/10/issue-7187-jupyter.qmd
• tests/docs/smoke-all/2023/10/10/issue-7187-knitr.qmd

Purpose and Scope

This page provides a high-level overview of the Quarto CLI architecture, explaining its purpose as a document processing and publishing system and describing how major components interact to transform computational documents into various output formats.

For detailed information about specific subsystems, see:

• Execution engine details: Document Execution
• Rendering pipeline specifics: Document Processing Pipeline
• Schema and configuration: Schema and Configuration System
• Project types and structure: Project Types

Sources:

• src/command/render/render.ts1-70
• src/command/render/pandoc.ts1-50

System Overview

Quarto is a scientific publishing system that transforms computational documents (.qmd, .ipynb, .Rmd) into publishable outputs (HTML, PDF, DOCX, presentations, books, and websites). The system is built around a layered architecture with clear separation of concerns:

Architectural Layers:

Core Design Principles:

1. Type Safety: YAML schemas generate TypeScript types and Zod validators for compile-time and runtime validation
2. Extensibility: Lua filters, custom formats, and project types allow deep customization
3. Multi-Engine: Supports multiple execution engines (Jupyter, Knitr) with a common interface
4. Format Agnostic: Single source can render to multiple output formats (HTML, PDF, Word, etc.)
5. Project-Aware: First-class support for multi-document projects with navigation, cross-references, and search

The system's modularity allows components to be developed, tested, and understood independently while maintaining clear interfaces between layers.

Sources:

• src/command/render/render.ts1-434
• src/command/render/pandoc.ts308-1200
• src/execute/engine.ts40-100
• src/config/types.ts1-400
• src/project/types.ts1-100

Core Components and Their Interactions

This diagram shows the main code entities and how they interact during a typical render operation:

Key Component Interfaces:

Component	Key Methods/Properties	Responsibility
ProjectContext	dir, config, files, engines	Holds project-level configuration and file lists
ExecutionEngineInstance	.execute(), .dependencies(), .postprocess()	Runs code and produces markdown output
Format	pandoc, render, execute, metadata, formatExtras()	Defines all aspects of output format configuration
ExecuteResult	markdown, includes, metadata, supporting	Contains all outputs from code execution
PandocOptions	source, format, markdown, args, metadata	Packages all inputs needed for pandoc execution
RenderedFile	input, file, format, supporting, resourceFiles	Describes a single rendered output file
RenderResult	files[], context, baseDir, outputDir	Aggregates results from rendering operation

Sources:

• src/command/render/cmd.ts1-150
• src/command/render/render-shared.ts1-100
• src/command/render/render.ts66-434
• src/command/render/pandoc.ts308-1200
• src/project/project-context.ts1-300
• src/execute/engine.ts80-300
• src/config/metadata.ts1-200

Document Processing Pipeline

This diagram shows the concrete functions and data structures involved in transforming a source document to output:

Pipeline Stages:

Stage	Key Functions	Input	Output
Engine Selection	fileExecutionEngine()	File path + extension	ExecutionEngineInstance
Target Creation	engine.target()	File path + markdown	ExecutionTarget with kernelspec
Code Execution	engine.execute()	ExecutionTarget + Format	ExecuteResult with markdown
Format Resolution	metadataAsFormat()	Metadata + format name	Format object
Pandoc Prep	generateDefaults(), filterParamsJson()	Format + ExecuteResult	Pandoc defaults + env vars
Pandoc Execution	execProcess() with pandocBinaryPath()	Markdown + defaults + filters	Raw output file
Post-Processing	htmlPostprocessors[]	Output HTML	Modified HTML with dependencies
Finalization	recipe.complete()	Output + supporting files	RenderedFile

Sources:

• src/command/render/render.ts66-434
• src/command/render/pandoc.ts308-1200
• src/execute/engine.ts150-400
• src/execute/jupyter/jupyter-kernel.ts1-100
• src/resources/rmd/execute.R1-50
• src/config/metadata.ts1-300
• src/command/render/filters.ts128-200
• src/command/render/defaults.ts1-100

Execution Engine Architecture

The execution engine system uses a discovery pattern where each engine declares what file types and languages it handles.

Key Interfaces:

Engine Discovery Flow:

Step	Function	Location	Behavior
1. Registration	executionEngines	engine.ts50-100	Returns array of all available engines
2. File Claim	fileExecutionEngine()	engine.ts200-250	Checks each engine's claimsFile() method
3. Language Claim	claimsLanguage()	Engine implementations	Jupyter claims "julia", Knitr claims "r"
4. Instance Launch	engine.launch()	jupyter.ts300-400 rmd.ts100-200	Creates engine instance with project context
5. Execution	instance.execute()	Engine instance	Runs code, returns ExecuteResult

Engine Implementations:

• Jupyter Engine (kJupyterEngine): Manages Python server at execute/jupyter/jupyter.ts100-500 communicates via WebSocket, handles kernelspecs
• Knitr Engine (kKnitrEngine): Spawns R process at execute/rmd.ts100-300 uses hooks from resources/rmd/hooks.R1-500
• Markdown Engine (kMarkdownEngine): No-op execution for static markdown at execute/markdown.ts

Sources:

• src/execute/engine.ts1-400
• src/execute/jupyter/jupyter.ts1-200
• src/execute/rmd.ts1-150
• src/execute/types.ts1-100

Schema and Type Safety System

Quarto uses a schema-driven configuration system that generates TypeScript types, JSON schemas, and Zod validators from YAML definitions.

Schema Pipeline:

Stage	Input	Output	Location
Definition	YAML schema files	Schema objects	resources/schema/definitions.yml
TS Generation	Schema objects	TypeScript interfaces	Generated schema-types.ts
Zod Generation	Schema objects	Runtime validators	Generated zod/schema-types.ts
JSON Schema	Schema objects	JSON Schema	json-schemas.json
Intelligence	Schema + docs	Editor completions	yaml-intelligence-resources.json

Configuration Hierarchy:

Key Configuration Constants:

Configuration keys are defined in config/constants.ts1-300 as exported constants:

• Format metadata: kMetadataFormat, kBaseFormat, kTargetFormat
• Execution: kEngine, kEval, kEcho, kOutput, kCache, kFreeze
• Rendering: kKeepMd, kKeepTex, kCodeFold, kFigAlign
• Project: kProjectType, kProjectOutputDir, kProjectLibDir

Configuration Resolution:

The metadataAsFormat() function at config/metadata.ts merges configuration from:

1. Format defaults from schema
2. Project-level _quarto.yml
3. Document-level YAML front matter
4. Cell-level options (for executable code)

Sources:

• src/resources/schema/definitions.yml1-200
• src/config/constants.ts1-300
• src/config/types.ts1-100
• src/resources/editor/tools/yaml/yaml-intelligence-resources.json1-100

Project System

The ProjectContext serves as the central coordination point for multi-document projects.

Project Context Structure:

Project Type Implementations:

Type	Constant	Implementation	Key Features
Website	kWebsite	website/website.ts	Navigation, search, listings, sitemap
Book	kBook	book/book.ts	Chapters, cross-references, single/multi-file
Default	kDefault	project-default.ts	Basic project with no special structure

Project Context Creation:

The projectContext() function at project-context.ts138-250 performs:

1. Directory Discovery: Walks up from input file looking for _quarto.yml
2. Config Resolution: Parses YAML with schema validation via readAndValidateYamlFromFile()
3. Profile Application: Applies active profiles via initializeProfileConfig()
4. Extension Loading: Loads and merges extension metadata via mergeExtensionMetadata()
5. Type Initialization: Calls projectType().create() for type-specific setup
6. Environment Setup: Loads .env files via dotenvSetVariables()

Project Rendering Flow:

The renderProject() function at render/project.ts1-300 orchestrates:

1. Pre-render scripts via kProjectPreRender configuration
2. Incremental or full rendering based on file changes
3. Format-specific rendering via renderFiles()
4. Post-render scripts via kProjectPostRender configuration
5. Resource copying and cleanup

Sources:

• src/project/types.ts1-100
• src/project/project-context.ts138-300
• src/command/render/project.ts1-150
• src/project/types/project-types.ts1-100

Format System

Formats define how documents are rendered and what features are available.

Format Resolution Process:

Format Structure:

The Format interface at config/types.ts100-300 contains:

• pandoc: Options passed directly to pandoc (output format, template, variables)
• render: Rendering behavior (kKeepMd, kKeepTex, kCodeFold, etc.)
• execute: Execution options (kEval, kEcho, kCache)
• language: Localization strings (kTocTitleDocument, kCalloutTipCaption)
• metadata: Additional metadata forwarded to output
• formatExtras: Function returning additional resources, filters, postprocessors

Built-in Formats:

Format	Base	Key Features	Implementation
html	HTML5	Bootstrap, grid layouts, code tools	format/html/
revealjs	HTML5	Slides, transitions, plugins	format/html/format-html-revealjs.ts
pdf	LaTeX	Academic typesetting, cross-refs	format/pdf/
docx	OpenXML	Word documents, reference doc	Pandoc built-in
typst	Typst	Modern typesetting	format/typst/
ipynb	Notebook	Jupyter notebook output	format/ipynb/

Format Extras Pattern:

Format extras allow formats to inject additional resources:

Extras are returned by the optional format.formatExtras() function, called at pandoc.ts525-573 and merged into the rendering pipeline.

Sources:

• src/config/types.ts100-400
• src/config/metadata.ts1-200
• src/command/render/pandoc.ts525-700
• src/config/format.ts1-150

Lua Filter Pipeline

Lua filters transform the Pandoc AST during rendering. Quarto's filter system is organized into phases.

Filter Registration:

The quartoFilters() function at render/filters.ts100-400 returns filter specifications:

Filter Phases:

Filters are organized by their at position (from resources/schema/definitions.yml40-55):

Phase	Timing	Purpose	Key Filters
pre-ast	Before AST loaded	Early transformation	User extensions
post-ast	After AST loaded	AST preprocessing	User extensions
pre-quarto	Before Quarto filters	Setup	User extensions
Quarto Filters	Main processing	Cross-refs, layouts, callouts	Built-in filters
post-quarto	After Quarto filters	Customization	User extensions
pre-render	Before pandoc write	Format prep	User extensions
post-render	After pandoc write	Post-processing	User extensions
citeproc	Citation processing	Bibliography	Pandoc built-in

Key Quarto Filters:

Filter parameters are built at filters.ts200-600 and passed via the QUARTO_FILTER_PARAMS environment variable:

• Crossref: Parameters from crossrefFilterParams() include crossref metadata, numbering options
• Layout: Parameters from layoutFilterParams() include figure/table layout settings
• Normalize: Table processing, AST standardization
• Callouts: Converts div notation to callouts
• Code Annotation: Processes code annotations

Filter Parameter Injection:

At pandoc.ts324-358 filter parameters are:

1. Collected from format metadata and options
2. Serialized to JSON
3. Base64-encoded
4. Set in QUARTO_FILTER_PARAMS environment variable
5. Decoded by Lua filters during execution

Sources:

• src/command/render/filters.ts1-600
• src/command/render/crossref.ts1-100
• src/command/render/layout.ts1-100
• src/resources/schema/definitions.yml30-60

Data Flow Summary

The complete rendering pipeline for a .qmd file:

1. CLI Invocation: User runs quarto render document.qmd
2. Project Discovery: projectContext() finds _quarto.yml and loads configuration
3. Engine Selection: fileExecutionEngine() selects Jupyter or Knitr based on metadata
4. Execution: Engine runs code, produces ExecuteResult with markdown and metadata
5. Format Resolution: metadataAsFormat() merges format configuration
6. Pandoc Setup: generateDefaults() creates pandoc defaults file
7. Filter Preparation: quartoFilters() builds filter chain and parameters
8. Pandoc Execution: runPandoc() invokes pandoc with filters
9. HTML Post-Processing: Postprocessors inject dependencies, fix layouts
10. Resource Copying: Output and supporting files moved to output directory
11. Result Packaging: RenderResult returned with file paths and metadata

Key Data Structures:

• ExecutionTarget: Input file info, metadata, engine selection
• ExecuteResult: Markdown output, metadata, includes, supporting files
• PandocOptions: All options needed for pandoc execution
• RunPandocResult: Pandoc output, postprocessors, resources
• RenderedFile: Final output path, supporting files, resources
• RenderResult: Collection of rendered files with project context

Sources:

• src/command/render/render.ts1-500
• src/command/render/pandoc.ts308-1000
• src/execute/types.ts1-200
• src/command/render/types.ts1-200