Overview and Architecture

Relevant source files

• .gitignore
• README.md
• src/command/create-project/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/freeze.ts
• src/command/render/output.ts
• src/command/render/pandoc.ts
• src/command/render/project.ts
• src/command/render/render.ts
• src/config/constants.ts
• src/config/format.ts
• src/config/metadata.ts
• src/config/pdf.ts
• src/config/types.ts
• src/core/log.ts
• src/core/pandoc/pandoc-id.ts
• src/core/path.ts
• src/core/uuid.ts
• src/format/formats-shared.ts
• src/format/formats.ts
• src/format/markdown/format-markdown.ts
• src/inspect/inspect-types.ts
• src/inspect/inspect.ts
• src/project/project-context.ts
• src/project/project-create.ts
• src/project/project-gitignore.ts
• src/project/project-resources.ts
• src/project/project-shared.ts
• src/project/types.ts
• src/project/types/project-default.ts
• src/project/types/project-types.ts
• src/project/types/single-file/single-file.ts
• src/project/types/types.ts
• src/project/types/website/website.ts
• src/quarto.ts
• tests/docs/inspect/website-with-extensions/extension-test/.gitignore
• tests/docs/inspect/website-with-extensions/extension-test/_extensions/gadenbuie/auto-dark/LICENSE
• tests/docs/inspect/website-with-extensions/extension-test/_extensions/gadenbuie/auto-dark/_extension.yml
• tests/docs/smoke-all/2023/03/22/gha-toc-4917.qmd
• tests/unit/project/file-information-cache.test.ts
• tests/unit/project/utils.ts

Purpose and Scope

This page provides a high-level introduction to Quarto CLI's architecture and its major subsystems. It explains how the system is organized into layers, how components interact, and the primary execution flows. For detailed information about specific subsystems, see:

• Schema and Configuration: Schema and Configuration System
• Document Execution: Document Execution
• Pandoc Filters: Pandoc Filter System
• Format Generation: Format Generation
• Project System: Project System

What is Quarto CLI

Quarto CLI is a scientific and technical publishing system that converts computational documents (.qmd, .ipynb, .Rmd, .md) into various output formats (HTML, PDF, DOCX, presentations, etc.). It is built on Pandoc and written primarily in TypeScript, running on Deno.

The system orchestrates multiple subsystems to:

1. Parse and validate document configuration
2. Execute computational code (Python, R, Julia)
3. Transform content through Pandoc with custom Lua filters
4. Generate format-specific output with post-processing
5. Manage multi-document projects (websites, books, manuscripts)

Sources: README.md1-30 src/quarto.ts1-240

High-Level Architecture

The following diagram shows the major architectural layers and how they interact, using actual code entities from the codebase:

Sources: src/quarto.ts122-240 src/command/render/cmd.ts23-28 src/command/render/render.ts66-434 src/project/project-context.ts139-573

Core Type Definitions

The system is built around several key TypeScript interfaces that define the data structures flowing through the pipeline:

ProjectContext

The ProjectContext interface (src/project/types.ts54-115) is the central data structure for project-level operations:

Field	Type	Purpose
dir	string	Project root directory
config	ProjectConfig	Merged configuration from _quarto.yml and profiles
files	ProjectFiles	Input files, resources, config files
engines	string[]	Execution engines used in the project
fileMetadata()	function	Resolves metadata for a specific file
formatExtras()	function	Project-level format customization
environment()	function	Execution environment configuration

Format

The Format interface (src/config/types.ts421-457) represents a resolved output format:

Field	Type	Purpose
identifier	FormatIdentifier	Format name and variants
pandoc	FormatPandoc	Pandoc-specific options (to, from, template, etc.)
execute	FormatExecute	Execution options (cache, eval, echo, etc.)
render	FormatRender	Render options (keep-tex, keep-md, etc.)
metadata	Metadata	Document metadata
formatExtras()	function	Format-specific processing hooks

RenderContext

The RenderContext interface (defined in src/command/render/types.ts) contains all state for rendering a single document:

• target: Input file information (source, input, markdown)
• format: Resolved Format object
• options: CLI flags and render options
• project: Optional ProjectContext
• engine: Execution engine instance
• libDir: Library directory for dependencies

Sources: src/project/types.ts54-115 src/config/types.ts421-457 src/command/render/types.ts1-100

Command Execution Flow

The following diagram shows how CLI commands flow to their handlers with specific function references:

Command Registration

Commands are registered in src/command/command.ts and imported by the main CLI. Each command is a Cliffy Command instance:

• renderCommand: Defined in src/command/render/cmd.ts23-159
• previewCommand: Defined in src/command/preview/cmd.ts
• Other commands: create, convert, inspect, run, check, install, publish, etc.

