docs: dark brand

docs/advanced/typst/brand-yaml.qmd

@@ -17,31 +17,6 @@ Brand YAML palette and theme colors are available in Typst `brand-color`, e.g. `
 
 Lighter versions of the colors, suitable as background colors, are available in `brand-background-color`, e.g. `brand-background-color.success`.
 
-## Logo
-
-The `logo` option allows extra customization in Typst for full control over layout.
-
-In all formats, `logo` can be the path to a logo or the name of a `brand.logo` resource, i.e. `small`, `medium`, or `large`. It can also be an object with
-
-`path` 
-: Image path or name of `brand.logo` resource
-`alt`
-: Alt text for the logo image
-
-The Typst implementation also supports
-
-`width`
-: Width in CSS units. Default `1.5in`.
-
-`location`
-: Location on the page in X and Y using CSS [`text-align`](https://developer.mozilla.org/en-US/docs/Web/CSS/text-align) and [`text-vertical-align`](https://developer.mozilla.org/en-US/docs/Web/CSS/vertical-align) keyword values, specifically
-`left`, `center`, `right` and `top`, `middle`, and `bottom`.
-  The X and Y components are combined with a dash, e.g. `left-top` (the default), `center-middle`, etc.
-  Applied as Typst [`align`](https://typst.app/docs/reference/layout/align/).
-
-`padding`, `padding-top`, `padding-right`, `padding-bottom`, `padding-left`
-: Amount of padding to add to each side of the logo, using CSS [`padding`](https://developer.mozilla.org/en-US/docs/Web/CSS/padding) conventions. Due to a limitation in the Lua implementation of YAML, multiple padding options are applied in alphabetical order instead of the order of the YAML object. Applied as Typst [`block.inset`](https://typst.app/docs/reference/layout/block/#parameters-inset). Default `padding: 0.75in`.
-
 ## Typography
 
 Brand YAML is specified for the following elements and Brand YAML properties. Combinations that are not supported are marked NA.
@@ -66,11 +41,11 @@ Many of the NA combinations are possible in Typst, but were removed for compatib
 
 ### Missing fonts in Typst
 
-When Typst is unable to find the requested font, it will fall back to a default font. In Typst 0.11, shipped with Quarto 1.6, the default font is Linux Libertine; in Typst 0.12, to be shipped with Quarto 1.7, the default is Libertinus Serif. 
+When Typst is unable to find the requested font, it will fall back to a default font. In Typst 0.13, shipped with Quarto 1.7, the default is Libertinus Serif.
 
-Typst 0.12 will warn `unknown font family` in this case. 
+Typst will warn `unknown font family` in this case.
 
-To tell Typst to not fall back (and not to display fonts it can't find), you can add 
+To tell Typst to not fall back (and not to display fonts it can't find), you can add
 
 ```typst
 #set text(fallback: false)
@@ -84,20 +59,13 @@ Then it tells Typst to use this font directory, in addition to any system fonts
 
 In rare cases, there may be ambiguities about a font's name that will cause Typst not to find the font. To see if a font is available to Typst, run
 
-```sh
-quarto typst fonts --font-path .quarto/typst-font-cache 2>&1 | grep *fontname*
-```
-
-Unfortunately with Typst 0.11, there is no flag to ignore system fonts, so you'll need to grep for the font name.
-
-
-With Typst 0.12, you can run
+Run
 
 ```
 quarto typst fonts --ignore-system-fonts --font-path .quarto/typst-font-cache/
 ```
 
-to list only the fonts downloaded by Quarto. (In either version of Typst, ``--variants`` can be helpful for more detail.)
+to list only the fonts downloaded by Quarto. (Adding ``--variants`` can be helpful for more detail.)
 
 If the font is listed but it still isn't working, check for variation in the font name. For example, the Sono font can be downloaded from Google Fonts as Sono, but Typst will only accept Sono Extralight Monospace.
 

docs/authoring/brand.qmd

@@ -73,6 +73,55 @@ brand: brand/_brand.yml
 
 Paths specified in `_brand.yml` are relative to the location of the brand file.
 
