quarto-dev · cderv · Jul 24, 2026 · Jul 24, 2026
diff --git a/_freeze/docs/authoring/cross-references/execute-results/html.json b/_freeze/docs/authoring/cross-references/execute-results/html.json
diff --git a/_freeze/docs/authoring/cross-references/figure-html/fig-plot-output-1.png b/_freeze/docs/authoring/cross-references/figure-html/fig-plot-output-1.png
diff --git a/_freeze/docs/authoring/tables/execute-results/html.json b/_freeze/docs/authoring/tables/execute-results/html.json
diff --git a/docs/authoring/_table-crossrefs.md b/docs/authoring/_table-crossrefs.md
@@ -16,4 +16,10 @@ See @tbl-letters.
 
 Which looks like this when rendered to HTML:
 
+::: light-content
 ![](images/crossref-table.png){fig-alt="A table with 3 columns and four rows. The text 'Table 1: My Caption' is above the header column. The text 'See tbl. 1' is aligned to the left underneath the last column." width="500"}
+:::
+
+::: dark-content
+![](images/crossref-table-dark.png){fig-alt="A table with 3 columns and four rows. The text 'Table 1: My Caption' is above the header column. The text 'See tbl. 1' is aligned to the left underneath the last column." width="500"}
+:::
diff --git a/docs/authoring/elephant-dark.png b/docs/authoring/elephant-dark.png
diff --git a/docs/authoring/figures.qmd b/docs/authoring/figures.qmd
@@ -18,9 +18,21 @@ In Pandoc markdown, a figure is created whenever a captioned image appears by-it
 
 This results in the following treatment for various output types:
 
-| HTML                                                                              | PDF                                                                  | Word                                                                  |
-|---------------------------|-----------------------|-----------------------|
-| ![](images/html-figure.png){fig-alt="A line drawing of an elephant." width="340"} | ![](images/pdf-figure.png){fig-alt="A line drawing of an elephant."} | ![](images/word-figure.png){fig-alt="A line drawing of an elephant."} |
+::: {.list-table header-rows=1 tbl-colwidths="[33,33,33]"}
+- - HTML
+  - PDF
+  - Word
+
+- - ::: light-content
+    ![](images/html-figure.png){fig-alt="A line drawing of an elephant." width="340"}
+    :::
+
+    ::: dark-content
+    ![](images/html-figure-dark.png){fig-alt="A line drawing of an elephant." width="340"}
+    :::
+  - ![](images/pdf-figure.png){fig-alt="A line drawing of an elephant."}
+  - ![](images/word-figure.png){fig-alt="A line drawing of an elephant."}
+:::
 
 Note that for LaTeX / PDF output figures are automatically numbered (you can arrange for figures to be numbered in other formats using [Cross References](cross-references.qmd)).
 
@@ -139,9 +151,15 @@ format:
 
 In HTML output formats you can add  lightbox styling and behavior to images to allow a reader to click to see a larger version of the image. For example, the following image has lightbox treatment (click on the image to see lightbox in action):
 
+::: light-content
 ![An elephant](elephant.png){.lightbox width=50%}
+:::
+
+::: dark-content
+![An elephant](elephant-dark.png){.lightbox width=50%}
+:::
 
-Lightbox treatment can be added by adding the class `.lightbox` to an image: 
+Lightbox treatment can be added by adding the class `.lightbox` to an image:
 
 ```markdown
 ![An elephant](elephant.png){.lightbox}
@@ -205,7 +223,13 @@ Famous Elephants
 
 Again, the last paragraph provides the main caption, and the individual figures carry the sub-captions. Here is what this looks like when rendered as HTML:
 
+::: light-content
 ![](images/elephant-subfigures.png){fig-alt="An artistic rendition of Surus, Hannibal's last war elephant, is on the left. Underneath this picture is the caption '(a) Surus.' On the right is a line drawing of Hanno, a famous elephant. Underneath this picture is the caption '(b) Hanno.' The words 'Figure 1: Famous elephants' are centered beneath both pictures."}
+:::
+
+::: dark-content
+![](images/elephant-subfigures-dark.png){fig-alt="An artistic rendition of Surus, Hannibal's last war elephant, is on the left. Underneath this picture is the caption '(a) Surus.' On the right is a line drawing of Hanno, a famous elephant. Underneath this picture is the caption '(b) Hanno.' The words 'Figure 1: Famous elephants' are centered beneath both pictures."}
+:::
 
 Note that the empty lines between the figures (and between the last figure and the caption) are required (it's what indicates that these images belong to their own paragraphs rather than being multiple images within the same paragraph).
 
@@ -225,7 +249,13 @@ To layout two figures with their own standalone captions (and no main caption),
 :::
 ```
 
+::: light-content
 ![](images/elephant-figures-no-subcaption.png){fig-alt="An artistic rendition of Surus, Hannibal's last war elephant, is on the left. Underneath this picture is the caption 'Surus.' On the right is a line drawing of Hanno, a famous elephant. Underneath this picture is the caption 'Hanno.'"}
+:::
+
+::: dark-content
+![](images/elephant-figures-no-subcaption-dark.png){fig-alt="An artistic rendition of Surus, Hannibal's last war elephant, is on the left. Underneath this picture is the caption 'Surus.' On the right is a line drawing of Hanno, a famous elephant. Underneath this picture is the caption 'Hanno.'"}
+:::
 
 You can also eliminate the captions entirely:
 
@@ -253,7 +283,13 @@ If you have more than 2 images, you might want to lay them out across multiple r
 :::
 ```
 
+::: light-content
 ![](images/elephant-rows.png){fig-alt="A 2x2 grid of pictures of elephants. There are labels underneath each of the pictures. Clockwise from the upper left, the labels say: Surus, Hanno, Lin Wang, and Abdul Abbas."}
+:::
+
+::: dark-content
+![](images/elephant-rows-dark.png){fig-alt="A 2x2 grid of pictures of elephants. There are labels underneath each of the pictures. Clockwise from the upper left, the labels say: Surus, Hanno, Lin Wang, and Abdul Abbas."}
+:::
 
 More complex figure arrangements (e.g. rows with varying column layouts) are possible. See the [Custom Layouts](#complex-layouts) section below for more details.
 
@@ -404,7 +440,13 @@ For example, this defines a layout with two equally sized figures in the first r
 :::
 ```
 
+::: light-content
 ![](images/layout-attrib.png){fig-alt="Three elephant pictures arranged such that two pictures are side-by-side in the first row, and the third picture is underneath both of these. The picture on the left in the first row is captioned 'Surus' and the picture on the right is captioned 'Hanno'. The picture underneath these two is captioned 'Lin Wang' and is as as wide and tall as the other two put together."}
+:::
+
+::: dark-content
+![](images/layout-attrib-dark.png){fig-alt="Three elephant pictures arranged such that two pictures are side-by-side in the first row, and the third picture is underneath both of these. The picture on the left in the first row is captioned 'Surus' and the picture on the right is captioned 'Hanno'. The picture underneath these two is captioned 'Lin Wang' and is as as wide and tall as the other two put together."}
+:::
 
 The `layout` attribute is a 2-dimensional array where the first dimension defines rows and the second columns. In this case `"layout="[[1,1], [1]]"` translates to: create two rows, the first of which has two columns of equal size and the second of which has a single column.
 
@@ -432,7 +474,13 @@ You can also use negative values to create space between elements. For example:
 :::
 ```
 
+::: light-content
 ![](images/layout-attrib-negative.png){fig-alt="Three elephant pictures arranged such that two pictures are side-by-side in the first row, and the third picture is underneath both of these. The picture on the left in the first row is captioned 'Surus' and the picture on the right is captioned 'Hanno'. The two pictures are separated by some whitespace. The picture underneath these two is captioned 'Lin Wang' and is wider and taller than the other two put together."}
+:::
+
+::: dark-content
+![](images/layout-attrib-negative-dark.png){fig-alt="Three elephant pictures arranged such that two pictures are side-by-side in the first row, and the third picture is underneath both of these. The picture on the left in the first row is captioned 'Surus' and the picture on the right is captioned 'Hanno'. The two pictures are separated by some whitespace. The picture underneath these two is captioned 'Lin Wang' and is wider and taller than the other two put together."}
+:::
 
 ### Vertical Alignment
 
@@ -446,7 +494,13 @@ If you have a layout with a row of images of differing heights, you can control
 :::
 ```
 
