Quarto

Quarto is an open-source scientific and technical publishing system built on Pandoc.

Content authored using Quarto can be published to Posit Connect.

Installing Quarto

Follow the Quarto installation instructions to install Quarto before or after Connect.

Enabling Quarto support

The package-installed starter configuration enables Quarto support and scans versioned installations beneath /opt/quarto. Connect starts successfully when Quarto is enabled without a discovered installation.

If you used the Quarto Debian installer, Quarto is available at /usr/local/bin/quarto. Configure this installation explicitly:

/etc/rstudio-connect/rstudio-connect.gcfg
[Quarto]
Enabled = true
Executable = "/usr/local/bin/quarto"

If you installed using the Quarto .tar.gz or another method, you might have installed Quarto elsewhere. You can support multiple Quarto versions in this way, providing an Executable for each:

/etc/rstudio-connect/rstudio-connect.gcfg
[Quarto]
Enabled = true
Executable = "/opt/quarto/1.0.37/bin/quarto"
Executable = "/opt/quarto/1.1.189/bin/quarto"
Executable = "/opt/quarto/1.2.66/bin/quarto"
Note

Changing any of the Quarto configuration settings requires a restart of Posit Connect.

Quarto support is available when Quarto.Enabled is enabled and Connect discovers a Quarto installation. Connect fails to start when an explicitly configured Quarto.Executable is invalid.

A compatible version of Quarto is identified when content is deployed. That Quarto installation is used any time Quarto is needed for that content.

Quarto content may contain R and Python code chunks; when that content is deployed, compatible language versions are identified and used with Quarto anytime that content is run. Quarto support does not require R or Python installations, but content that uses these languages will succeed only if a compatible installation is available.

Scanning

Posit Connect can scan administrator-configured directories for Quarto installations and optionally use PATH.

  • Version scanning: Looking for Quarto in locations known to contain multiple version installations. Disabled by default.
  • Path scanning: Looking for Quarto using the PATH environment variable. Disabled by default, and only occurs if a Quarto location is not otherwise discovered or configured.

Each kind of scanning can be individually controlled. The following configuration snippet shows both scanning settings.

/etc/rstudio-connect/rstudio-connect.gcfg
[Quarto]
ExecutableVersionScanning = /opt/quarto
ExecutablePathScanning = false

Use the Quarto.Executable setting to explicitly enumerate Quarto installations.

Version scanning

Posit Connect can scan configured directories that contain multiple Quarto installations. Connect examines each direct child directory for an executable at bin/quarto. Connect does not match other executable names that contain quarto, and it does not search nested directories.

For example, any of the following installed versions of Quarto will be automatically detected:

/opt/quarto/1.4.557/bin/quarto
/opt/quarto/1.5.57/bin/quarto
/opt/quarto/1.6.43/bin/quarto
Note

Symbolic links from any of these scan locations to alternate locations are permitted.

Version scanning is configured with Quarto.ExecutableVersionScanning, which accepts one or more absolute directory paths. It is disabled when no paths are configured.

/etc/rstudio-connect/rstudio-connect.gcfg
[Quarto]
; Scan direct child directories beneath /opt/quarto:
ExecutableVersionScanning = /opt/quarto

; Add an additional scan directory:
ExecutableVersionScanning = /opt/quarto
ExecutableVersionScanning = /opt/quarto-extra

; An empty value is ignored:
ExecutableVersionScanning =
Note

Use the Quarto.Executable setting to explicitly enumerate Quarto installations if your organization uses a complicated directory hierarchy.

Path scanning

Posit Connect can use the PATH environment variable to discover a version of Quarto if one is not otherwise found.

Path scanning is disabled by default and can be enabled using the Quarto.ExecutablePathScanning setting.

/etc/rstudio-connect/rstudio-connect.gcfg
[Quarto]
ExecutablePathScanning = true
Warning

Use of PATH to locate a single Quarto installation is not recommended for most Posit Connect installations. An environment with multiple versions of Quarto helps you provide a stable, reproducible environment for your content authors.