+### Dark Brand
+
+As with [Themes](/docs/output-formats/html-themes.qmd#dark-mode), you can specify both light and dark brands, making both a light and a dark version of your output available:
+
+```{.yaml filename="document.qmd"}
+---
+brand:
+  light: light-brand.yml
+  dark: dark-brand.yml
+---
+```
+
+This also works with brands specified directly in the document:
+
+```{.yaml filename="document.qmd"}
+---
+brand:
+  light:
+    color:
+      background: "#ffffff"
+      foreground: "#333333"
+  dark:
+    color:
+      background: "#333333"
+      foreground: "#ffffff"
+---
+```
+
+Light and dark brands can also be specified at the project-level:
+
+```{.yaml filename="_quarto.yml"}
+brand:
+  light: light-brand.yml
+  dark: dark-brand.yml
+```
+
+#### Typst
+
+To choose a dark brand in Typst output use `brand-mode: dark`:
+
+```{.yaml filename="document.qmd"}
+---
+format:
+  typst:
+    brand-mode: dark
+---
+```
+
+
 ## Brand Elements
 
 The elements of **brand.yml** are specified in the documentation for the [**brand.yml** project](https://posit-dev.github.io/brand-yml/){.external}. 
@@ -164,14 +213,6 @@ logo:
 
 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:
 
 ``` {.yaml filename="_brand.yml"}
@@ -214,6 +255,65 @@ The **brand.yml** specification allows you to specify a `light` and `dark` versi
 
 ::: 
 
+#### Document logo customization
+
+You can further customize the logo at the document level with the `logo` option.
+
+For example, you can specify a particular brand logo resource:
+```{.yaml filename="document.qmd"}
+---
+logo: large
+---
+```
+
+Or, specify a brand logo and change the alt text:
+
+```{.yaml filename="document.qmd"}
+---
+logo:
+  path: large
+  alt: Alternate alternate text
+---
+```
+
+::: {.callout-warning}
+
+## Limitation
+
+It is [not currently possible](https://github.com/quarto-dev/quarto-cli/issues/11309) to customize the logo for a specific page within a website. Only the project's `_brand.yml` is applied.
+
+::: 
+
+The Typst implementation allows customization of the logo position at the document level:
+
+```{.yaml filename="document.qmd"}
+---
+format:
+  typst:
+    logo:
+      width: 1in
+      location: right-top
+      padding-right: 0.5in
+      padding-top: 0.25in
+      alt: Alternate alternate text
+---
+```
+
++--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
+| Option                   | Description                                                                                                                                    |
++==========================+================================================================================================================================================+
+| `width`                  | Width in CSS units. Default `1.5in`.                                                                                                           |    
++--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
+| `location`               | Location on the page in `X-Y`, where `X` is `left`, `center`, or `right` and Y is `top`, `middle`, or `bottom`.                                |
+|                          | Applied as Typst [`align`](https://typst.app/docs/reference/layout/align/).                                                                    |
++--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
+| `padding`, `padding-top`,| Amount of padding to add to each side of the logo, using CSS [`padding`](https://developer.mozilla.org/en-US/docs/Web/CSS/padding) conventions.| 
+| `padding-right`,         | Padding options are applied in alphabetical order.                                                                                             |
+| `padding-bottom`,        | Applied as Typst [`block.inset`](https://typst.app/docs/reference/layout/block/#parameters-inset).                                             |
+| `padding-left`           | Default `padding: 0.75in`.                                                                                                                     |
++--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
+
+
 ### Typography
 
 [Typography in the **brand.yml** docs](https://posit-dev.github.io/brand-yml/brand/typography.html){.external}
@@ -330,6 +430,11 @@ The supported fields are generally described as follows:
 
 ::: 
 
+#### Typst
+
+See [the Advanced documentation](/docs/advanced/typst/brand-yaml.qmd#typography) for more details on the Typst implementation, and troubleshooting tips for fonts.
+
+
 ### Defaults
 
 [Defaults in the **brand.yml** docs](https://posit-dev.github.io/brand-yml/brand/defaults.html){.external}
@@ -409,7 +514,7 @@ Beyond the automatic application of your brand file, you can also directly acces
 
 Some values from the `_brand.yml` configuration file can be accessed via the `brand` shortcode. In particular, you can access colors and logos by name:
 
--   Use `{{{< brand color COLOR_NAME >}}}` to return the brand color named `COLOR_NAME` as a string.
+-   Use `{{{< brand color COLOR_NAME BRAND_MODE >}}}` to return the brand color named `COLOR_NAME` as a string. The `BRAND_MODE` is optional and defaults to `light`. To return the color from the [dark brand](#dark-brand) use `dark`.
 -   Use `{{{< brand logo LOGO_NAME >}}}` to return the brand logo named `LOGO_NAME` as an image.
 
 For example, you could use the shortcode to place a brand image you've named `icon` in a dashboard sidebar:
@@ -556,4 +661,19 @@ theme:
   - tweaks.scss  # a user-defined customization
 ```
 
-Learn more about how Quarto generates styles in [More About Quarto Themes](/docs/output-formats/html-themes-more.qmd).
+The analogous syntax also works for combining light and dark brands with light and dark themes:
+
+```yaml
+# Quarto 1.7 syntax
+theme:
+  light:
+    - cosmo
+    - brand
+  dark:
+    - slate
+    - brand
+```
+
+Learn more about how Quarto generates styles in [More About Quarto Themes](/docs/output-formats/html-themes-more.qmd).
+
+

docs/computations/execution-options.qmd

@@ -30,21 +30,23 @@ Code block options are included in a special comment at the top of the block (li
 
 Options available for customizing output include:
 
-+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Option    | Description                                                                                                                                                                                       |
-+===========+===================================================================================================================================================================================================+
-| `eval`    | Evaluate the code chunk (if `false`, just echos the code into the output).                                                                                                                        |
-+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| `echo`    | Include the source code in output                                                                                                                                                                 |
-+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| `output`  | Include the results of executing the code in the output (`true`, `false`, or `asis` to indicate that the output is raw markdown and should not have any of Quarto's standard enclosing markdown). |
-+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| `warning` | Include warnings in the output.                                                                                                                                                                   |
-+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| `error`   | Include errors in the output (note that this implies that errors executing code will not halt processing of the document).                                                                        |
-+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| `include` | Catch all for preventing any output (code or results) from being included (e.g. `include: false` suppresses all output from the code block).                                                      |
-+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
++--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Option       | Description                                                                                                                                                                                       |
++==============+===================================================================================================================================================================================================+
+| `eval`       | Evaluate the code chunk (if `false`, just echos the code into the output).                                                                                                                        |
++--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| `echo`       | Include the source code in output                                                                                                                                                                 |
++--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| `output`     | Include the results of executing the code in the output (`true`, `false`, or `asis` to indicate that the output is raw markdown and should not have any of Quarto's standard enclosing markdown). |
++--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| `warning`    | Include warnings in the output.                                                                                                                                                                   |
++--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| `error`      | Include errors in the output (note that this implies that errors executing code will not halt processing of the document).                                                                        |
++--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| `include`    | Catch all for preventing any output (code or results) from being included (e.g. `include: false` suppresses all output from the code block).                                                      |
++--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| `renderings` | Specify rendering names for the plot or table outputs of the cell, e.g. `[light, dark]`                                                                                                           |
++--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
 Here's a Knitr example with some of these additional options included:
 
@@ -69,6 +71,37 @@ summary(airquality)
 ```
 ````
 
+Here is an example of using `renderings` to provide light and dark versions of a plot. Note that the number of cell outputs must match the number of renderings.
+
+````
+---
+title: "Dark mode"
+format: 
+  html:
+    theme:
+      light: flatly
+      dark: darkly
+---
+
+```{{r}}
+#| renderings: [light, dark]
+par(bg = "#FFFFFF", fg = "#000000")
+plot(1:10) # Shown in `light` mode
+
+par(bg = "#000000", fg = "#FFFFFF", col.axis = "#FFFFFF")
+plot(1:10) # Shown in `dark` mode
+```
+````
+
+
+::: {layout-ncol=2}
+
+![light rendering](images/renderings-light-mode.png)
+
+![dark rendering](images/renderings-dark-mode.png)
+
+:::
+
 ::: callout-tip
 When using the Knitr engine, you can also use any of the available native options (e.g. `collapse`, `tidy`, `comment`, etc.). See the [Knitr options documentation](https://yihui.org/knitr/options/) for additional details. You can include these native options in option comment blocks as shown above, or on the same line as the `{r}` as shown in the Knitr documentation.
 :::