Brand documentation should include information about how `brand` interacts with `theme`

[gadenbuie]

What would you like to do?

Report an issue on quarto.org

Description

Originally pointed out here: posit-dev/brand-yml#56

The brand documentation at https://quarto.org/docs/authoring/brand.html should include information about how theme and brand interact, in particular to describe the difference between the following three scenarios:

format:
  html:
    theme: yeti

format:
  html:
    theme:
      - brand
      - yeti

format:
  html:
    theme:
      - yeti
      - brand

[gadenbuie]

Oh, it is documented in More about Quarto themes, which is linked from the In SCSS section of the primary brand section.

I think the locations of those pieces make sense, but the core issue of how brand interacts with theme should probably be raised a little earlier in the docs. Many people will encounter needing to know about this without considering themselves among the category of users who needs to know about SCSS.

[mcanouil]

I agree, at my first attempt at brand (last Thursday), I quickly needed to know this bit of information to properly use a default theme + brand.

I believe most of the brand users will already have a default theme set and will want to add branding to it.

[cscheid]

We changed the output of quarto create in 1.6 to have brand ahead of cosmo in the team, but I agree that we need to have a better explanation for folks migrating their <1.6 content.