This document provides a high-level introduction to the Quarto CLI codebase, explaining its purpose as a scientific and technical document rendering and publishing system. It outlines the major subsystems, their responsibilities, and how they interact to transform source documents (.qmd, .ipynb, .Rmd) into various output formats (HTML, PDF, presentations, manuscripts, websites, books).
For specific subsystem details, see: Schema System (#2), Execution Engines (#3), Pandoc Filters (#4), Format Generation (#5), Project Types (#6), Preview/Development (#7), and Testing (#8).
Quarto CLI is a command-line tool that orchestrates the conversion of computational documents into publishable outputs. It serves three primary functions:
Document Rendering: Executes code cells (via Jupyter, Knitr, or other engines), processes markdown through Pandoc's AST with custom Lua filters, and generates format-specific outputs (HTML, PDF, DOCX, presentations, etc.)
Project Management: Handles multi-document projects with specialized behavior for websites, books, and manuscripts, including navigation generation, search indexing, and cross-document references
Development Workflows: Provides live preview servers with hot-reloading for iterative authoring and development
The system is built around Pandoc as its core conversion engine, with Quarto adding computational execution, enhanced markdown features (callouts, cross-references, layouts), project organization, and format-specific enhancements.
Sources: src/command/render/render.ts1-583 src/command/render/pandoc.ts1-300 src/project/project-context.ts1-200
System Layers: Data Flow from Input to Output
The architecture follows a strict layered design where each layer depends only on layers below it. The Schema & Configuration Layer provides type-safe configuration validated at multiple stages (TypeScript compile-time, JSON Schema at build-time, Zod at runtime). The Execution Layer handles computational code via pluggable engines (Jupyter for Python/Julia/R, Knitr for R, or Markdown for static content). The Processing Core transforms the document AST through Pandoc with custom Lua filters that implement cross-references, layouts, and format-specific features. Format Renderers generate output-specific files with post-processing for dependencies and styling. The Interactive Development layer provides real-time preview with intelligent change detection.
Sources: src/project/project-context.ts139-567 src/execute/engine.ts src/command/render/pandoc.ts308-1200 src/format/html/format-html.ts src/command/preview/preview.ts146-700
Key Components: Functions and Classes that Coordinate the System
This map shows the critical function call paths through the system. renderCommand() and previewCommand() serve as entry points that invoke render() from render-shared.ts. The projectContext() function loads and validates configuration, while renderFiles() orchestrates per-file execution and Pandoc processing. fileExecutionEngine() selects the appropriate execution engine (Jupyter/Knitr/Markdown), and runPandoc() invokes Pandoc with Lua filters. Format-specific extras add post-processors like bootstrapHtmlPostprocessor(), and outputRecipe.complete() finalizes the output.
Sources: src/command/render/cmd.ts src/command/render/render-shared.ts src/command/render/render-files.ts src/execute/engine.ts src/command/render/pandoc.ts308-1200 src/format/html/format-html-bootstrap.ts
The CLI provides four primary commands implemented in separate modules:
| Command | Module | Primary Function | Key Entry Point |
|---|---|---|---|
render | src/command/render/cmd.ts | Render documents or projects | renderCommand |
preview | src/command/preview/cmd.ts | Live preview with hot-reload | previewCommand |
serve | src/command/serve/cmd.ts | Execute and serve interactive documents | serve() |
publish | Not shown | Deploy to hosting services | Not covered here |
All commands parse flags through parseRenderFlags() src/command/render/flags.ts36-500 which extracts options like --to, --output, --execute, --cache, etc. These flags are passed to the rendering pipeline as RenderOptions objects.
Sources: src/command/render/cmd.ts23-120 src/command/preview/cmd.ts58-200 src/command/serve/cmd.ts1-95 src/command/render/flags.ts36-500
The configuration system uses YAML schemas as the single source of truth, generating TypeScript types, JSON schemas, and Zod validators. This provides three-tier validation: compile-time (TypeScript), build-time (JSON Schema), and runtime (Zod).
Schema Type Generation Pipeline
The Format interface src/config/types.ts407-650 is the central data structure containing:
identifier: Format metadata (target-format, base-format, display-name)execute: Execution options (cache, freeze, eval, echo, enabled)render: Render options (keep-md, output-divs, fig-align)pandoc: Pandoc options (to, from, standalone, filters)metadata: Document metadata passed to Pandoc templateslanguage: Localization strings (via _language-*.yml files)formatExtras: Callback function returning FormatExtras objectConfiguration precedence (highest to lowest):
--to, --output, --metadata)_quarto.yml in project root)_quarto-{profile}.yml when profile active)src/format/formats.ts)The mergeConfigs() function src/core/config.ts handles merging with special array behavior: arrays are concatenated rather than replaced, allowing additive configuration at multiple levels.
Sources: src/resources/schema/definitions.yml src/resources/editor/tools/yaml/yaml-intelligence-resources.json src/config/types.ts407-650 src/config/metadata.ts src/core/schema/validated-yaml.ts src/project/project-context.ts186-273
The execution layer runs computational code and embeds results into markdown. The system uses a discovery pattern where engines declare their capabilities via the ExecutionEngine interface.
| Engine | Claim Method | Primary Module | Server Component |
|---|---|---|---|
| Jupyter | claimsFile() checks .ipynb or kernelspec metadata | src/execute/jupyter/jupyter.ts | src/execute/jupyter/jupyter.py ExecuteHandler |
| Knitr | claimsFile() checks .Rmd or R code blocks | src/execute/knitr/knitr.ts | Inter-process R via src/resources/rmd/rmd.R |
| Markdown | Default fallback (no execution) | src/execute/markdown.ts | N/A |
Execution Engine Selection and Invocation
The fileExecutionEngine() function src/execute/engine.ts implements the discovery pattern:
engine.claimsFile(file, metadata) on each engine in order.qmd files: Check for code cells with engine-specific languages.ipynb files: Always use Jupyter engine.Rmd files: Always use Knitr engineJupyter execution has two modes controlled by the execute.daemon option:
daemon: true): Kernel persists across renders with daemon-restart intervalThe Python server src/execute/jupyter/jupyter.py implements the ExecuteHandler class that communicates via TCP sockets (or Unix sockets on Linux/macOS), using nbclient for notebook execution and kernel management.
Knitr execution uses R inter-process communication through rmd.R src/resources/rmd/rmd.R which sets up hooks via hooks.R src/resources/rmd/hooks.R and patches knitr via patch.R src/resources/rmd/patch.R to capture outputs in Quarto-compatible formats.
Sources: src/execute/engine.ts src/execute/jupyter/jupyter.ts src/execute/knitr/knitr.ts src/execute/jupyter/jupyter.py src/resources/rmd/rmd.R src/resources/rmd/hooks.R
The rendering pipeline transforms executed markdown through Pandoc with custom Lua filters. Quarto uses a single Pandoc invocation with a sophisticated filter chain rather than multiple separate passes.
Pandoc Execution Pipeline
Key Pipeline Stages:
Filter Parameter Collection src/command/render/filters.ts128-201:
filterParamsJson() aggregates parameters from format, project, and executionQUARTO_FILTER_PARAMS environment variablePandoc Defaults Generation src/command/render/defaults.ts77-250:
generateDefaults() creates a YAML defaults file with all Pandoc optionsquarto-defaults-{uuid}.ymlPandoc Invocation src/command/render/pandoc.ts308-800:
pandoc +RTS -K512m -RTS --defaults <file>QUARTO_FILTER_PARAMS, LUA_CPATH, trace flagsLua Filter Chain src/resources/filters/main.lua:
main.lua orchestrates 15+ filter stages in specific orderFloatRefTarget for figures/tables, Callout for calloutsHTML Post-Processing src/format/html/format-html-bootstrap.ts277-500:
bootstrapHtmlPostprocessor() operates on parsed HTML DOMcodeToolsPostprocessor() adds code folding and source downloadkatexPostProcessor() processes KaTeX math expressionsOutput Recipe Completion src/command/render/output.ts58-200:
latexmk for PDF)renderCleanup() to remove intermediate filesSources: src/command/render/pandoc.ts308-1200 src/command/render/filters.ts128-201 src/command/render/defaults.ts77-250 src/resources/filters/main.lua src/format/html/format-html-bootstrap.ts277-500 src/command/render/codetools.ts
Projects organize multiple documents with shared configuration. The ProjectContext object src/project/types.ts86-180 provides:
| Field | Type | Purpose |
|---|---|---|
dir | string | Absolute path to project root |
config | ProjectConfig | Merged configuration from _quarto.yml |
files | { input, resources, config } | Categorized file lists |
engines | string[] | Required execution engines |
isSingleFile | boolean | Single-file vs multi-file project |
formatExtras | Function | Hook for project-wide format processing |
Project types src/project/types/project-types.ts define specialized behaviors:
Project rendering (renderProject() src/command/render/project.ts243-700) executes lifecycle hooks:
Sources: src/project/project-context.ts139-567 src/project/types.ts86-180 src/project/types/project-types.ts src/command/render/project.ts243-700
Formats define output specifications and processing hooks. The format registry src/format/formats.ts maps format identifiers to Format objects created by format-specific modules.
Format Architecture and Extension Points
Major Format Families:
| Format Family | Base Formats | Primary Module | Key Features |
|---|---|---|---|
| HTML | html, html4, html5 | src/format/html/format-html.ts | Bootstrap 5.2, SCSS themes, responsive figures, code tools |
| Presentations | revealjs, beamer, pptx | src/format/reveal/format-reveal.ts | Slide structure, RevealJS plugins, auto-animate, themes |
pdf, latex, beamer | src/format/pdf/format-pdf.ts | LaTeX via latexmk, Typst 0.10, TinyTeX support | |
| Documents | docx, odt, rtf | src/format/docx/format-docx.ts | Reference documents, track changes, custom styles |
| Markdown | gfm, commonmark, hugo-md | src/format/markdown/ | YAML preservation, shortcode escaping, front matter |
Format Detection Functions src/config/format.ts10-177:
isHtmlOutput(format): Returns true for HTML, EPUB, or HTML-based slidesisPdfOutput(format): Returns true for PDF or beamerisLatexOutput(format): Returns true for PDF, LaTeX, or beamerisTypstOutput(format): Returns true for Typst formatisMarkdownOutput(format): Returns true for markdown variantsFormatExtras Callback src/config/types.ts378-450:
The formatExtras callback allows formats to inject additional processing:
HTML formats use bootstrapExtras() src/format/html/format-html-bootstrap.ts117-220 to inject:
Sources: src/format/formats.ts src/config/format.ts10-177 src/format/html/format-html.ts src/format/html/format-html-bootstrap.ts117-220 src/format/reveal/format-reveal.ts src/format/pdf/format-pdf.ts src/config/types.ts378-450
The preview system provides live development with WebSocket-based automatic reloading and intelligent change detection.
Interactive Development Architecture
Key Components:
Initial Render src/command/preview/preview.ts414-492:
renderForPreview() performs initial document renderRenderResult with output path and supporting filesDev Server src/core/http-devserver.ts:
httpDevServer() starts HTTP server with WebSocket upgrade<script> tag for quarto-preview.js into HTML responsesFile Watching src/project/serve/watch.ts1-400:
watchProject() uses debounced file system watching_quarto.yml, _metadata.yml, extensionsRender Queue src/project/serve/serve.ts133-450:
Change Handlers:
Client Reload src/core/http-devserver.ts:
reloadClients() broadcasts WebSocket message to connected browsersreload (refresh page), navigate (change URL)Platform Detection:
X-Requested-With header, uses viewer paneSpecial Features:
previewRenderRequest() handles POST requests from IDEs for immediate renderexternal-preview scriptSources: src/command/preview/preview.ts146-700 src/command/preview/cmd.ts src/project/serve/serve.ts133-450 src/project/serve/watch.ts1-400 src/core/http-devserver.ts
Complete Document Processing Flow
End-to-end rendering involves these steps:
Context Initialization src/project/project-context.ts139-273:
_quarto.yml)--to flag or first format in configEngine Selection src/execute/engine.ts:
claimsFile() on each registered engine.qmd: Check for code cells with language kernels.ipynb: Always use Jupyter.Rmd: Always use KnitrExecution src/execute/types.ts:
Notebook Embedding src/core/jupyter/jupyter-embed.ts:
{{{< embed notebook.ipynb >}}} directivesPandoc Preparation src/command/render/pandoc.ts308-500:
filterParamsJson(): Collect all filter parametersgenerateDefaults(): Create Pandoc defaults fileresolveExtras(): Merge format and project extrasPandoc Execution src/command/render/pandoc.ts308-1200:
pandoc +RTS -K512m -RTS --defaults <file>QUARTO_FILTER_PARAMS with JSONPost-Processing:
latexmk or typst src/command/render/output-tex.ts src/command/render/output-typst.tsCleanup src/command/render/cleanup.ts:
keep-md, keep-tex, etc.)Sources: src/command/render/render.ts66-434 src/command/render/pandoc.ts308-1200 src/execute/engine.ts src/core/jupyter/jupyter-embed.ts src/command/render/output.ts58-200
Configuration uses mergeConfigs() src/core/config.ts with custom array merging: later configs override earlier ones, except arrays which concatenate. This enables additive configuration (e.g., adding filters at multiple levels).
Multiple subsystems use hook functions for extensibility:
preRender(), postRender(), formatExtras(), pandocRenderer()formatExtras() callbackexecute(), postprocess(), dependencies()Rather than multiple separate Pandoc invocations, Quarto uses a single Pandoc execution with a sophisticated Lua filter chain. The main.lua filter coordinates multiple sub-filters, sharing state via global variables and the Pandoc AST metadata.
The RenderServices interface src/command/render/types.ts provides:
temp: Temporary file managementextension: Extension contextnotebook: Notebook contextcleanup: Cleanup registrationThis allows testing and alternative implementations without tight coupling.
The ProjectContext object serves as the execution context for all rendering operations, carrying configuration, file lists, and execution state. Even single-file renders create a minimal project context src/project/types/single-file/single-file.ts
Sources: src/core/config.ts src/project/types.ts1-200 src/command/render/types.ts1-300 src/project/types/single-file/single-file.ts
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.