diff --git a/_freeze/docs/computations/execution-options/execute-results/html.json b/_freeze/docs/computations/execution-options/execute-results/html.json index 72be953c88..a6f53d7cf2 100644 --- a/_freeze/docs/computations/execution-options/execute-results/html.json +++ b/_freeze/docs/computations/execution-options/execute-results/html.json @@ -1,8 +1,8 @@ { - "hash": "0871cbc0c1f3b895822356d2a70e28c3", + "hash": "9d0ecea30325bb683def1c3a5ca36673", "result": { "engine": "jupyter", - "markdown": "---\ntitle: Execution Options\nformat: html\n---\n\n## Output Options\n\nThere are a wide variety of options available for customizing output from executed code. All of these options can be specified either globally (in the document front-matter) or per code-block. For example, here's a modification of the Python example to specify that we don't want to \"echo\" the code into the output document:\n\n``` yaml\n---\ntitle: \"My Document\"\nexecute:\n echo: false\njupyter: python3\n---\n```\n\nNote that we can override this option on a per code-block basis. For example:\n\n```{{python}}\n#| echo: true\n\nimport matplotlib.pyplot as plt\nplt.plot([1,2,3,4])\nplt.show()\n```\n\nCode block options are included in a special comment at the top of the block (lines at the top prefaced with `#|` are considered options).\n\nOptions available for customizing output include:\n\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| Option | Description |\n+===========+===================================================================================================================================================================================================+\n| `eval` | Evaluate the code chunk (if `false`, just echos the code into the output). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `echo` | Include the source code in output |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `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). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `warning` | Include warnings in the output. |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `error` | Include errors in the output (note that this implies that errors executing code will not halt processing of the document). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `include` | Catch all for preventing any output (code or results) from being included (e.g. `include: false` suppresses all output from the code block). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n\nHere's a Knitr example with some of these additional options included:\n\n```` \n---\ntitle: \"Knitr Document\"\nexecute:\n echo: false\n---\n\n```{{r}}\n#| warning: false\n\nlibrary(ggplot2)\nggplot(airquality, aes(Temp, Ozone)) + \n geom_point() + \n geom_smooth(method = \"loess\", se = FALSE)\n```\n\n```{{r}}\nsummary(airquality)\n```\n````\n\n::: callout-tip\nWhen 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.\n:::\n\n::: callout-tip\nThe Knitr engine can also *conditionally* evaluate a code chunk using objects or expressions. See [Using R: Knitr Options](r.qmd#chunk-options).\n:::\n\n## Figure Options\n\nThere are a number of ways to control the default width and height of figures generated from code. First, it's important to know that Quarto sets a default width and height for figures appropriate to the target output format. Here are the defaults (expressed in inches):\n\n| Format | Default |\n|-------------------------|-----------|\n| Default | 7 x 5 |\n| HTML Slides | 9.5 x 6.5 |\n| HTML Slides (reveal.js) | 9 x 5 |\n| PDF | 5.5 x 3.5 |\n| PDF Slides (Beamer) | 10 x 7 |\n| PowerPoint | 7.5 x 5.5 |\n| MS Word, ODT, RTF | 5 x 4 |\n| EPUB | 5 x 4 |\n| Hugo | 8 x 5 |\n\nThese defaults were chosen to provide attractive well proportioned figures, but feel free to experiment to see whether you prefer another default size. You can change the default sizes using the `fig-width` and `fig-height` options. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: \n html:\n fig-width: 8\n fig-height: 6\n pdf:\n fig-width: 7\n fig-height: 5\n---\n```\n\nHow do these sizes make their way into the engine-level defaults for generating figures? This differs by engine:\n\n- For the Knitr engine, these values become the default values for the `fig.width` and `fig.height` chunk options. You can override these default values via chunk level options.\n\n- For Python, these values are used to set the [Matplotlib](https://matplotlib.org/stable/tutorials/introductory/customizing.html) `figure.figsize` rcParam (you can of course manually override these defaults for any given plot).\n\n- For Julia, these values are used to initialize the default figure size for the [Plots.jl](https://docs.juliaplots.org/stable/) GR backend.\n\n If you are using another graphics library with Jupyter and want to utilize these values, you can read them from `QUARTO_FIG_WIDTH` and `QUARTO_FIG_HEIGHT` environment variables.\n\n::: callout-caution\nWhen using the Knitr engine, `fig-width` and `fig-height` are supported on a per-cell basis. But when using the Jupyter engine, these options only have an effect if specified at the document- or project-level metadata.\n:::\n\n### Caption and Alt Text\n\nYou can specify the caption and alt text for figures generated from code using the `fig-cap` and `fig-alt` options. For example, here we add these options to a Python code cell that creates a plot:\n\n```{{python}}\n#| fig-cap: \"Polar axis plot\"\n#| fig-alt: \"A line plot on a polar axis\"\n\nimport numpy as np\nimport matplotlib.pyplot as plt\n\nr = np.arange(0, 2, 0.01)\ntheta = 2 * np.pi * r\nfig, ax = plt.subplots(subplot_kw={'projection': 'polar'})\nax.plot(theta, r)\nax.set_rticks([0.5, 1, 1.5, 2])\nax.grid(True)\nplt.show()\n```\n\n## Inline Code\n\nJupyter, Knitr and OJS all support executing inline code within markdown (e.g. to allow narrative to automatically use the most up to date computations). See [Inline Code](inline-code.qmd) for details.\n\n## Raw Output\n\nThe `output: asis` option enables you to generate raw markdown output. When `output: asis` is specified none of Quarto's standard enclosing divs will be included. For example, here we specify `output: asis` in order to generate a pair of headings:\n\n::: panel-tabset\n## Jupyter\n\n```{{python}}\n#| echo: false\n#| output: asis\n\nprint(\"# Heading 1\\n\")\nprint(\"## Heading 2\\n\")\n```\n\n## Knitr\n\n```{{r}}\n#| echo: false\n#| output: asis\n\ncat(\"# Heading 1\\n\")\ncat(\"## Heading 2\\n\")\n```\n:::\n\nWhich generates the following output:\n\n``` default\n# Heading 1\n\n## Heading 2\n```\n\nNote that we also include the `echo: false` option to ensure that the code used to generate markdown isn't included in the final output.\n\nIf we had not specified `output: asis` the output, as seen in the intermediate markdown, would have included Quarto's `.cell-output` div:\n\n```` default\n::: {.cell-output-stdout}\n```\n# Heading 1\n\n## Heading 2\n \n```\n:::\n````\n\nFor the Jupyter engine, you can also create raw markdown output using the functions in `IPython.display`. For example:\n\n```{{python}}\n#| echo: false\nradius = 10\nfrom IPython.display import Markdown\nMarkdown(f\"The _radius_ of the circle is **{radius}**.\")\n```\n\n\n## Knitr Options\n\nIf you are using the Knitr cell execution engine, you can specify default document-level [Knitr chunk options](https://yihui.org/knitr/options/) in YAML. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: html\nknitr:\n opts_chunk: \n collapse: true\n comment: \"#>\" \n R.options:\n knitr.graphics.auto_pdf: true\n---\n```\n\nYou can additionally specify global Knitr options using `opts_knit`.\n\nThe `R.options` chunk option is a convenient way to define R options that are set temporarily via [`options()`](https://rdrr.io/r/base/options.html) before the code chunk execution, and immediately restored afterwards.\n\nIn the example above, we establish default Knitr chunk options for a single document. You can also add shared `knitr` options to a project-wide `_quarto.yml` file or a project-directory scoped `_metadata.yml` file.\n\n\n\n## Jupyter Options\n\n### Expression Printing\n\nWhen multiple expressions are present in a code cell, by default, only the last top-level expression is captured in the rendered output. For example, consider the code cell:\n\n::: {layout-ncol=\"2\"}\n```` markdown\n```{{python}}\n\"first\"\n\"last\"\n```\n````\n:::\n\nWhen rendered to HTML the output generated is:\n\n``` markdown\n'last'\n```\n\nThis behavior corresponds to the `last_expr` setting for [Jupyter shell interactivity](https://ipython.readthedocs.io/en/stable/config/options/terminal.html#configtrait-InteractiveShell.ast_node_interactivity).\n\nYou can control this behavior with the `ipynb-shell-interactivity` option. For example, to capture all top-level expressions set it to `all`:\n\n``` yaml\n---\ntitle: All expressions\nformat: html\nipynb-shell-interactivity: all\n---\n```\n\nNow the above code cell results in the output:\n\n``` markdown\n'first'\n\n'last'\n```\n\n::: callout-note\n## All Expressions are Printed in Dashboards\n\nFor [dashboards](/docs/dashboards/index.qmd) the default setting of `ipynb-shell-interactivity` is `all.`\n:::\n\n## Intermediates\n\nOn the way from markdown input to final output, there are some intermediate files that are created and automatically deleted at the end of rendering. You can use the following options to keep these intermediate files:\n\n+--------------+------------------------------------------------------------------------------------------------+\n| Option | Description |\n+==============+================================================================================================+\n| `keep-md` | Keep the markdown file generated by executing code. |\n+--------------+------------------------------------------------------------------------------------------------+\n| `keep-ipynb` | Keep the notebook file generated from executing code (applicable only to markdown input files) |\n+--------------+------------------------------------------------------------------------------------------------+\n\nFor example, here we specify that we want to keep the jupyter intermediate file after rendering:\n\n``` yaml\n---\ntitle: \"My Document\"\nexecute:\n keep-ipynb: true\njupyter: python3\n---\n```\n\n## Fenced Echo\n\nIf you are writing a tutorial or documentation on using Quarto code blocks, you'll likely want to include the fenced code delimiter (e.g. ```` ```{python} ````) in your code output to emphasize that executable code requires that delimiter. You can do this using the `echo: fenced` option. For example, the following code block:\n\n```{{python}}\n#| echo: fenced\n1 + 1\n```\n\nWill be rendered as:\n\n::: {#41c323f9 .cell execution_count=1}\n```` { .cell-code}\n```{{python}}\n1 + 1\n```\n\n````\n\n::: {.cell-output .cell-output-display execution_count=1}\n```\n2\n```\n:::\n:::\n\n\nThis is especially useful when you want to demonstrate the use of cell options. For example, here we demonstrate the use of the `output` and `code-overflow` options:\n\n```{{python}}\n#| echo: fenced\n#| output: false\n#| code-overflow: wrap\n1 + 1\n```\n\nThis code block appears in the rendered document as:\n\n::: {#cbc47400 .cell execution_count=2}\n```` { .cell-code .code-overflow-wrap}\n```{{python}}\n#| output: false\n#| code-overflow: wrap\n1 + 1\n```\n\n````\n:::\n\n\nNote that all YAML options will be included in the fenced code output *except for* `echo: fenced` (as that might be confusing to readers).\n\nThis behavior can also be specified at the document level if you want all of your executable code blocks to include the fenced delimiter and YAML options:\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: html\nexecute:\n echo: fenced\n---\n```\n\n#### Unexecuted Blocks\n\n\n\n\nOften you'll want to include a fenced code block purely as documentation (not executable). You can do this by using two curly braces around the language (e.g. `python`, `r`, etc.) rather than one. For example:\n\n```{{{python}}}\n1 + 1\n```\n\nWill be output into the document as:\n\n```{{python}}\n1 + 1\n```\n\nIf you want to show an example with multiple code blocks and other markdown, just enclose the entire example in 4 backticks (e.g. ````` ```` `````) and use the two curly brace syntax for code blocks within. For example:\n\n ````\n ---\n title: \"My document\"\n ---\n\n Some markdown content.\n\n ```{{{python}}}\n 1 + 1\n ```\n\n Some additional markdown content.\n\n ````\n\n\n\n## Engine Binding\n\nEarlier we said that the engine used for computations was determined automatically. You may want to customize this---for example you may want to use the Jupyter [R kernel](https://github.com/IRkernel/IRkernel) rather than Knitr, or you may want to use Knitr with Python code (via [reticulate](https://rstudio.github.io/reticulate/)).\n\nHere are the basic rules for automatic binding:\n\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| Extension | Engine Binding |\n+===========+========================================================================================================================================================================================================================================+\n| .qmd | Use Knitr engine if an `{r}` code block is discovered within the file |\n| | |\n| | Use Jupyter engine if *any other* executable code block (e.g. `{python}`, `{julia}`, `{bash}`, etc.) is discovered within the file. The kernel used is determined based on the language of the first executable code block discovered. |\n| | |\n| | Use no engine if no executable code blocks are discovered. |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| .ipynb | Jupyter engine |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| .Rmd | Knitr engine |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| .md | No engine (note that if an `md` document does contain executable code blocks then an error will occur) |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n\n::: callout-note\n\n## Using python and r together\n\nIf your quarto document includes both `{python}` and `{r}` code blocks, then quarto will automatically use Knitr engine and [reticulate](https://rstudio.github.io/reticulate/) R package to execute the python content.\n:::\n\nFor `.qmd` files in particular, you can override the engine used via the `engine` option. For example:\n\n``` markdown\nengine: jupyter\n```\n\n``` markdown\nengine: knitr\n```\n\nYou can also specify that no execution engine should be used via `engine: markdown`.\n\nThe presence of the `knitr` or `jupyter` option will also override the default engine:\n\n``` markdown\nknitr: true\n```\n\n``` markdown\njupyter: python3\n```\n\nVariations with additional engine-specific options also work to override the default engine:\n\n``` markdown\nknitr:\n opts_knit:\n verbose: true\n```\n\n``` markdown\njupyter:\n kernelspec:\n display_name: Python 3\n language: python\n name: python3\n```\n\n## Shell Commands\n\nUsing shell commands (from Bash, Zsh, etc.) within Quarto computational documents differs by engine. If you are using the Jupyter engine you can use [Jupyter shell magics](https://jakevdp.github.io/PythonDataScienceHandbook/01.05-ipython-and-shell-commands.html). For example:\n\n```` markdown\n---\ntitle: \"Using Bash\"\nengine: jupyter\n---\n\n```{{python}}\n!echo \"foo\"\n```\n````\n\nNote that `!` preceding `echo` is what enables a Python cell to be able to execute a shell command.\n\nIf you are using the Knitr engine you can use ```` ```{bash} ```` cells, for example:\n\n```` markdown\n---\ntitle: \"Using Bash\"\nengine: knitr\n---\n\n```{{bash}}\necho \"foo\" \n```\n````\n\nNote that the Knitr engine also supports ```` ```{python} ```` cells, enabling the combination of R, Python, and Bash in the same document\n\n", + "markdown": "---\ntitle: Execution Options\nformat: html\n---\n\n## Output Options\n\nThere are a wide variety of options available for customizing output from executed code. All of these options can be specified either globally (in the document front-matter) or per code-block. For example, here's a modification of the Python example to specify that we don't want to \"echo\" the code into the output document:\n\n``` yaml\n---\ntitle: \"My Document\"\nexecute:\n echo: false\njupyter: python3\n---\n```\n\nNote that we can override this option on a per code-block basis. For example:\n\n```{{python}}\n#| echo: true\n\nimport matplotlib.pyplot as plt\nplt.plot([1,2,3,4])\nplt.show()\n```\n\nCode block options are included in a special comment at the top of the block (lines at the top prefaced with `#|` are considered options).\n\nOptions available for customizing output include:\n\n+--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| Option | Description |\n+==============+===================================================================================================================================================================================================+\n| `eval` | Evaluate the code chunk (if `false`, just echos the code into the output). |\n+--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `echo` | Include the source code in output |\n+--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `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). |\n+--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `warning` | Include warnings in the output. |\n+--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `error` | Include errors in the output (note that this implies that errors executing code will not halt processing of the document). |\n+--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `include` | Catch all for preventing any output (code or results) from being included (e.g. `include: false` suppresses all output from the code block). |\n+--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `renderings` | Specify rendering names for the plot or table outputs of the cell, e.g. `[light, dark]` |\n+--------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n\nHere's a Knitr example with some of these additional options included:\n\n```` \n---\ntitle: \"Knitr Document\"\nexecute:\n echo: false\n---\n\n```{{r}}\n#| warning: false\n\nlibrary(ggplot2)\nggplot(airquality, aes(Temp, Ozone)) + \n geom_point() + \n geom_smooth(method = \"loess\", se = FALSE)\n```\n\n```{{r}}\nsummary(airquality)\n```\n````\n\nHere 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.\n\n````\n---\ntitle: \"Dark mode\"\nformat: \n html:\n theme:\n light: flatly\n dark: darkly\n---\n\n```{{r}}\n#| renderings: [light, dark]\npar(bg = \"#FFFFFF\", fg = \"#000000\")\nplot(1:10) # Shown in `light` mode\n\npar(bg = \"#000000\", fg = \"#FFFFFF\", col.axis = \"#FFFFFF\")\nplot(1:10) # Shown in `dark` mode\n```\n````\n\n\n::: {layout-ncol=2}\n\n![light rendering](images/renderings-light-mode.png)\n\n![dark rendering](images/renderings-dark-mode.png)\n\n:::\n\n::: callout-tip\nWhen 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.\n:::\n\n::: callout-tip\nThe Knitr engine can also *conditionally* evaluate a code chunk using objects or expressions. See [Using R: Knitr Options](r.qmd#chunk-options).\n:::\n\n## Figure Options\n\nThere are a number of ways to control the default width and height of figures generated from code. First, it's important to know that Quarto sets a default width and height for figures appropriate to the target output format. Here are the defaults (expressed in inches):\n\n| Format | Default |\n|-------------------------|-----------|\n| Default | 7 x 5 |\n| HTML Slides | 9.5 x 6.5 |\n| HTML Slides (reveal.js) | 9 x 5 |\n| PDF | 5.5 x 3.5 |\n| PDF Slides (Beamer) | 10 x 7 |\n| PowerPoint | 7.5 x 5.5 |\n| MS Word, ODT, RTF | 5 x 4 |\n| EPUB | 5 x 4 |\n| Hugo | 8 x 5 |\n\nThese defaults were chosen to provide attractive well proportioned figures, but feel free to experiment to see whether you prefer another default size. You can change the default sizes using the `fig-width` and `fig-height` options. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: \n html:\n fig-width: 8\n fig-height: 6\n pdf:\n fig-width: 7\n fig-height: 5\n---\n```\n\nHow do these sizes make their way into the engine-level defaults for generating figures? This differs by engine:\n\n- For the Knitr engine, these values become the default values for the `fig.width` and `fig.height` chunk options. You can override these default values via chunk level options.\n\n- For Python, these values are used to set the [Matplotlib](https://matplotlib.org/stable/tutorials/introductory/customizing.html) `figure.figsize` rcParam (you can of course manually override these defaults for any given plot).\n\n- For Julia, these values are used to initialize the default figure size for the [Plots.jl](https://docs.juliaplots.org/stable/) GR backend.\n\n If you are using another graphics library with Jupyter and want to utilize these values, you can read them from `QUARTO_FIG_WIDTH` and `QUARTO_FIG_HEIGHT` environment variables.\n\n::: callout-caution\nWhen using the Jupyter engine, `fig-width` and `fig-height` are only supported if specified at the document- or project-level. \nHowever, when using the Knitr engine, these options are also supported as code cell options on a per-cell basis.\n:::\n\n### Caption and Alt Text\n\nYou can specify the caption and alt text for figures generated from code using the `fig-cap` and `fig-alt` options. For example, here we add these options to a Python code cell that creates a plot:\n\n```{{python}}\n#| fig-cap: \"Polar axis plot\"\n#| fig-alt: \"A line plot on a polar axis\"\n\nimport numpy as np\nimport matplotlib.pyplot as plt\n\nr = np.arange(0, 2, 0.01)\ntheta = 2 * np.pi * r\nfig, ax = plt.subplots(subplot_kw={'projection': 'polar'})\nax.plot(theta, r)\nax.set_rticks([0.5, 1, 1.5, 2])\nax.grid(True)\nplt.show()\n```\n\n## Inline Code\n\nJupyter, Knitr and OJS all support executing inline code within markdown (e.g. to allow narrative to automatically use the most up to date computations). See [Inline Code](inline-code.qmd) for details.\n\n## Raw Output\n\nThe `output: asis` option enables you to generate raw markdown output. When `output: asis` is specified none of Quarto's standard enclosing divs will be included. For example, here we specify `output: asis` in order to generate a pair of headings:\n\n::: panel-tabset\n## Jupyter\n\n```{{python}}\n#| echo: false\n#| output: asis\n\nprint(\"# Heading 1\\n\")\nprint(\"## Heading 2\\n\")\n```\n\n## Knitr\n\n```{{r}}\n#| echo: false\n#| output: asis\n\ncat(\"# Heading 1\\n\")\ncat(\"## Heading 2\\n\")\n```\n:::\n\nWhich generates the following output:\n\n``` default\n# Heading 1\n\n## Heading 2\n```\n\nNote that we also include the `echo: false` option to ensure that the code used to generate markdown isn't included in the final output.\n\nIf we had not specified `output: asis` the output, as seen in the intermediate markdown, would have included Quarto's `.cell-output` div:\n\n```` default\n::: {.cell-output-stdout}\n```\n# Heading 1\n\n## Heading 2\n \n```\n:::\n````\n\nFor the Jupyter engine, you can also create raw markdown output using the functions in `IPython.display`. For example:\n\n```{{python}}\n#| echo: false\nradius = 10\nfrom IPython.display import Markdown\nMarkdown(f\"The _radius_ of the circle is **{radius}**.\")\n```\n\n## Knitr Options\n\nIf you are using the Knitr cell execution engine, you can specify default document-level [Knitr chunk options](https://yihui.org/knitr/options/) in YAML. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: html\nknitr:\n opts_chunk: \n collapse: true\n comment: \"#>\" \n R.options:\n knitr.graphics.auto_pdf: true\n---\n```\n\nYou can additionally specify global Knitr options using `opts_knit`.\n\nThe `R.options` chunk option is a convenient way to define R options that are set temporarily via [`options()`](https://rdrr.io/r/base/options.html) before the code chunk execution, and immediately restored afterwards.\n\nIn the example above, we establish default Knitr chunk options for a single document. You can also add shared `knitr` options to a project-wide `_quarto.yml` file or a project-directory scoped `_metadata.yml` file.\n\n\n## Jupyter Options\n\n### Expression Printing\n\nWhen multiple expressions are present in a code cell, by default, only the last top-level expression is captured in the rendered output. For example, consider the code cell:\n\n::: {layout-ncol=\"2\"}\n```` markdown\n```{{python}}\n\"first\"\n\"last\"\n```\n````\n:::\n\nWhen rendered to HTML the output generated is:\n\n``` markdown\n'last'\n```\n\nThis behavior corresponds to the `last_expr` setting for [Jupyter shell interactivity](https://ipython.readthedocs.io/en/stable/config/options/terminal.html#configtrait-InteractiveShell.ast_node_interactivity).\n\nYou can control this behavior with the `ipynb-shell-interactivity` option. For example, to capture all top-level expressions set it to `all`:\n\n``` yaml\n---\ntitle: All expressions\nformat: html\nipynb-shell-interactivity: all\n---\n```\n\nNow the above code cell results in the output:\n\n``` markdown\n'first'\n\n'last'\n```\n\n::: callout-note\n## All Expressions are Printed in Dashboards\n\nFor [dashboards](/docs/dashboards/index.qmd) the default setting of `ipynb-shell-interactivity` is `all.`\n:::\n\n## Intermediates\n\nOn the way from markdown input to final output, there are some intermediate files that are created and automatically deleted at the end of rendering. You can use the following options to keep these intermediate files:\n\n+--------------+------------------------------------------------------------------------------------------------+\n| Option | Description |\n+==============+================================================================================================+\n| `keep-md` | Keep the markdown file generated by executing code. |\n+--------------+------------------------------------------------------------------------------------------------+\n| `keep-ipynb` | Keep the notebook file generated from executing code (applicable only to markdown input files) |\n+--------------+------------------------------------------------------------------------------------------------+\n\nFor example, here we specify that we want to keep the jupyter intermediate file after rendering:\n\n``` yaml\n---\ntitle: \"My Document\"\nexecute:\n keep-ipynb: true\njupyter: python3\n---\n```\n\n## Fenced Echo\n\nIf you are writing a tutorial or documentation on using Quarto code blocks, you'll likely want to include the fenced code delimiter (e.g. ```` ```{python} ````) in your code output to emphasize that executable code requires that delimiter. You can do this using the `echo: fenced` option. For example, the following code block:\n\n```{{python}}\n#| echo: fenced\n1 + 1\n```\n\nWill be rendered as:\n\n::: {#580ae0c4 .cell execution_count=1}\n```` { .cell-code}\n```{{python}}\n1 + 1\n```\n\n````\n\n::: {.cell-output .cell-output-display execution_count=5}\n```\n2\n```\n:::\n:::\n\n\nThis is especially useful when you want to demonstrate the use of cell options. For example, here we demonstrate the use of the `output` and `code-overflow` options:\n\n```{{python}}\n#| echo: fenced\n#| output: false\n#| code-overflow: wrap\n1 + 1\n```\n\nThis code block appears in the rendered document as:\n\n::: {#3925a895 .cell execution_count=2}\n```` { .cell-code .code-overflow-wrap}\n```{{python}}\n#| output: false\n#| code-overflow: wrap\n1 + 1\n```\n\n````\n:::\n\n\nNote that all YAML options will be included in the fenced code output *except for* `echo: fenced` (as that might be confusing to readers).\n\nThis behavior can also be specified at the document level if you want all of your executable code blocks to include the fenced delimiter and YAML options:\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: html\nexecute:\n echo: fenced\n---\n```\n\n#### Unexecuted Blocks\n\n\n\nOften you'll want to include a fenced code block purely as documentation (not executable). You can do this by using two curly braces around the language (e.g. `python`, `r`, etc.) rather than one. For example:\n\n```{{{python}}}\n1 + 1\n```\n\nWill be output into the document as:\n\n```{{python}}\n1 + 1\n```\n\nIf you want to show an example with multiple code blocks and other markdown, just enclose the entire example in 4 backticks (e.g. ````` ```` `````) and use the two curly brace syntax for code blocks within. For example:\n\n ````\n ---\n title: \"My document\"\n ---\n\n Some markdown content.\n\n ```{{{python}}}\n 1 + 1\n ```\n\n Some additional markdown content.\n\n ````\n\n\n## Engine Binding\n\nEarlier we said that the engine used for computations was determined automatically. You may want to customize this---for example you may want to use the Jupyter [R kernel](https://github.com/IRkernel/IRkernel) rather than Knitr, or you may want to use Knitr with Python code (via [reticulate](https://rstudio.github.io/reticulate/)).\n\nHere are the basic rules for automatic binding:\n\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| Extension | Engine Binding |\n+===========+========================================================================================================================================================================================================================================+\n| .qmd | Use Knitr engine if an `{r}` code block is discovered within the file |\n| | |\n| | Use Jupyter engine if *any other* executable code block (e.g. `{python}`, `{julia}`, `{bash}`, etc.) is discovered within the file. The kernel used is determined based on the language of the first executable code block discovered. |\n| | |\n| | Use no engine if no executable code blocks are discovered. |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| .ipynb | Jupyter engine |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| .Rmd | Knitr engine |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| .md | No engine (note that if an `md` document does contain executable code blocks then an error will occur) |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n\n::: callout-note\n\n## Using python and r together\n\nIf your quarto document includes both `{python}` and `{r}` code blocks, then quarto will automatically use Knitr engine and [reticulate](https://rstudio.github.io/reticulate/) R package to execute the python content.\n:::\n\nFor `.qmd` files in particular, you can override the engine used via the `engine` option. For example:\n\n``` markdown\nengine: jupyter\n```\n\n``` markdown\nengine: knitr\n```\n\nYou can also specify that no execution engine should be used via `engine: markdown`.\n\nThe presence of the `knitr` or `jupyter` option will also override the default engine:\n\n``` markdown\nknitr: true\n```\n\n``` markdown\njupyter: python3\n```\n\nVariations with additional engine-specific options also work to override the default engine:\n\n``` markdown\nknitr:\n opts_knit:\n verbose: true\n```\n\n``` markdown\njupyter:\n kernelspec:\n display_name: Python 3\n language: python\n name: python3\n```\n\n## Shell Commands\n\nUsing shell commands (from Bash, Zsh, etc.) within Quarto computational documents differs by engine. If you are using the Jupyter engine you can use [Jupyter shell magics](https://jakevdp.github.io/PythonDataScienceHandbook/01.05-ipython-and-shell-commands.html). For example:\n\n```` markdown\n---\ntitle: \"Using Bash\"\nengine: jupyter\n---\n\n```{{python}}\n!echo \"foo\"\n```\n````\n\nNote that `!` preceding `echo` is what enables a Python cell to be able to execute a shell command.\n\nIf you are using the Knitr engine you can use ```` ```{bash} ```` cells, for example:\n\n```` markdown\n---\ntitle: \"Using Bash\"\nengine: knitr\n---\n\n```{{bash}}\necho \"foo\" \n```\n````\n\nNote that the Knitr engine also supports ```` ```{python} ```` cells, enabling the combination of R, Python, and Bash in the same document\n\n", "supporting": [ "execution-options_files" ], diff --git a/docs/advanced/typst/brand-yaml.qmd b/docs/advanced/typst/brand-yaml.qmd index 370fcd8f0c..23550d6302 100644 --- 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. @@ -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. diff --git a/docs/authoring/brand.qmd b/docs/authoring/brand.qmd index d11b93aaab..fc9f690c6f 100644 --- 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,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). \ No newline at end of file +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 index fe92672969..b2ed374460 100644 --- 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: @@ -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. ::: diff --git a/docs/computations/images/renderings-dark-mode.png b/docs/computations/images/renderings-dark-mode.png new file mode 100644 index 0000000000..8e67603ba2 Binary files /dev/null and b/docs/computations/images/renderings-dark-mode.png differ diff --git a/docs/computations/images/renderings-light-mode.png b/docs/computations/images/renderings-light-mode.png new file mode 100644 index 0000000000..dbaa6284f6 Binary files /dev/null and b/docs/computations/images/renderings-light-mode.png differ diff --git a/docs/output-formats/html-themes.qmd b/docs/output-formats/html-themes.qmd index 7d440cbe27..0e17860be2 100644 --- 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 index c9394b33cb..9383a3916a 100644 --- 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.