+::: light-content
 ![](images/valign.png){fig-alt="Two pictures of elephants side by side. The picture on the left has the label 'Figure 1: Surus' underneath it. The picture on the right has the label 'Figure 2: Lin Wang' underneath it. The figure on the left is more than twice the width and height of the figure on the right."}
+:::
+
+::: dark-content
+![](images/valign-dark.png){fig-alt="Two pictures of elephants side by side. The picture on the left has the label 'Figure 1: Surus' underneath it. The picture on the right has the label 'Figure 2: Lin Wang' underneath it. The figure on the left is more than twice the width and height of the figure on the right."}
+:::
 
 Note that vertical alignment isn't limited to images, you can also vertically align any other elements that are included in a panel.
 

diff --git a/docs/authoring/images/crossref-table-dark.png b/docs/authoring/images/crossref-table-dark.png
diff --git a/docs/authoring/images/elephant-figures-no-subcaption-dark.png b/docs/authoring/images/elephant-figures-no-subcaption-dark.png
diff --git a/docs/authoring/images/elephant-rows-dark.png b/docs/authoring/images/elephant-rows-dark.png
diff --git a/docs/authoring/images/elephant-subfigures-dark.png b/docs/authoring/images/elephant-subfigures-dark.png
diff --git a/docs/authoring/images/html-figure-dark.png b/docs/authoring/images/html-figure-dark.png
diff --git a/docs/authoring/images/layout-attrib-dark.png b/docs/authoring/images/layout-attrib-dark.png
diff --git a/docs/authoring/images/layout-attrib-negative-dark.png b/docs/authoring/images/layout-attrib-negative-dark.png
diff --git a/docs/authoring/images/valign-dark.png b/docs/authoring/images/valign-dark.png
diff --git a/docs/authoring/markdown-basics.css b/docs/authoring/markdown-basics.css
@@ -0,0 +1,9 @@
+.heading-output {
+  border-bottom: none;
+  margin-top: 0;
+  margin-bottom: 0;
+}
+
+.pad-to-code-block {
+  padding-top: 1rem;
+}
diff --git a/docs/authoring/markdown-basics.qmd b/docs/authoring/markdown-basics.qmd
@@ -1,10 +1,12 @@
 ---
 title: Markdown Basics
 format: html
-language: 
+language:
   section-title-footnotes: Example Footnotes
-aliases: 
+aliases:
   - /docs/authoring/
+css:
+  - markdown-basics.css
 ---
 
 ## Overview
@@ -80,56 +82,107 @@ Violets are blue.
 
 : {tbl-colwidths="[50, 50]"}
 
-```{=html}
-<style type="text/css">
-.heading-output {
-  border-bottom: none;
-  margin-top: 0;
-  margin-bottom: 0;
-}
-</style>
-```
 ## Links & Images
 
