document various limitations

html brand font source: file not supported yet
revealjs does not support light/dark mode switching
can't combine renderings with *-cap or label

Author: gordonwoodhull

docs/authoring/brand.qmd

@@ -109,6 +109,16 @@ brand:
   dark: dark-brand.yml
 ```
 
+
+::: {.callout-warning}
+
+## Limitation
+
+The `revealjs` format does not support switching between light and dark modes.
+
+:::
+
+
 #### Typst
 
 To choose a dark brand in Typst output use `brand-mode: dark`:
@@ -331,6 +341,14 @@ typography:
 
 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).
 
+
+::: {.callout-warning}
+## Limitation
+
+HTML formats do not currently support `source: file`.
+:::
+
+
 You can then refer to fonts by `family` in the remaining typography options:
 
 ``` {.yaml filename="_brand.yml"}
@@ -516,8 +534,10 @@ 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 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.
+-   Use `{{{< brand color COLOR_NAME BRAND_MODE >}}}` to return the brand color named `COLOR_NAME` as a string.
+-   Use `{{{< brand logo LOGO_NAME BRAND_MODE >}}}` to return the brand logo named `LOGO_NAME` as an image.
+
+The `BRAND_MODE` is optional and defaults to `light`. To return the color from the [dark brand](#dark-brand) use `dark`.
 
 For example, you could use the shortcode to place a brand image you've named `icon` in a dashboard sidebar:
 
@@ -542,6 +562,7 @@ format: revealjs
 ## Slide Title {background-color='{{< brand color primary >}}'}
 ````
 
+
 ::: {.callout-warning}
 ## Limitation
 

docs/computations/execution-options.qmd

@@ -93,7 +93,6 @@ plot(1:10) # Shown in `dark` mode
 ```
 ````
 
-
 ::: {layout-ncol=2}
 
 ![light rendering](images/renderings-light-mode.png)
@@ -102,6 +101,37 @@ plot(1:10) # Shown in `dark` mode
 
 :::
 
+`renderings` does not currently work correctly with the cell options `label` or `fig-cap`, `tbl-cap`, etc. To combine `renderings` with crossrefs and/or captions, use the fenced div syntax:
+
+
+````
+---
+title: "Dark mode"
+format:
+  html:
+    theme:
+      light: flatly
+      dark: darkly
+---
+
+::: {#fig-caption-crossref}
+
+```{{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
+```
+
+Light and dark renderings with a caption and crossref
+
+:::
+````
+
+
 ::: 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.
 :::