Clarify _brand.yml Placement for SCSS Variable Support in Documentation

[danielvartan]

Hi there,

Just a quick note regarding https://quarto.org/docs/authoring/brand.html#in-scss.

It would be helpful to inform users that to utilize colors as variables in SCSS files, the _brand.yml file must be listed last in the theme configuration. Otherwise, the variables won’t work as expected.

Example:

format:
  html:
    theme: [cosmo, styles.scss, brand]

[cderv]

The document is talking about layering. Can you share an example of what you tried that required the following order ?

This way we could add the correct use case in the documentation with other explained order.

thanks

[danielvartan]

Hi @cderv,

I created an example in a test repository to illustrate the issue.

Here is the relevant excerpt from the Quarto documentation:

The colors defined in palette are set as SCSS variables of the form brand-COLOR_NAME. .

For this to work, the brand entry in the theme list must take precedence over the .scss file. However, this detail is not clearly stated in the documentation.

For example, the following configuration works as expected:

https://github.com/danielvartan/test/blob/33e699851668df62d80817109565dc68a586f45c/_quarto.yml#L62

But if you modify the line to:

    theme: [cosmo, brand, scss/styles.scss]

The color variables in the SCSS file will lose their references, resulting in an error:

processing file: index.qmd
  |                                                          output file: index.knit.md

                                                                                                            
ERROR: Theme file compilation failed:

Error: Undefined variable.
     ╷
1048 │ $body-color: $brand-gray;
     │              ^^^^^^^^^^^

The documentation should clarify that the order of the theme array is crucial for proper variable resolution.

Cheers!

[danielvartan]

Or do you mean the documentation says the other way around, and it is in fact wrong ? 🤔

Now re-reading with your example, I am in doubt

Yes, that's correct. The text emphasizes that the order is crucial but fails to explain that the brand must precede the SCSS file to ensure the color variables are properly defined. Additionally, it states, "You can add a custom SCSS file, styles.scss, in the usual way" (theme: [styles.scss]), but this is inaccurate. If you follow that approach and attempt to use a color defined in _brands.yml, it won't work.

[cderv]

I see. this is not a problem specific to brand here. You are using a variable do define another one

/*-- scss:defaults --*/

$body-color: $brand-gray;
$toc-font-size: 1em !default;

Following the layering system (https://quarto.org/docs/output-formats/html-themes-more.html#bootstrap-bootswatch-layering), defaults is layered in reversed order so that variables from last added file are defined first and can override some theme default for example. This is different than rules layer for example.

our common docs says:

We order the themes according to the order that they are specified in the YAML, maintaining the order for declarations and rules and reversing the order for variables (allowing the files specified later in the list to provide defaults variable values to the files specified earlier in the list).

By using $brand-gray in your cusom layer, you need $brand-gray to be defined, which only happen if it comes last.

If you were to use $brand-gray in the rules part, then what is currently described in documentation does apply;

This is quite specific to default variables definition. It would happen if you were to use a cosmo theme variable in your style.scss but use theme: [cosmo, style.scss] -- you would get the same error

We'll try to add an example on this.

[danielvartan]

If you were to use $brand-gray in the rules part, then what is currently described in documentation does apply;

Have you tested this? It doesn’t seem so, but I can’t test it at the moment.

[cderv]

yes doing [cosmo, brand, scss/styles.scss] is working when $brand-gray is used in rules.

This is consistent with how layering works.

[danielvartan]

I just tested it, and you're absolutely right! I can't believe I missed that. Sorry for taking up your time.