Merge pull request #1461 from quarto-dev/brand

Brand edits

Author: cwickham

docs/authoring/brand.qmd

@@ -2,12 +2,6 @@
 title: Multiformat branding with `_brand.yml`
 ---
 
-::: callout-caution
-## Work In Progress
-
-These docs are a work-in-progress and may be incorrect or incomplete. Feedback welcome.
-:::
-
 ## Overview
 
 Quarto supports [**brand.yml**](https://posit-dev.github.io/brand-yml/)---a single YAML file that can be used to customize the appearance of your documents across multiple formats. This is particularly useful for organizations that need a unified look across various formats.
@@ -102,7 +96,7 @@ color:
   background: blue
 ```
 
-The most commonly used colors include `foreground`, `background` and `primary`:
+The most commonly used semantic colors include `foreground`, `background` and `primary`:
 
 ``` {.yaml filename="_brand.yml"}
 color:
@@ -166,7 +160,15 @@ logo:
   medium: logo.png
 ```
 
-You can specify a local file path, relative to the location of `_brand.yml`, or a URL (*is this true?*).
+You can specify a local file path, relative to the location of `_brand.yml`, or a URL.
+
+::: {.callout-warning}
+
+ ## Limitation
+
+ Logos specified as URLs are not currently supported in `format: typst`.
+
+ ::: 
 
 A single logo may not work well in all locations so **brand.yml** allows you to set three different logos: `small`, `medium` and `large`. For example:
 
@@ -223,7 +225,7 @@ typography:
       source: google
 ```
 
-The properties you can set for a font under `fonts` depends on the `source`. You can see the other properties available in our [Reference for Brand](docs/reference/metadata/brand.qmd#font-resource-definitions).
+The properties you can set for a font under `fonts` depends on the `source`. You can see the other properties available in our [Reference for Brand](/docs/reference/metadata/brand.qmd#font-resource-definitions).
 
 You can then refer to fonts by `family` in the remaining typography options:
 
@@ -330,50 +332,51 @@ The supported fields are generally described as follows:
 
 [Defaults in the **brand.yml** docs](https://posit-dev.github.io/brand-yml/brand/defaults.html){.external}
 
-The `defaults` section of **brand.yml** allows users to set option for specific tools that don't otherwise fit into the **brand.yml** schema. In particular, Quarto currently supports `defaults: bootstrap`.
+The `defaults` section of **brand.yml** allows users to set options for specific tools that don't otherwise fit into the **brand.yml** schema. Quarto's implementation currently supports `defaults: bootstrap`.
 
-::: {.content-hidden}
+#### Bootstrap
 
-#### Quarto 
+The `bootstrap` section of `defaults` follows [**brand.yml**](https://posit-dev.github.io/brand-yml/brand/defaults.html) and applies to the `html` and `dashboard` formats.
+Quarto merges the options set under `defaults: bootstrap` in the appropriate layer of [Quarto's SCSS layering system](/docs/output-formats/html-themes-more.qmd).
 
-Quarto merges options you set in `defaults: quarto` with document metadata. For example, you can use this to set format specific options like syntax highlighting for `html`:
+The `defaults` option inside `bootstrap`, can take a string, or key-value pairs
+corresponding to SCSS variable name-value pairs.
+Building on our initial example, you could use `bootstrap: defaults` to set the SCSS variables `link-decoration` and `navbar-fg`:
 
 ``` {.yaml filename="_brand.yml"}
 defaults:
-  quarto:
-    format:
-      html:
-        highlight-style: github
+  bootstrap:
+    defaults: # defaults also supports a string as its value
+      link-decoration: underline
+      navbar-fg: "#fff"
 ```
 
-Or, you might change the `logo` options for `typst`:
+The resulting HTML pages will have links that are underlined and use white for text in the navigation bar.
 
-``` {.yaml filename="_brand.yml"}
-defaults:
-  quarto:
-    format:
-      typst:
-        logo:
-          location: left-bottom
-```
-
-::: callout-note
-## Set all formats in document metadata
-
-Because of the merging behavior of `format`, if you set format specific options in `defaults: quarto`, you'll need to set all the required formats in document metadata:
-
-``` {.yaml filename="document.qmd"}
-format:
-  html: default
-  revealjs: default
-```
+::::::: {.column-body-outset-right layout-ncol="2"}
+::: {}
+![Without `defaults: bootstrap` setting](/docs/authoring/images/brand-html-no-defaults.png){.lightbox group="brand-bootstrap-defaults" fig-alt="Screenshot of a webpage. The text is dark grey on a light blue background, using a rounded sans-serif typeface, a logo appears in the navbar."}
 :::
 
-::: 
+::: {}
+![With `defaults: bootstrap` setting: note the link decoration and the white color for the navbar text](/docs/authoring/images/brand-html-defaults.png){.lightbox group="brand-bootstrap-defaults" fig-alt="Screenshot of a webpage. It looks identical to the previous image, except for underlined links and white text on the navbar."}
+:::
+:::::::
 
-#### Bootstrap
+In addition to the `defaults` option, Quarto supports `uses`, `functions`, `mixins` and `rules`, which all take a string value. 
+For example, you could use `rules` to provide a CSS rule to remove the border below second-level headings:
 
-*How relevant is `defaults: bootstrap`? Example? WHere do you find out what you can put under `bootstrap`?*
+```{.yaml filename="_brand.yml"}
+defaults:
+  bootstrap:
+    # uses: <string>
+    # functions: <string>
+    # mixins: <string>
+    rules: |
+      h2 {
+        border: none;
+      }
+```
 
 ### Meta
 
@@ -438,21 +441,54 @@ You can't currently access `typography`, `meta`, or `defaults` values using the
 
 ### In SCSS
 
-If `_brand.yml` defines `color: blue`:
+The colors defined in `palette` are set as SCSS variables of the form `brand-COLOR_NAME`. 
+For example, if `_brand.yml` defines `blue`:
 
 ```{.yaml filename="_brand.yml"}
 color:
   palette:
     blue: "#ddeaf1"
 ```
 
-This should work:
+Then the variable `$brand-blue` is will be set to `#ddeaf1` in the `defaults` layer of  [Quarto's SCSS layering system](/docs/output-formats/html-themes-more.html#bootstrap-bootswatch-layering). 
+You can add a custom SCSS file, `styles.scss`, in the usual way:
+```{.yaml filename="_quarto.yml"}
+format:
+  html:
+    theme: [styles.scss]
+```
+
+Then `styles.scss` can use these brand variables to make style tweaks. 
+For example, you might want all `h1` elements to be `blue`:
+
+```{.scss filename="styles.scss"}
+/*-- scss:rules --*/
+
+h1 {
+  color: $brand-blue;
+}
+```
+
+When you specify SCSS files without an explicit `brand` element, it is equivalent to listing them after `brand`.
+For instance, the above `theme` is equivalent to:
 
-```{.scss filename="custom.scss"}
-/*-- scss:defaults --*/
-$navbar-bg: $brand-blue; 
+```{.yaml filename="_quarto.yml"}
+format:
+  html:
+    theme: [brand, styles.scss]
+```
+
+The order of elements in `theme` controls their priority. 
+For example, you could layer brand and your custom SCSS on top of a built-in theme:
+
+```{.yaml filename="_quarto.yml"}
+format:
+  html:
+    theme: [cosmo, brand, styles.scss]
 ```
 
+You can learn more about layering themes in [More About Quarto Themes](/docs/output-formats/html-themes-more.qmd).
+
 ### Typst
 
 In Typst documents, brand colors are set in a [dictionary](https://typst.app/docs/reference/foundations/dictionary/) called `brand-color`. 
@@ -474,7 +510,3 @@ Filters and shortcodes can access brand values using the `brand` Lua module.
 local brand = require('modules/brand/brand')
 local primary = brand.get_color('primary')
 ```
-
-## Comprehensive Example
-
-TBD

docs/authoring/images/brand-html-defaults.png

@@ -44,7 +44,7 @@ From time to time, as the Bootswatch themes are updated, we will update these me
 
 ## Bootstrap / Bootswatch Layering
 
-When using the Quarto HTML format, we allow the user to specify theme information in the document front matter (or project YAML). The theme information consists of a list of one or more of
+When using the Quarto `html` and `dashboard` formats, we allow the user to specify theme information in the document front matter (or project YAML). The theme information consists of a list of one or more of
 
 -   A valid built in Bootswatch theme name
 
@@ -106,3 +106,50 @@ We order the themes according to the order that they are specified in the YAML,
         Bootstrap
         cosmo           /*-- scss:rules --*/
         custom.scss     /*-- scss:rules --*/
+
+## `revealjs` Layering
+
+The same system applies for `revealjs` and its themes.
+`revealjs` themes shipped with Quarto do not have a uniform variable naming convention, and so different SCSS files are likely to be needed to make effective changes to different themes.
+
+Nevertheless, the following examples illustrate what's possible:
+
+``` yaml
+# In this configuration, `custom.scss` takes precedence
+format:
+  revealjs:
+    theme:
+      - blood
+      - custom.scss
+# In this configuration, the `blood` theme takes precedence
+format:
+  revealjs:
+    theme:
+      - custom.scss
+      - blood
+```
+
+## `_brand.yml` Layering
+
+Quarto supports [**brand.yml**](https://posit-dev.github.io/brand-yml/brand/defaults.html), see the [Brand guide](/docs/authoring/brand.qmd) for more details.
+By default, styling information in `_brand.yml` takes the lowest precedence.
+To change this, use the `"brand"` string in your theme configuration in YAML:
+
+``` yaml
+# In this configuration, the `blood` theme takes precedence
+# over `custom.scss` *and* the information in `_brand.yml`
+format:
+  revealjs:
+    theme:
+      - custom.scss
+      - blood
+# In this configuration, the information in `_brand.yml` takes
+# precedence over the `blood` theme and `custom.scss`, in that
+# order
+format:
+  revealjs:
+    theme:
+      - blood
+      - custom.scss
+      - brand
+```

docs/authoring/images/brand-html-no-defaults.png

@@ -215,3 +215,4 @@ See these articles to learn more about using Reveal:
 -   [Reveal Basics](index.qmd) covers the basic mechanics of creating presentations.
 -   [Presenting Slides](presenting.qmd) describes slide navigation, printing to PDF, drawing on slides using a chalkboard, and creating multiplex presentations.
 -   [Advanced Reveal](advanced.qmd) delves into transitions, animations, advanced layout and positioning, and other options available for customizing presentations.
+-   [More About Quarto Themes](/docs/output-formats/html-themes-more.qmd) describes the layering system in more detail, including interactions with other SCSS files and [`_brand.yml`](/docs/authoring/brand.qmd).