Quarto

Off-Host Execution

When using off-host execution, Quarto versions are defined by the set of Execution Environments available for executing content. For an overview of this feature, please see the Execution Environments appendix. Connect selects an appropriate image from the set of configured images based on the version of Quarto requested by the content.

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

Quarto must be installed on your system before configuring Posit Connect to allow support for Quarto content. Follow Posit’s Quarto Installation instructions when installing Quarto.

Enabling Quarto Support

If you used the Quarto Debian installer, Quarto will be available at /usr/local/bin/quarto. Configure Posit Connect to use this default location:

; /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 may 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 only available when the Quarto.Enabled is enabled and the Quarto.Executable setting references a valid Quarto installation. Posit Connect will warn at startup if Quarto is enabled without specifying an installation. Connect fails to start if Quarto is enabled but references an invalid installation.

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 versions of R and Python are identified and used with Quarto anytime that content is run. Quarto support does not require either R or Python installations, but content that uses R or Python will succeed only if a compatible installation is available.

Quarto Version Matching

Posit Connect attempts to find a Quarto installation that is appropriate for your content. By default, it 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"