From 290ab3dee9f6423d4c52ff0695dc5de3d810304c Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Tue, 23 Jun 2026 13:45:02 +0200 Subject: [PATCH] docs: document profile priority and missing profile behavior Clarify that first-listed profile wins scalar conflicts when multiple profiles are active. Also document that a named profile with no corresponding _quarto-{name}.yml file is silently ignored. Closes quarto-cli-gr1b. --- docs/projects/profiles.qmd | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/projects/profiles.qmd b/docs/projects/profiles.qmd index 1abd619729..be7fc87607 100644 --- a/docs/projects/profiles.qmd +++ b/docs/projects/profiles.qmd @@ -127,6 +127,12 @@ quarto render quarto render --profile advanced,production ``` +When multiple profiles are active and their configurations contain the same scalar key, the **first-listed profile takes priority**. For example, with `--profile advanced,production`, the `advanced` profile's values win any scalar conflicts. Arrays and objects follow standard [metadata merging](quarto-projects.qmd#metadata-merging) rules (arrays are union-concatenated, objects are deep-merged). + +::: {.callout-warning} +If a profile is specified but no corresponding `_quarto-{name}.yml` file exists, the profile is **silently ignored** with no warning or error. This can lead to unexpected behavior if you mistype a profile name. +::: + ## Profile Content You can also specify that content within your project only be included when a certain profile is active. You do this using the `.content-visible` class along with the `when-profile` attribute to a div or span. For example, here we defined a div that is included only for the `advanced` profile: