DO use label with renderings, DON'T use crossref with renderings

Author: gordonwoodhull

docs/computations/execution-options.qmd

@@ -101,7 +101,10 @@ 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:
+The `renderings` cell option does not currently work correctly with cell cross-reference options (`label` starting with `fig-`, `tbl-`, etc.) or cell caption options (`fig-cap`, `tbl-cap`, etc.).
+
+
+To combine `renderings` with crossrefs and/or captions, use the fenced div syntax:
 
 
 ````
@@ -117,6 +120,7 @@ format:
 ::: {#fig-caption-crossref}
 
 ```{{r}}
+#| label: caption-crossref
 #| renderings: [light, dark]
 par(bg = "#FFFFFF", fg = "#000000")
 plot(1:10) # Shown in `light` mode
@@ -131,6 +135,9 @@ Light and dark renderings with a caption and crossref
 :::
 ````
 
+Note the use of a `label` that is not a cross-reference, i.e. that does not start with one of the [cross reference types](../authoring/cross-references.qmd#overview). It is a good practice to have named cells with `label`, for debuggability and stable resource names. However, cross-reference labels that start with `fig-`, `tbl-`, etc., will not work with `renderings`.
+
+
 
 ::: 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.