The main execution flow in quarto() (src/quarto.ts122-217):

1. Check for version requirements and reconfiguration needs
2. Handle special pass-through commands (pandoc, typst, run)
3. Parse arguments with Cliffy
4. Initialize session temp directory (src/core/temp.ts)
5. Execute command action
6. Cleanup and exit

Sources: src/quarto.ts122-217 src/command/render/cmd.ts23-159 src/command/command.ts1-50

Document Rendering Pipeline

The document rendering pipeline is the core flow for transforming input documents to output formats:

Key Pipeline Functions

render() (src/command/render/render-shared.ts)
Top-level render orchestrator. Determines if rendering a single file or project, resolves formats, and coordinates execution.

renderFiles() (src/command/render/render-files.ts)
Renders multiple files, handling parallel execution, progress reporting, and dependency tracking.

renderPandoc() (src/command/render/render.ts66-434)
Core function that:

1. Merges execution results into format configuration
2. Processes notebook placeholders
3. Constructs PandocOptions
4. Calls runPandoc()
5. Executes HTML post-processors
6. Handles self-contained output
7. Returns PandocRenderCompletion

runPandoc() (src/command/render/pandoc.ts309-1265)
Executes Pandoc with:

1. Format defaults generation (src/command/render/defaults.ts)
2. Filter parameter construction (src/command/render/filters.ts)
3. Template staging
4. Pandoc process execution via execProcess()
5. Collection of post-processors and finalizers

Sources: src/command/render/render.ts66-434 src/command/render/pandoc.ts309-1265 src/command/render/render-shared.ts1-200

Project vs Single-File Rendering

Quarto handles two rendering modes with distinct code paths:

Project Rendering

When a ProjectContext exists, rendering goes through src/command/render/project.ts242-701:

1. Pre-render scripts: Execute project.pre-render scripts (src/command/render/project.ts309-367)
2. Project type hooks: Call ProjectType.preRender() (src/project/types/types.ts35-42)
3. Supplemental files: Add files via ProjectType.supplementRender() (e.g., listing pages)
4. Render files: Call renderFiles() for all input files
5. Output relocation: Move files to output-dir (src/command/render/project.ts496-700)
6. Post-processing: Call ProjectType.postRender() and project.post-render scripts

Single-File Rendering

For standalone files (src/command/render/render-shared.ts)):

1. No project context or pre/post render hooks
2. Direct call to renderFiles() with single file
3. Output remains in source directory (unless --output-dir specified)
4. Simpler cleanup and resource management

Sources: src/command/render/project.ts242-701 src/command/render/render-shared.ts1-200

Configuration Resolution

Configuration is resolved through multiple layers with specific precedence:

Key configuration constants are defined in src/config/constants.ts1-800:

• kMetadataFormat: "format" key for output format specification
• kProjectType: "type" key for project type
• kProjectOutputDir: "output-dir" key
• Execution defaults: kExecuteEnabled, kCache, kFreeze, kEval, kEcho
• Render defaults: kKeepMd, kKeepTex, kCodeFold, kFigAlign
• Pandoc defaults: kTo, kFrom, kTemplate, kToc, kNumberSections

Sources: src/config/constants.ts1-800 src/project/project-context.ts139-573 src/command/render/render-contexts.ts

Extension System Integration

Extensions integrate at multiple points:

1. Extension discovery (src/extension/extension.ts): Searches for extensions in _extensions/ directories
2. Project type extensions: Custom project types (e.g., dashboard, custom project templates)
3. Format extensions: Custom formats with templates, filters, and resources
4. Filter extensions: Additional Lua filters injected into the pipeline
5. Shortcode extensions: Custom shortcode handlers

Extensions contribute via the Extension interface:

• contributes.project: Project configuration
• contributes.formats: Format definitions
• contributes.filters: Lua filter paths
• contributes.shortcodes: Shortcode definitions

Sources: src/extension/extension.ts1-500 src/project/project-context.ts219-225

Key Entry Points Summary

Entry Point	Location	Purpose
quarto()	src/quarto.ts122-217	Main CLI entry point
render()	src/command/render/render-shared.ts	Top-level render orchestrator
renderProject()	src/command/render/project.ts242-701	Project rendering with hooks
renderFiles()	src/command/render/render-files.ts	Multi-file rendering
runPandoc()	src/command/render/pandoc.ts309-1265	Pandoc execution
projectContext()	src/project/project-context.ts139-573	Project context resolution
executionEngine()	src/execute/engine.ts	Engine resolution
serveProject()	src/command/preview/preview.ts	Preview server

Sources: src/quarto.ts1-240 src/command/render/pandoc.ts1-1265 src/project/project-context.ts1-1000