Excluding versions

If you have versions of Quarto that are picked up by automatic scanning but which you would like to exclude, disable Quarto scanning and explicitly specify all versions you would like to use with the Quarto.Executable configuration property.

Quarto version matching

Note

View the Quarto runtime state in the Connect UI at System > Info > System Info. The page reports whether the runtime is disabled, not permitted by the license, enabled with no versions found, or enabled with discovered versions. For each local installation, the page also reports the executable path.

Restart Connect after you install a runtime version so Connect can discover the installation.

Posit Connect attempts to find a Quarto installation that is appropriate for published content based on the version constraint specified in the manifest.json file.

A Quarto version constraint is not generated automatically, but publishers may manually add an environment.quarto.requires field to the manifest.json file if they want to use a custom version constraint. Quarto version constraints must respect the PEP 440 Specification.

Example manifest.json file segment:

manifest.json
"environment": {
    "quarto": {
        "requires": ">=1.4"
    }
}

When a Quarto version constraint is not included in the environment section, the current Quarto version in use is included as-is.

Example manifest.json file segment:

manifest.json
"quarto": {
    "version": "1.5.57"
}

For this case, Posit Connect applies a “nearest” matching approach. This algorithm attempts to always find a version of Quarto to use with your content. More deployments will succeed, but not always with the same version of Quarto that is used by the author.

If you would prefer a strict association between authored and deployed Quarto versions, you can choose to use an “exact” matching approach.

The “nearest” matching algorithm is the most flexible option and favors publication of your content over precise duplication of the authoring environment.

The “major-minor” algorithm is a middle ground between “nearest” and “exact”. It requires exact MAJOR.MINOR matching but is flexible about the patch level. This is a useful option when your desktop and server may occasionally have different update cycles when installing bug fix releases.

An inconsistent version of Quarto occasionally causes problems when installing package dependencies. For the best results, make sure that Posit Connect has access to the same versions of Quarto used to author content.

The Quarto version matching approach is controlled with the Quarto.VersionMatching configuration setting.

nearest

Find an installation that is close to the version used when authoring the content. This algorithm uses the ordered tests when looking for MAJOR.MINOR.PATCH version matches:

  1. Use exact version match.

  2. If there are matching MAJOR.MINOR releases, use least-greater version.

  3. If there are matching MAJOR.MINOR releases, use latest of these.

  4. Use least-greater version across all releases.

  5. Use latest across all releases.

major-minor

Find an installation with an exact MAJOR.MINOR version match that is close to the version used when authoring the content. If a compatible version cannot be found, content will fail to deploy. The algorithm is a constrained “nearest” search:

  1. Use exact version match.

  2. If there are matching MAJOR.MINOR releases, use least-greater version.

  3. If there are matching MAJOR.MINOR releases, use latest of these.

exact

Finds an installation that exactly matches the version used when authoring the content. If a matching version cannot be found, content will fail to deploy.

Quarto project profiles

Posit Connect uses the Quarto.Profile setting to configure the default Quarto project profile for Quarto renders.

The Quarto.Profile indicates the value given to the QUARTO_PROFILE environment variable. By default, the value “connect” is used.

Note

Quarto v1.2 adds support for project profiles. Older versions of Quarto will not automatically receive a value for QUARTO_PROFILE.

This first example overrides the default “connect” value for Quarto.Profile:

/etc/rstudio-connect/rstudio-connect.gcfg
[Quarto]
Profile = "production"

Some installations may want to enable multiple profiles:

/etc/rstudio-connect/rstudio-connect.gcfg
[Quarto]
Profile = "connect,staging"

Individual content items may provide an alternate QUARTO_PROFILE value. You can prevent this situation by adding the QUARTO_PROFILE environment variable to the set of prohibited environment variables using Applications.ProhibitedEnvironment:

/etc/rstudio-connect/rstudio-connect.gcfg
[Applications]
ProhibitedEnvironment = "QUARTO_PROFILE"