From b3f94d67bd9c2c8f57c6583fc7364ee6530050eb Mon Sep 17 00:00:00 2001 From: Charlotte Wickham Date: Tue, 7 Nov 2023 09:41:29 +1300 Subject: [PATCH] Update freeze --- .../docs/authoring/cross-references/execute-results/html.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_freeze/docs/authoring/cross-references/execute-results/html.json b/_freeze/docs/authoring/cross-references/execute-results/html.json index 3eed21323..dacbb92a5 100644 --- a/_freeze/docs/authoring/cross-references/execute-results/html.json +++ b/_freeze/docs/authoring/cross-references/execute-results/html.json @@ -2,7 +2,7 @@ "hash": "ddc9f0f37fda654fc34636f8b68a4480", "result": { "engine": "jupyter", - "markdown": "---\ntitle: \"Cross References\"\nformat: html\n---\n\n## Overview\n\nCross-references make it easier for readers to navigate your document by providing numbered references and hyperlinks to various entities like figures and tables. Every cross-referenceable entity requires a label (unique identifier prefixed with type e.g. `#fig-element`) and caption (description). For example, this is a cross-referenceable figure:\n\n``` markdown\n![Elephant](elephant.png){#fig-elephant}\n```\n\nThe presence of the caption (`Elephant`) and label (`#fig-elephant`) make this figure referenceable. This enables you to use the following syntax to refer to it elsewhere in the document:\n\n``` markdown\nSee @fig-elephant for an illustration.\n```\n\nHere is what this would look like rendered to HTML:\n\n![](images/crossref-figure.png){.border fig-alt=\"A line drawing of an elephant. The caption 'Figure 1: Elephant' is centered beneath it.\" width=\"100%\"}\n\nQuarto enables you to create cross-references to figures, tables, equations, sections, code listings, theorems, proofs, and more. Cross references can also be applied to dynamic output from Knitr and Jupyter.\n\nNote that cross reference identifiers must start with their type (e.g. `fig-` or `tbl-`). So the identifier `#fig-elephant` is valid for a cross-reference but the identifiers `#elephant` and `#elephant-fig` are not.\n\nThere are options available that control the text used for titles and references. For example, you could change \"Figure 1\" to read \"Fig 1\" or \"fig. 1\". See the [options documentation](#options) for details on how to customize the text used for crossrefs.\n\n::: {.callout-note style=\"padding-bottom: 16px\"}\nQuarto's syntax for cross-references is based on [pandoc-crossref](https://github.com/lierdakil/pandoc-crossref) (which is in turn based on this discussion: ). There are however several differences (mostly related to handling computational output) to note:\n\n1. Quarto uses the prefix `#fig-` rather than `#fig:` (which is more compatible with Jupyter notebook [cell ids](https://jupyter.org/enhancement-proposals/62-cell-id/cell-id.html)).\n2. Quarto is able to reference raw HTML and LaTeX figures and tables (which are often produced by executable code blocks).\n3. Quarto has support for referencing theorems and proofs (and related types).\n:::\n\n## Figures\n\nAs described above, this is the markdown used to create a cross-referenceable figure and then refer to it:\n\n``` markdown\n![Elephant](elephant.png){#fig-elephant}\n\nSee @fig-elephant for an illustration.\n```\n\nNote again that cross-reference identifiers must start with their type (e.g. `#fig-`) and that cross reference identifiers must be all lower case.\n\n### Subfigures\n\nYou may want to create a figure composed of multiple subfigures. To do this, enclose the figures in a div (with its own label and caption) and give each subfigure its own label and (optionally) caption. You can then refer to either the entire figure in a reference or a single subfigure:\n\n``` markdown\n::: {#fig-elephants layout-ncol=2}\n\n![Surus](surus.png){#fig-surus}\n\n![Hanno](hanno.png){#fig-hanno}\n\nFamous Elephants\n:::\n\nSee @fig-elephants for examples. In particular, @fig-hanno.\n```\n\nHere is what this looks like when rendered as HTML:\n\n![](images/crossref-subfigures.png){.preview-image .border 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. The text 'See fig. 1 for examples. In particular, fig. 1(b).' is underneath this text and is aligned to the left.\" width=\"100%\"}\n\nNote that we also used the `layout-ncol` attribute to specify a two-column layout. See the article on [Figures](figures.qmd) for more details on laying out panels of figures.\n\n### Computations\n\nFigures produced by Jupyter and Knitr can also be cross-referenced. To do this, add a `label` and `fig-cap` option at the top of the code block. For example:\n\n::: panel-tabset\n#### Jupyter\n\n ```{{python}}\n #| label: fig-plot\n #| fig-cap: \"Plot\"\n\n import matplotlib.pyplot as plt\n plt.plot([1,23,2,4])\n plt.show()\n ```\n\n For example, see @fig-plot.\n\n![](images/crossref-figure-jupyter.png){fig-alt=\"A line plot with the label 'Figure 1: Plot' centered underneath it. The text 'For example, see fig. 1' is underneath this label and aligned to the left.\"}\n\n#### Knitr\n\n ```{{r}}\n #| label: fig-plot\n #| fig-cap: \"Plot\"\n\n plot(cars)\n ```\n\n For example, see @fig-plot.\n\n![](images/crossref-figure-r.png){fig-alt=\"A scatter plot of speed versus distance for the `cars` dataset. The label 'Figure 1: Plot' is centered beneath it. The text 'For example, see fig. 1' is aligned to the left underneath that.\"}\n:::\n\nYou can also create multiple figures within a code cell and reference them as subfigures. To do this use `fig-cap` for the main caption, and `fig-subcap` to provide an array of subcaptions. For example:\n\n ```{{python}}\n #| label: fig-plots\n #| fig-cap: \"Plots\" \n #| fig-subcap:\n #| - \"Plot 1\"\n #| - \"Plot 2\" \n #| layout-ncol: 2\n\n import matplotlib.pyplot as plt\n plt.plot([1,23,2,4])\n plt.show()\n\n plt.plot([8,65,23,90])\n plt.show()\n ```\n\n See @fig-plots for examples. In particular, @fig-plots-2.\n\n![](images/crossref-subfigures-jupyter.png){fig-alt=\"Two line plots side-by-side. The plot on the left has the caption '(a) Plot 1' centered underneath it. The plot on the right has the caption '(b) Plot 2' centered underneath it. The text 'Figure 1: Plots' is centered underneath both of these plots. The text 'See fig. 1 for examples. In particular, fig. 1(b)' is aligned to the left underneath that.\"}\n\nNote that subfigure reference labels are created automatically based on the main chunk label (e.g. `@fig-plots-1`, `@fig-plots-2`, etc.).\n\nIf you'd like subfigure captions that include only an identifier, e.g. \"(a)\", and not a text caption, then specify `fig-subcap: true` rather than providing explicit subcaption text:\n\n```{{python}}\n#| label: fig-plots\n#| fig-cap: \"Plots\" \n#| fig-subcap: true\n#| layout-ncol: 2\n```\n\n## Tables\n\nFor tables produced by executable code cells, include a label with a `tbl-` prefix to make them cross-referenceable. For example:\n\n::: {#tbl-planets .cell tbl-cap='Planets' execution_count=1}\n```` { .cell-code}\n```{{python}}\n#| label: tbl-planets\n#| tbl-cap: Planets\n\nfrom IPython.display import Markdown\nfrom tabulate import tabulate\ntable = [[\"Sun\",696000,1989100000],\n [\"Earth\",6371,5973.6],\n [\"Moon\",1737,73.5],\n [\"Mars\",3390,641.85]]\nMarkdown(tabulate(\n table, \n headers=[\"Planet\",\"R (km)\", \"mass (x 10^29 kg)\"]\n))\n```\n\n````\n\n::: {.cell-output .cell-output-display .cell-output-markdown execution_count=1}\nPlanet R (km) mass (x 10^29 kg)\n-------- -------- -------------------\nSun 696000 1.9891e+09\nEarth 6371 5973.6\nMoon 1737 73.5\nMars 3390 641.85\n:::\n:::\n\n\n::: callout-important\n## Label Prefix\n\nIn order for a table to be cross-referenceable, its label must start with the `tbl-` prefix.\n:::\n\n{{< include _table-crossrefs.md >}}\n\n### Computations\n\nYou can also cross-reference tables created from code executed via computations. To do this, add the `label` and `tbl-cap` cell options. For example:\n\n```{{r}}\n#| label: tbl-iris\n#| tbl-cap: \"Iris Data\"\n\nlibrary(knitr)\nkable(head(iris))\n```\n\n![](/docs/authoring/images/crossref-table-knitr.png){fig-alt=\"Example table output.\" fig-align=\"center\" width=\"80%\"}\n\nYou can also create multiple tables within a code cell and reference them as subtables. To do this, add a `tbl-subcap` option with an array of subcaptions. For example:\n\n```{{r}}\n#| label: tbl-tables\n#| tbl-cap: \"Tables\"\n#| tbl-subcap:\n#| - \"Cars\"\n#| - \"Pressure\"\n#| layout-ncol: 2\n\nlibrary(knitr)\nkable(head(cars))\nkable(head(pressure))\n```\n\n![](/docs/authoring/images/crossref-subtable-knitr.png){fig-alt=\"Two tables side-by-side. Each table has 2 columns and 8 rows. The table on the left is titled '(a) Cars'. The table on the right is titled '(b) Pressure'. Centered underneath both tables is the text 'Table 1: Tables.'\" fig-align=\"center\" width=\"80%\"}\n\nIf you'd like subtable captions that include only an identifier, e.g. \"(a)\", and not a text caption, then specify `tbl-subcap: true` rather than providing explicit subcaption text:\n\n```{{r}}\n#| label: tbl-tables\n#| tbl-cap: \"Tables\"\n#| tbl-subcap: true\n#| layout-ncol: 2\n\nlibrary(knitr)\nkable(head(cars))\nkable(head(pressure))\n```\n\n![](/docs/authoring/images/crossref-subtable-nocaption-knitr.png){fig-align=\"center\" width=\"80%\"}\n\n## Equations\n\nProvide an `#eq-` label immediately after an equation to make it referenceable. For example:\n\n``` markdown\nBlack-Scholes (@eq-black-scholes) is a mathematical model that seeks to explain the behavior of financial derivatives, most commonly options:\n\n$$\n\\frac{\\partial \\mathrm C}{ \\partial \\mathrm t } + \\frac{1}{2}\\sigma^{2} \\mathrm S^{2}\n\\frac{\\partial^{2} \\mathrm C}{\\partial \\mathrm C^2}\n + \\mathrm r \\mathrm S \\frac{\\partial \\mathrm C}{\\partial \\mathrm S}\\ =\n \\mathrm r \\mathrm C \n$$ {#eq-black-scholes}\n```\n\nBlack-Scholes (@eq-black-scholes) is a mathematical model that seeks to explain the behavior of financial derivatives, most commonly options:\n\n$$\n\\frac{\\partial \\mathrm C}{ \\partial \\mathrm t } + \\frac{1}{2}\\sigma^{2} \\mathrm S^{2}\n\\frac{\\partial^{2} \\mathrm C}{\\partial \\mathrm S^2}\n + \\mathrm r \\mathrm S \\frac{\\partial \\mathrm C}{\\partial \\mathrm S}\\ =\n \\mathrm r \\mathrm C \n$$ {#eq-black-scholes}\n\nNote that the equation number is included (via `\\qquad`) in the right margin of the equation.\n\n## Sections\n\nTo reference a section, add a `#sec-` identifier to any heading. For example:\n\n``` markdown\n## Introduction {#sec-introduction}\n\nSee @sec-introduction for additional context.\n```\n\nNote that when using section cross-references, you will also need to enable the `number-sections` option (so that section numbering is visible to readers). For example:\n\n``` yaml\n---\ntitle: \"My Document\"\nnumber-sections: true\n---\n```\n\n## Code Listings\n\nTo create a reference-able code block, add a `#lst-` identifier along with a `lst-cap` attribute. For example:\n\n```` markdown\n```{#lst-customers .sql lst-cap=\"Customers Query\"}\nSELECT * FROM Customers\n```\n\nThen we query the customers database (@lst-customers).\n````\n\n::: {.callout-note}\n\nNote that code listings currently only work with _display code blocks_ (as opposed to executable code blocks). If you wish to both execute and reference a code block, use a combination of a display block and a code block with `echo: false` in the cell YAML.\n\n:::\n\n\n\n## Theorems and Proofs\n\nTheorems are commonly used in articles and books in mathematics. To include a reference-able theorem, create a div with a `#thm-` label (or one of other theorem-type labels described below). You also need to specify a theorem name either via the first heading in the block. You can include any content you like within the div. For example:\n\n``` markdown\n::: {#thm-line}\n\n## Line\n\nThe equation of any straight line, called a linear equation, can be written as:\n\n$$\ny = mx + b\n$$\n:::\n\nSee @thm-line.\n```\n\n![](images/crossref-theorem.png){fig-alt=\"A snippet of a LaTeX document. The first line reads: 'Thereom 1 (Line) The equation of any straight line, called a linear equation, can be written as:' Cenetered on a separate line is the equation 'y = mx + b'. The text 'See thm. 1' is aligned to the left underneath that.\"}\n\nFor LaTeX output, the [amsthm](https://ctan.org/pkg/amsthm?lang=en) package is used for typesetting theorems. For other formats an appropriate treatment is used (the above is an example of HTML output).\n\nThere are a number of theorem variations supported, each with their own label prefix:\n\n| **Label Prefix** | **Printed Name** | **LaTeX Environment** |\n|------------------|------------------|-----------------------|\n| `#thm-` | Theorem | theorem |\n| `#lem-` | Lemma | lemma |\n| `#cor-` | Corollary | corollary |\n| `#prp-` | Proposition | proposition |\n| `#cnj-` | Conjecture | conjecture |\n| `#def-` | Definition | definition |\n| `#exm-` | Example | example |\n| `#exr-` | Exercise | exercise |\n\nThe `proof`, `remark`, and `solution` environments generally receive similar typesetting as theorems, however they are not numbered (and therefore cannot be cross-referenced). To create these environments just use them as the class name of a div:\n\n``` markdown\n::: {.solution}\nThe solution.\n:::\n```\n\nAs with theorems you can optionally include a heading as the first element of the div (or a `name` attribute) to give the environment a caption for typesetting (this typically appears in parentheses after the environment title).\n\nFor LaTeX output the [amsthm](https://ctan.org/pkg/amsthm?lang=en) package is used to typeset these environments. For other formats a similar treatment is used, but you can further customizing this using CSS.\n\n## References\n\nThe examples above have all used the default syntax for inline references (e.g. `@fig-elephant`), which results in the reference text \"Figure 1\", \"Table 1\", etc.\n\nYou can customize the appearance of inline references by either changing the syntax of the inline reference or by setting options. Here are the various ways to compose a cross-reference and their resulting output:\n\n| Type | Syntax | Output |\n|---------------|-----------------------|----------|\n| Default | `@fig-elephant` | Figure 1 |\n| Capitalized | `@Fig-elephant` | Figure 1 |\n| Custom Prefix | `[Fig @fig-elephant]` | Fig 1 |\n| No Prefix | `[-@fig-elephant]` | 1 |\n\nNote that the capitalized syntax makes no difference for the default output, but would indeed capitalize the first letter if the default had been change via an option to use lower case (e.g. \"fig.\").\n\nYou can also group cross references using the following syntax:\n\n``` markdown\nAs illustrated in [@fig-elephant; @fig-panther; @fig-rabbit].\n```\n\nThere are a number of options that can be used to further customize the treatment of cross-references. See the section below on [References Options](#references-1) for additional details.\n\n## Chapter Numbering\n\nYou can use the `crossref: chapters` option to indicate that top-level headings (H1) in your document correspond to chapters, and that cross-references should be sub-numbered by chapter. For example:\n\n``` markdown\n---\ntitle: \"My Document\"\nauthor: \"Jane Doe\"\nnumber-sections: true\ncrossref:\n chapters: true\n---\n\n# Introduction\n\n![Elephant](elephant.png){#fig-elephant}\n\nSee @fig-elephant for an illustration.\n```\n\n![](images/crossref-chapters.png){fig-alt=\"A line drawing of an elephant. Above it is the text '1 Introduction' in large, bold font. The label 'Figure 1.1: Elephant' is centered underneath it. The text 'See fig. 1.1 for an illustration' is aligned to the left underneath that.\"}\n\n## Lists\n\nFor LaTeX / PDF output, you can use the raw LaTeX commands `\\listoffigures`, `\\listoftables` and `\\listoflistings` to produce listings of all figures, tables, etc. within a document. You can use the `lof-title`, `lot-title`, and `lol-title` crossref options to customize the title of the listing.\n\nFor example:\n\n``` markdown\n---\ntitle: \"My Document\"\ncrossref:\n lof-title: \"List of Figures\"\nformat: pdf\n---\n\n\\listoffigures\n```\n\nNote that the default titles for the lists use the form displayed above (i.e. \"List of \\\").\n\n## Options {#options}\n\nThere are a wide variety of options available for customizing caption labels and references. These options are all specified within the `crossref` key of document metadata.\n\n::: {.callout-note appearance=\"simple\"}\nNote that since LaTeX does its own formatting and layout of figures and tables, not all of these options will apply when rendering to PDF. Specifically, delimiter options like `title-delim` and numbering options like `labels` don't work for PDF output. Additionally, formatting directives are not applied (e.g. italicizing the figure title) for LaTeX titles.\n:::\n\n### Titles\n\nYou can specify the title prefix used for captions using `*-title` options. You can also specify the delimiter used between the prefix and the caption using the `title-delim` option. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\ncrossref:\n fig-title: Fig # (default is \"Figure\")\n tbl-title: Tbl # (default is \"Table\")\n title-delim: \"—\" # (default is \":\")\n---\n```\n\n### References {#references-1}\n\nYou can specify the prefix used for inline reference type using `*-prefix` options. You can also specify whether references should be hyper-linked using the `ref-hyperlink` option. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\ncrossref:\n fig-prefix: figure # (default is \"Figure\")\n tbl-prefix: table # (default is \"Table\")\n ref-hyperlink: false # (default is true)\n---\n```\n\n### Numbering\n\nThere are a variety of numbering schemes available for cross-references, including:\n\n- `arabic` (1, 2, 3)\n\n- `roman` (I, II, III, IV)\n\n- `roman i` (i, ii, iii, iv)\n\n- `alpha x` (start from letter 'x')\n\n- `alpha X` (start from letter 'X')\n\nYou can specify the number scheme used for all types (other than sub-references) using the `labels` option. For sub-references (e.g. subfigures), you can specify the number scheme using the `subref-labels` option. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\ncrossref:\n labels: alpha a # (default is arabic)\n subref-labels: roman i # (default is alpha a)\n---\n```\n\nIf you would like, you can specify the number scheme for a specific type using the `*-labels` options. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\ncrossref:\n fig-labels: alpha a # (default is arabic)\n tbl-labels: alpha a # (default is arabic)\n subref-labels: roman i # (default is alpha a)\n---\n```\n\nIf both `labels` and a type specific label option is provided, the type specific option will override the `labels` option.\n\n", + "markdown": "---\ntitle: \"Cross References\"\nformat: html\n---\n\n## Overview\n\nCross-references make it easier for readers to navigate your document by providing numbered references and hyperlinks to various entities like figures and tables. Every cross-referenceable entity requires a label (unique identifier prefixed with type e.g. `#fig-element`) and caption (description). For example, this is a cross-referenceable figure:\n\n``` markdown\n![Elephant](elephant.png){#fig-elephant}\n```\n\nThe presence of the caption (`Elephant`) and label (`#fig-elephant`) make this figure referenceable. This enables you to use the following syntax to refer to it elsewhere in the document:\n\n``` markdown\nSee @fig-elephant for an illustration.\n```\n\nHere is what this would look like rendered to HTML:\n\n![](images/crossref-figure.png){.border fig-alt=\"A line drawing of an elephant. The caption 'Figure 1: Elephant' is centered beneath it.\" width=\"100%\"}\n\nQuarto enables you to create cross-references to figures, tables, equations, sections, code listings, theorems, proofs, and more. Cross references can also be applied to dynamic output from Knitr and Jupyter.\n\nNote that cross reference identifiers must start with their type (e.g. `fig-` or `tbl-`). So the identifier `#fig-elephant` is valid for a cross-reference but the identifiers `#elephant` and `#elephant-fig` are not.\n\nThere are options available that control the text used for titles and references. For example, you could change \"Figure 1\" to read \"Fig 1\" or \"fig. 1\". See the [options documentation](#options) for details on how to customize the text used for crossrefs.\n\n::: {.callout-note style=\"padding-bottom: 16px\"}\nQuarto's syntax for cross-references is based on [pandoc-crossref](https://github.com/lierdakil/pandoc-crossref) (which is in turn based on this discussion: ). There are however several differences (mostly related to handling computational output) to note:\n\n1. Quarto uses the prefix `#fig-` rather than `#fig:` (which is more compatible with Jupyter notebook [cell ids](https://jupyter.org/enhancement-proposals/62-cell-id/cell-id.html)).\n2. Quarto is able to reference raw HTML and LaTeX figures and tables (which are often produced by executable code blocks).\n3. Quarto has support for referencing theorems and proofs (and related types).\n:::\n\n## Figures\n\nAs described above, this is the markdown used to create a cross-referenceable figure and then refer to it:\n\n``` markdown\n![Elephant](elephant.png){#fig-elephant}\n\nSee @fig-elephant for an illustration.\n```\n\nNote again that cross-reference identifiers must start with their type (e.g. `#fig-`) and that cross reference identifiers must be all lower case.\n\n### Subfigures\n\nYou may want to create a figure composed of multiple subfigures. To do this, enclose the figures in a div (with its own label and caption) and give each subfigure its own label and (optionally) caption. You can then refer to either the entire figure in a reference or a single subfigure:\n\n``` markdown\n::: {#fig-elephants layout-ncol=2}\n\n![Surus](surus.png){#fig-surus}\n\n![Hanno](hanno.png){#fig-hanno}\n\nFamous Elephants\n:::\n\nSee @fig-elephants for examples. In particular, @fig-hanno.\n```\n\nHere is what this looks like when rendered as HTML:\n\n![](images/crossref-subfigures.png){.preview-image .border 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. The text 'See fig. 1 for examples. In particular, fig. 1(b).' is underneath this text and is aligned to the left.\" width=\"100%\"}\n\nNote that we also used the `layout-ncol` attribute to specify a two-column layout. See the article on [Figures](figures.qmd) for more details on laying out panels of figures.\n\n### Computations\n\nFigures produced by Jupyter and Knitr can also be cross-referenced. To do this, add a `label` and `fig-cap` option at the top of the code block. For example:\n\n::: panel-tabset\n#### Jupyter\n\n ```{{python}}\n #| label: fig-plot\n #| fig-cap: \"Plot\"\n\n import matplotlib.pyplot as plt\n plt.plot([1,23,2,4])\n plt.show()\n ```\n\n For example, see @fig-plot.\n\n![](images/crossref-figure-jupyter.png){fig-alt=\"A line plot with the label 'Figure 1: Plot' centered underneath it. The text 'For example, see fig. 1' is underneath this label and aligned to the left.\"}\n\n#### Knitr\n\n ```{{r}}\n #| label: fig-plot\n #| fig-cap: \"Plot\"\n\n plot(cars)\n ```\n\n For example, see @fig-plot.\n\n![](images/crossref-figure-r.png){fig-alt=\"A scatter plot of speed versus distance for the `cars` dataset. The label 'Figure 1: Plot' is centered beneath it. The text 'For example, see fig. 1' is aligned to the left underneath that.\"}\n:::\n\nYou can also create multiple figures within a code cell and reference them as subfigures. To do this use `fig-cap` for the main caption, and `fig-subcap` to provide an array of subcaptions. For example:\n\n ```{{python}}\n #| label: fig-plots\n #| fig-cap: \"Plots\" \n #| fig-subcap:\n #| - \"Plot 1\"\n #| - \"Plot 2\" \n #| layout-ncol: 2\n\n import matplotlib.pyplot as plt\n plt.plot([1,23,2,4])\n plt.show()\n\n plt.plot([8,65,23,90])\n plt.show()\n ```\n\n See @fig-plots for examples. In particular, @fig-plots-2.\n\n![](images/crossref-subfigures-jupyter.png){fig-alt=\"Two line plots side-by-side. The plot on the left has the caption '(a) Plot 1' centered underneath it. The plot on the right has the caption '(b) Plot 2' centered underneath it. The text 'Figure 1: Plots' is centered underneath both of these plots. The text 'See fig. 1 for examples. In particular, fig. 1(b)' is aligned to the left underneath that.\"}\n\nNote that subfigure reference labels are created automatically based on the main chunk label (e.g. `@fig-plots-1`, `@fig-plots-2`, etc.).\n\nIf you'd like subfigure captions that include only an identifier, e.g. \"(a)\", and not a text caption, then specify `fig-subcap: true` rather than providing explicit subcaption text:\n\n```{{python}}\n#| label: fig-plots\n#| fig-cap: \"Plots\" \n#| fig-subcap: true\n#| layout-ncol: 2\n```\n\n## Tables\n\nFor tables produced by executable code cells, include a label with a `tbl-` prefix to make them cross-referenceable. For example:\n\n::: {#tbl-planets .cell tbl-cap='Planets' execution_count=1}\n```` { .cell-code}\n```{{python}}\n#| label: tbl-planets\n#| tbl-cap: Planets\n\nfrom IPython.display import Markdown\nfrom tabulate import tabulate\ntable = [[\"Sun\",696000,1989100000],\n [\"Earth\",6371,5973.6],\n [\"Moon\",1737,73.5],\n [\"Mars\",3390,641.85]]\nMarkdown(tabulate(\n table, \n headers=[\"Planet\",\"R (km)\", \"mass (x 10^29 kg)\"]\n))\n```\n\n````\n\n::: {.cell-output .cell-output-display .cell-output-markdown execution_count=1}\nPlanet R (km) mass (x 10^29 kg)\n-------- -------- -------------------\nSun 696000 1.9891e+09\nEarth 6371 5973.6\nMoon 1737 73.5\nMars 3390 641.85\n:::\n:::\n\n\n::: callout-important\n## Label Prefix\n\nIn order for a table to be cross-referenceable, its label must start with the `tbl-` prefix.\n:::\n\n\n\nFor markdown tables, add a caption below the table, then include a `#tbl-` label in braces at the end of the caption. For example:\n\n``` markdown\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: My Caption {#tbl-letters}\n\nSee @tbl-letters.\n```\n\nWhich looks like this when rendered to HTML:\n\n![](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\"}\n\n\n### Subtables\n\nYou may want to create a composition of several sub-tables. To do this, create a div with a main identifier, then apply sub-identifiers (and optional caption text) to the contained tables. For example:\n\n``` markdown\n::: {#tbl-panel layout-ncol=2}\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: First Table {#tbl-first}\n\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: Second Table {#tbl-second}\n\nMain Caption\n:::\n\nSee @tbl-panel for details, especially @tbl-second.\n```\n\nWhich looks like this when rendered to HTML:\n\n![](/docs/authoring/images/crossref-subtable.png){fig-alt=\"Two tables side-by-side. Both tables have 3 columns and 4 rows. The table on the left is titled '(a) First table'. The table on the right is titled '(b) Second Table'. Centered underneath both tables is the text 'Table 1: Main Caption'. The text 'See tbl. 2 for details, especially tbl. 2 (b)' is aligned to the left underneath that.\"}\n\nNote that the \"Main Caption\" for the table is provided as the last block within the containing div.\n\n\n\n### Computations\n\nYou can also cross-reference tables created from code executed via computations. To do this, add the `label` and `tbl-cap` cell options. For example:\n\n```{{r}}\n#| label: tbl-iris\n#| tbl-cap: \"Iris Data\"\n\nlibrary(knitr)\nkable(head(iris))\n```\n\n![](/docs/authoring/images/crossref-table-knitr.png){fig-alt=\"Example table output.\" fig-align=\"center\" width=\"80%\"}\n\nYou can also create multiple tables within a code cell and reference them as subtables. To do this, add a `tbl-subcap` option with an array of subcaptions. For example:\n\n```{{r}}\n#| label: tbl-tables\n#| tbl-cap: \"Tables\"\n#| tbl-subcap:\n#| - \"Cars\"\n#| - \"Pressure\"\n#| layout-ncol: 2\n\nlibrary(knitr)\nkable(head(cars))\nkable(head(pressure))\n```\n\n![](/docs/authoring/images/crossref-subtable-knitr.png){fig-alt=\"Two tables side-by-side. Each table has 2 columns and 8 rows. The table on the left is titled '(a) Cars'. The table on the right is titled '(b) Pressure'. Centered underneath both tables is the text 'Table 1: Tables.'\" fig-align=\"center\" width=\"80%\"}\n\nIf you'd like subtable captions that include only an identifier, e.g. \"(a)\", and not a text caption, then specify `tbl-subcap: true` rather than providing explicit subcaption text:\n\n```{{r}}\n#| label: tbl-tables\n#| tbl-cap: \"Tables\"\n#| tbl-subcap: true\n#| layout-ncol: 2\n\nlibrary(knitr)\nkable(head(cars))\nkable(head(pressure))\n```\n\n![](/docs/authoring/images/crossref-subtable-nocaption-knitr.png){fig-align=\"center\" width=\"80%\"}\n\n## Equations\n\nProvide an `#eq-` label immediately after an equation to make it referenceable. For example:\n\n``` markdown\nBlack-Scholes (@eq-black-scholes) is a mathematical model that seeks to explain the behavior of financial derivatives, most commonly options:\n\n$$\n\\frac{\\partial \\mathrm C}{ \\partial \\mathrm t } + \\frac{1}{2}\\sigma^{2} \\mathrm S^{2}\n\\frac{\\partial^{2} \\mathrm C}{\\partial \\mathrm C^2}\n + \\mathrm r \\mathrm S \\frac{\\partial \\mathrm C}{\\partial \\mathrm S}\\ =\n \\mathrm r \\mathrm C \n$$ {#eq-black-scholes}\n```\n\nBlack-Scholes (@eq-black-scholes) is a mathematical model that seeks to explain the behavior of financial derivatives, most commonly options:\n\n$$\n\\frac{\\partial \\mathrm C}{ \\partial \\mathrm t } + \\frac{1}{2}\\sigma^{2} \\mathrm S^{2}\n\\frac{\\partial^{2} \\mathrm C}{\\partial \\mathrm S^2}\n + \\mathrm r \\mathrm S \\frac{\\partial \\mathrm C}{\\partial \\mathrm S}\\ =\n \\mathrm r \\mathrm C \n$$ {#eq-black-scholes}\n\nNote that the equation number is included (via `\\qquad`) in the right margin of the equation.\n\n## Sections\n\nTo reference a section, add a `#sec-` identifier to any heading. For example:\n\n``` markdown\n## Introduction {#sec-introduction}\n\nSee @sec-introduction for additional context.\n```\n\nNote that when using section cross-references, you will also need to enable the `number-sections` option (so that section numbering is visible to readers). For example:\n\n``` yaml\n---\ntitle: \"My Document\"\nnumber-sections: true\n---\n```\n\n## Code Listings\n\nTo create a reference-able code block, add a `#lst-` identifier along with a `lst-cap` attribute. For example:\n\n```` markdown\n```{#lst-customers .sql lst-cap=\"Customers Query\"}\nSELECT * FROM Customers\n```\n\nThen we query the customers database (@lst-customers).\n````\n\n::: {.callout-note}\n\nNote that code listings currently only work with _display code blocks_ (as opposed to executable code blocks). If you wish to both execute and reference a code block, use a combination of a display block and a code block with `echo: false` in the cell YAML.\n\n:::\n\n\n\n## Theorems and Proofs\n\nTheorems are commonly used in articles and books in mathematics. To include a reference-able theorem, create a div with a `#thm-` label (or one of other theorem-type labels described below). You also need to specify a theorem name either via the first heading in the block. You can include any content you like within the div. For example:\n\n``` markdown\n::: {#thm-line}\n\n## Line\n\nThe equation of any straight line, called a linear equation, can be written as:\n\n$$\ny = mx + b\n$$\n:::\n\nSee @thm-line.\n```\n\n![](images/crossref-theorem.png){fig-alt=\"A snippet of a LaTeX document. The first line reads: 'Thereom 1 (Line) The equation of any straight line, called a linear equation, can be written as:' Cenetered on a separate line is the equation 'y = mx + b'. The text 'See thm. 1' is aligned to the left underneath that.\"}\n\nFor LaTeX output, the [amsthm](https://ctan.org/pkg/amsthm?lang=en) package is used for typesetting theorems. For other formats an appropriate treatment is used (the above is an example of HTML output).\n\nThere are a number of theorem variations supported, each with their own label prefix:\n\n| **Label Prefix** | **Printed Name** | **LaTeX Environment** |\n|------------------|------------------|-----------------------|\n| `#thm-` | Theorem | theorem |\n| `#lem-` | Lemma | lemma |\n| `#cor-` | Corollary | corollary |\n| `#prp-` | Proposition | proposition |\n| `#cnj-` | Conjecture | conjecture |\n| `#def-` | Definition | definition |\n| `#exm-` | Example | example |\n| `#exr-` | Exercise | exercise |\n\nThe `proof`, `remark`, and `solution` environments generally receive similar typesetting as theorems, however they are not numbered (and therefore cannot be cross-referenced). To create these environments just use them as the class name of a div:\n\n``` markdown\n::: {.solution}\nThe solution.\n:::\n```\n\nAs with theorems you can optionally include a heading as the first element of the div (or a `name` attribute) to give the environment a caption for typesetting (this typically appears in parentheses after the environment title).\n\nFor LaTeX output the [amsthm](https://ctan.org/pkg/amsthm?lang=en) package is used to typeset these environments. For other formats a similar treatment is used, but you can further customizing this using CSS.\n\n## References\n\nThe examples above have all used the default syntax for inline references (e.g. `@fig-elephant`), which results in the reference text \"Figure 1\", \"Table 1\", etc.\n\nYou can customize the appearance of inline references by either changing the syntax of the inline reference or by setting options. Here are the various ways to compose a cross-reference and their resulting output:\n\n| Type | Syntax | Output |\n|---------------|-----------------------|----------|\n| Default | `@fig-elephant` | Figure 1 |\n| Capitalized | `@Fig-elephant` | Figure 1 |\n| Custom Prefix | `[Fig @fig-elephant]` | Fig 1 |\n| No Prefix | `[-@fig-elephant]` | 1 |\n\nNote that the capitalized syntax makes no difference for the default output, but would indeed capitalize the first letter if the default had been change via an option to use lower case (e.g. \"fig.\").\n\nYou can also group cross references using the following syntax:\n\n``` markdown\nAs illustrated in [@fig-elephant; @fig-panther; @fig-rabbit].\n```\n\nThere are a number of options that can be used to further customize the treatment of cross-references. See the section below on [References Options](#references-1) for additional details.\n\n## Chapter Numbering\n\nYou can use the `crossref: chapters` option to indicate that top-level headings (H1) in your document correspond to chapters, and that cross-references should be sub-numbered by chapter. For example:\n\n``` markdown\n---\ntitle: \"My Document\"\nauthor: \"Jane Doe\"\nnumber-sections: true\ncrossref:\n chapters: true\n---\n\n# Introduction\n\n![Elephant](elephant.png){#fig-elephant}\n\nSee @fig-elephant for an illustration.\n```\n\n![](images/crossref-chapters.png){fig-alt=\"A line drawing of an elephant. Above it is the text '1 Introduction' in large, bold font. The label 'Figure 1.1: Elephant' is centered underneath it. The text 'See fig. 1.1 for an illustration' is aligned to the left underneath that.\"}\n\n## Lists\n\nFor LaTeX / PDF output, you can use the raw LaTeX commands `\\listoffigures`, `\\listoftables` and `\\listoflistings` to produce listings of all figures, tables, etc. within a document. You can use the `lof-title`, `lot-title`, and `lol-title` crossref options to customize the title of the listing.\n\nFor example:\n\n``` markdown\n---\ntitle: \"My Document\"\ncrossref:\n lof-title: \"List of Figures\"\nformat: pdf\n---\n\n\\listoffigures\n```\n\nNote that the default titles for the lists use the form displayed above (i.e. \"List of \\\").\n\n## Options {#options}\n\nThere are a wide variety of options available for customizing caption labels and references. These options are all specified within the `crossref` key of document metadata.\n\n::: {.callout-note appearance=\"simple\"}\nNote that since LaTeX does its own formatting and layout of figures and tables, not all of these options will apply when rendering to PDF. Specifically, delimiter options like `title-delim` and numbering options like `labels` don't work for PDF output. Additionally, formatting directives are not applied (e.g. italicizing the figure title) for LaTeX titles.\n:::\n\n### Titles\n\nYou can specify the title prefix used for captions using `*-title` options. You can also specify the delimiter used between the prefix and the caption using the `title-delim` option. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\ncrossref:\n fig-title: Fig # (default is \"Figure\")\n tbl-title: Tbl # (default is \"Table\")\n title-delim: \"—\" # (default is \":\")\n---\n```\n\n### References {#references-1}\n\nYou can specify the prefix used for inline reference type using `*-prefix` options. You can also specify whether references should be hyper-linked using the `ref-hyperlink` option. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\ncrossref:\n fig-prefix: figure # (default is \"Figure\")\n tbl-prefix: table # (default is \"Table\")\n ref-hyperlink: false # (default is true)\n---\n```\n\n### Numbering\n\nThere are a variety of numbering schemes available for cross-references, including:\n\n- `arabic` (1, 2, 3)\n\n- `roman` (I, II, III, IV)\n\n- `roman i` (i, ii, iii, iv)\n\n- `alpha x` (start from letter 'x')\n\n- `alpha X` (start from letter 'X')\n\nYou can specify the number scheme used for all types (other than sub-references) using the `labels` option. For sub-references (e.g. subfigures), you can specify the number scheme using the `subref-labels` option. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\ncrossref:\n labels: alpha a # (default is arabic)\n subref-labels: roman i # (default is alpha a)\n---\n```\n\nIf you would like, you can specify the number scheme for a specific type using the `*-labels` options. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\ncrossref:\n fig-labels: alpha a # (default is arabic)\n tbl-labels: alpha a # (default is arabic)\n subref-labels: roman i # (default is alpha a)\n---\n```\n\nIf both `labels` and a type specific label option is provided, the type specific option will override the `labels` option.\n\n", "supporting": [ "cross-references_files" ],