quarto-dev · gordonwoodhull · Apr 8, 2025 · Apr 3, 2025 · Apr 4, 2025 · Apr 6, 2025
diff --git a/_freeze/docs/computations/execution-options/execute-results/html.json b/_freeze/docs/computations/execution-options/execute-results/html.json
diff --git a/docs/advanced/typst/brand-yaml.qmd b/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.

diff --git a/docs/authoring/brand.qmd b/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,63 @@ The **brand.yml** specification allows you to specify a `light` and `dark` versi
 
 ::: 
 
+#### Document logo customization
+
+The document `logo` option allows extra customization of the logo.
+
+To choose a brand logo resource:
+```{.yaml filename="document.qmd"}
+---
+logo: large
+---
+```
+
+To choose a brand logo resource 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"}
+---
+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 +428,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 +512,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 +659,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).
+
+
diff --git a/docs/computations/execution-options.qmd b/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:
 

diff --git a/docs/output-formats/html-themes.qmd b/docs/output-formats/html-themes.qmd
@@ -101,10 +101,20 @@ Setting the above themes in your `_quarto.yml` results in both a dark and light
 
 When providing both a dark and light mode for your html output, Quarto will automatically create a toggle to allow your reader to select the desired dark or light appearance. The toggle will automatically appear in the top right corner of your html output. When possible, the toggle will use browser local storage to maintain the user's preference across sessions.
 
-The first appearance (light or dark) elements in the theme to determine the default appearance for your html output. For example, since the `light` option appears first in the above example, a reader will see the light appearance by default.
+To honor the user's operating system or browser preference for light or dark mode, specify `respect-user-color-scheme: true`:
+
+``` yaml
+format:
+  html:
+    respect-user-color-scheme: true
+```
+
+Otherwise, the order of light and dark elements in the theme or brand will determine the default appearance for your html output. For example, since the `light` option appears first in the first example, a reader will see the light appearance by default, if `respect-user-color-scheme` is not enabled.
 
 Quarto will automatically select the appropriate light or dark version of the text highlighter that you have specified when possible. For more information, see [Code Highlighting](html-code.qmd#highlighting).
 
+As of Quarto 1.7, `respect-user-color-scheme` requires JavaScript support: users with JavaScript disabled will see the author-preferred (first) brand or theme.
+
 ### Customizing Themes
 
 As when providing a single theme, you may provide a custom theme for dark and light mode, or a list of `scss` files to customize the light and dark appearance. This website, for example uses the following to use a light `cosmo` theme and then customizes the `cosmo` theme with additional Sass variables when in dark mode:

diff --git a/docs/prerelease/1.7/_highlights.qmd b/docs/prerelease/1.7/_highlights.qmd
@@ -6,3 +6,7 @@ Quarto 1.7 includes the following new features:
   - [Caching](/docs/computations/julia.qmd#caching-julia): Save time rendering long-running notebooks by caching results.
   - [Revise.jl integration](/docs/computations/julia.qmd#revise.jl-integration): Automatically update function definitions in Julia sessions.
 
+- Improvements to dark mode:
+  - [Dark Brand](/docs/authoring/brand.qmd#dark-brand): Light and dark brands can be specified for a document or project, enabling dark mode via brand.yml.
+  - [`renderings`](/docs/computations/execution-options.qmd#output-options): Plots and tables can have `light` and `dark` renderings.
+  - [`respect-user-color-scheme`](/docs/output-formats/html-themes.qmd#dark-mode): If enabled, this option detects the user's operating system / browser preference for whether to show the page in light or dark mode.