DOCSEARCHbyAlgolia
Submit Docs

Quarto CLI Documentation

repository·main·Indexed 26 days ago

https://github.com/quarto-dev/quarto-cli

Documentation for Quarto, an open-source scientific and technical publishing system built on Pandoc. It supports integrating executable code from Python, R, Julia, and JS into Markdown for reports, websites, and books. Includes guides on using the CLI for publishing to Netlify, GitHub Pages, and Posit Connect, implementing custom execution engines using @quarto/types, and managing project extensions and templates.

Tokens
61.7K
Snippets
158
Records
473
Agent score
91%

What's inside Quarto CLI

  1. Overview of Code Signing for Quarto Installers

    main

    Quarto installers are code-signed and (on macOS) notarized during the official Build Installers workflow (triggered via create-release.yml).

    Signing is reserved for official releases. Local builds using quarto-bld will skip the signing process if the required environment variables or secrets are missing.

    Key behaviors:

    • macOS: If the Application Developer Id is missing, the build will print warning: Missing Application Developer Id, not signing and proceed without signing.
    • Windows: The signing step is gated by repository secrets that are only resolvable by the Apple keychain action and DigiCert smctl during official release workflows.

  2. Overview of Quarto

    main

    Quarto is an open-source scientific and technical publishing system built on Pandoc. It allows authors to write in Markdown and embed code/output from Python, R, Julia, and JavaScript via Jupyter, Knitr, and Observable.

    Key features include:

    • Extensions for technical writing (cross-references, callouts, layout panels, etc.).
    • A project system for rendering websites and books.
    • Support for editors like VS Code, JupyterLab, and RStudio.
    • A visual Markdown editor for long-form composition.

  3. Understand Quarto's LaTeX Template Structure

    main

    Quarto uses a modular LaTeX template system that combines original Pandoc templates with Quarto-specific partials. This allows for extended functionality like author normalization and advanced bibliography control while maintaining compatibility with Pandoc.

    File Extension Convention

    • .tex files: Quarto-maintained partials (e.g., title.tex, toc.tex).
    • .latex files: Pandoc-derived partials (e.g., hypersetup.latex, fonts.latex).

    The Orchestrator

    Unlike Pandoc which uses default.latex, Quarto uses template.tex as the main orchestrator. This file assembles the document by including all Quarto and Pandoc partials in a specific order.

  4. Understand the Revealjs Format Architecture

    main
    Quarto configures reveal.js presentations through a three-stage pipeline that manages metadata normalization, default value assignment, and post-processing. This architecture ensures that user-facing YAML configuration is correctly transformed into the specific JavaScript types required by the reveal.js library, overcoming Pandoc's text-only template limitations.

  5. Understand the Sass Bundle Structure and Compilation Order

    main

    Quarto uses a layered SassBundle system. Each bundle consists of five layers compiled in a specific order to manage dependencies and variable overrides.

    Layer Types (in order):

    1. uses: @use directives for Sass modules
    2. functions: Sass functions
    3. defaults: Variables with the !default flag
    4. mixins: Reusable Sass mixins
    5. rules: CSS rules and selectors

    Compilation Order for Layers:

    • uses: framework $\rightarrow$ quarto $\rightarrow$ user
    • functions: framework $\rightarrow$ quarto $\rightarrow$ user
    • defaults: user $\rightarrow$ quarto (REVERSED) $\rightarrow$ framework (REVERSED). Note: User defaults are placed first so they take priority via the !default mechanism.
    • mixins: framework $\rightarrow$ quarto $\rightarrow$ user
    • rules: framework $\rightarrow$ quarto $\rightarrow$ user

  6. Understand the Axe Accessibility Checking Architecture

    main

    Quarto's axe-core integration is implemented across three distinct layers to handle different output formats (HTML, RevealJS, and Dashboard):

    1. Build-time (TypeScript): Detects the output format and injects axe-check.js and axe-check.css as FormatDependency. It encodes configuration options as base64 JSON into a <script> tag to prevent HTML parsing errors.
    2. Compile-time (SCSS): Provides format-specific styling. For RevealJS, it uses a CSS custom property bridge (--quarto-axe-*) to access theme variables since RevealJS compiles sass-bundles separately.
    3. Runtime (JavaScript): A single file (axe-check.js) performs DOM inspection to identify the format and orchestrates scanning via the QuartoAxeChecker class. It supports various reporters like QuartoAxeDocumentReporter (DOM overlays), QuartoAxeConsoleReporter (console logs), and QuartoAxeJsonReporter (JSON output).

  7. Understand Quarto Preview Routing

    main

    The quarto preview command uses a state machine to determine the preview mode based on the input provided. The routing depends on whether the input is a file or a directory, and whether that file belongs to a serveable project.

    • Single-File Preview (Path A): Used when the file is not part of a serveable project. It uses the preview() function.
    • Project Preview (Paths B/D): If the file is part of a project or the input is a directory, Quarto switches to a project-wide preview using serveProject(). This provides full project navigation in the browser.
    • Shiny Preview (Path C): If a Shiny document is detected, it uses previewShiny() or serve() and exits the standard routing.
    quarto preview [input]
       │
       ▼
   isFile(input)?
   ├── YES ──► Create ProjectContext, detect format
   │           ├── Shiny? ──► previewShiny() / serve() ──► EXIT (Path C)
   │           ├── Serveable project, file NOT in inputs?
   │           │   └── .md + external previewer ──► file = project.dir (Path B1)
   │           ├── Serveable project, file IN inputs?
   │           │   └── HTML/serve output ──► renderProject() then file = project.dir (Path B2)
   │           └── None of above ──► file stays as-is (Path A)
   │
   └── NO (directory) ──► straight to isDirectory check (Path D)
       │
       ▼
   isDirectory(file)?  ← file may have been mutated above
   ├── YES ──► serveProject(projectTarget, ...) ← projectTarget may be ProjectContext
   └── NO  ──► preview(file, ..., project)      ← single-file preview

  8. Understand HTML Callout Styling Architecture

    main

    Quarto employs a three-tier architecture for styling callouts in HTML-based outputs. The tier selected depends on your output format:

    1. Bootstrap HTML (html with themes): Provides full theming, collapsible sections, and dark mode support. Uses formats/html/bootstrap/_bootstrap-rules.scss.
    2. RevealJS (revealjs): Optimized for presentations with slide-aware scaling and background awareness. Uses formats/revealjs/quarto.scss.
    3. Standalone HTML (epub, gfm, plain html): Uses inline CSS and base64-encoded PNG icons for zero-dependency portability. Uses formats/html/styles-callout.html.

    All HTML callouts support three appearance modes:

    • default: Full-featured with a colored header background.
    • simple: Lightweight with only a left border.
    • minimal: Equivalent to simple but with the icon suppressed (icon=false).

  9. Use extension scripts for external packaging

    main

    The scripts located in the package/src/ext/ directory are designed for use by external package managers (such as Conda).

    These scripts facilitate a packaging process that includes only the minimal Quarto files, excluding any vendored dependencies. This process does not create standalone packages; instead, it places files into a user-specified location so that an external packaging tool can bundle them.

  10. Understand the Quarto qmd Custom Reader architecture

    main

    Quarto does not use Pandoc's standard Markdown reader directly. Instead, it uses a custom Pandoc reader written in Lua (readqmd.lua). This reader is the only stage in the pipeline that processes raw document text before it is parsed into a Pandoc AST.

    If you need to influence how Pandoc parses the document (rather than how the resulting AST is transformed), you must implement logic at this pre-parse stage. The pipeline flow is:

    1. Raw .qmd text
    2. qmd custom reader (performs raw-text transforms, then calls pandoc.read)
    3. Pandoc AST
    4. Filter pipeline (INIT → NORMALIZE → PRE → CROSSREF, etc.)

  12. Understand the Quarto Publishing Architecture

    main
    Quarto uses a provider-based architecture for the quarto publish command. Each deployment target (e.g., Netlify, Posit Connect, quarto-pub) implements a PublishProvider interface. The publishing process follows a standard flow: resolving the deployment target from _publish.yml, selecting a provider, resolving credentials (via environment variables, stored tokens, or interactive auth), and executing the upload using one of two patterns: file-by-file upload or bundle upload.