-+------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+
-| Markdown Syntax                                                        | Output                                                                                                 |
-+========================================================================+========================================================================================================+
-| ``` markdown                                                           | <https://quarto.org>                                                                                   |
-| <https://quarto.org>                                                   |                                                                                                        |
-| ```                                                                    |                                                                                                        |
-+------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+
-| ``` markdown                                                           | [Quarto](https://quarto.org)                                                                           |
-| [Quarto](https://quarto.org)                                           |                                                                                                        |
-| ```                                                                    |                                                                                                        |
-+------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+
-| ``` markdown                                                           | [Markdown Basics](./markdown-basics.qmd)                                                               |
-| [Markdown Basics](./markdown-basics.qmd)                               |                                                                                                        |
-| ```                                                                    |                                                                                                        |
-+------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+
-| ``` markdown                                                           | [Markdown Basics - Links & Images](./markdown-basics.qmd#links-images)                                 |
-| [Markdown Basics - Links & Images](./markdown-basics.qmd#links-images) |                                                                                                        |
-| ```                                                                    |                                                                                                        |
-+------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+
-| ``` markdown                                                           | [Markdown Basics - Links & Images](#links-images)                                                      |
-| [Markdown Basics - Links & Images](#links-images)                      |                                                                                                        |
-| ```                                                                    |                                                                                                        |
-+------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+
-| ``` markdown                                                           | ![Caption](elephant.png){fig-alt="A line drawing of an elephant."}                                     |
-| ![Caption](elephant.png)                                               |                                                                                                        |
-| ```                                                                    |                                                                                                        |
-+------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+
-| ``` markdown                                                           | [![Caption](elephant.png)](https://quarto.org)                                                         |
-| [![Caption](elephant.png)](https://quarto.org)                         |                                                                                                        |
-| ```                                                                    |                                                                                                        |
-+------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+
-| ``` markdown                                                           | [![Caption](elephant.png "An elephant"){fig-alt="A line drawing of an elephant."}](https://quarto.org) |
-| [![Caption](elephant.png "An elephant")](https://quarto.org)           |                                                                                                        |
-| ```                                                                    |                                                                                                        |
-+------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+
-| ``` markdown                                                           | [![](elephant.png){fig-alt="A line drawing of an elephant."}](https://quarto.org)                      |
-| [![](elephant.png){fig-alt="Alt text"}](https://quarto.org)            |                                                                                                        |
-| ```                                                                    |                                                                                                        |
-+------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+
+::: {.list-table header-rows=1 tbl-colwidths="[50, 50]"}
+- - Markdown Syntax
+  - Output
+
+- - ``` markdown
+    <https://quarto.org>
+    ```
+  - ::: pad-to-code-block
+    <https://quarto.org>
+    :::
+
+- - ``` markdown
+    [Quarto](https://quarto.org)
+    ```
+  - ::: pad-to-code-block
+    [Quarto](https://quarto.org)
+    :::
+
+- - ``` markdown
+    [Markdown Basics](./markdown-basics.qmd)
+    ```
+  - ::: pad-to-code-block
+    [Markdown Basics](./markdown-basics.qmd)
+    :::
+
+- - ``` markdown
+    [Markdown Basics - Links & Images](./markdown-basics.qmd#links-images)
+    ```
+  - ::: pad-to-code-block
+    [Markdown Basics - Links & Images](./markdown-basics.qmd#links-images)
+    :::
+
+- - ``` markdown
+    [Markdown Basics - Links & Images](#links-images)
+    ```
+  - ::: pad-to-code-block
+    [Markdown Basics - Links & Images](#links-images)
+    :::
+
+- - ``` markdown
+    ![Caption](elephant.png)
+    ```
+  - ::: pad-to-code-block
+
+    ::: light-content
+    ![Caption](elephant.png){fig-alt="A line drawing of an elephant."}
+    :::
+
+    ::: dark-content
+    ![Caption](elephant-dark.png){fig-alt="A line drawing of an elephant."}
+    :::
+
+    :::
+
+- - ``` markdown
+    [![Caption](elephant.png)](https://quarto.org)
+    ```
+  - ::: pad-to-code-block
+
+    ::: light-content
+    [![Caption](elephant.png)](https://quarto.org)
+    :::
+
+    ::: dark-content
+    [![Caption](elephant-dark.png)](https://quarto.org)
+    :::
+
+    :::
+
+- - ``` markdown
+    [![Caption](elephant.png "An elephant")](https://quarto.org)
+    ```
+  - ::: pad-to-code-block
+
+    ::: light-content
+    [![Caption](elephant.png "An elephant"){fig-alt="A line drawing of an elephant."}](https://quarto.org)
+    :::
+
+    ::: dark-content
+    [![Caption](elephant-dark.png "An elephant"){fig-alt="A line drawing of an elephant."}](https://quarto.org)
+    :::
+
+    :::
+
+- - ``` markdown
+    [![](elephant.png){fig-alt="Alt text"}](https://quarto.org)
+    ```
+  - ::: pad-to-code-block
+
+    ::: light-content
+    [![](elephant.png){fig-alt="A line drawing of an elephant."}](https://quarto.org)
+    :::
+
+    ::: dark-content
+    [![](elephant-dark.png){fig-alt="A line drawing of an elephant."}](https://quarto.org)
+    :::
+
+    :::
+:::
 
 ## Lists