diff --git a/_freeze/docs/authoring/cross-references/execute-results/html.json b/_freeze/docs/authoring/cross-references/execute-results/html.json index 42115c4902..a8b34b5957 100644 --- a/_freeze/docs/authoring/cross-references/execute-results/html.json +++ b/_freeze/docs/authoring/cross-references/execute-results/html.json @@ -1,8 +1,8 @@ { - "hash": "734233a780ad4c5ef9d0926679714c73", + "hash": "ef3190005aac9766972a9802450db689", "result": { "engine": "jupyter", - "markdown": "---\ntitle: \"Cross References\"\nformat: html\ntoc-expand: 2\ntoc-depth: 4\naliases: \n - /docs/authoring/cross-references-listings.html\n - /docs/authoring/cross-references-callouts.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---a unique identifier prefixed with a cross-reference type e.g. `#fig-element`. For example, this is a cross-referenceable figure:\n\n``` markdown\n![Elephant](elephant.png){#fig-elephant}\n```\n\nThe presence of the label (`#fig-elephant`) makes 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\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\n::: {#reserved-prefixes}\n::: {.callout-warning}\n\n## Reserved Prefixes \n\nUnless you are creating a cross-reference, avoid using the reserved cross-reference prefixes for code cell labels (e.g. set using the `label` code cell option) and element IDs (set using a `#` in an attribute). \n \nThe reserved prefixes are: `fig`, `tbl`, `lst`, `tip`, `nte`, `wrn`, `imp`, `cau`, `thm`, `lem`, `cor`, `prp`, `cnj`, `def`, `exm`, `exr`, `sol`, `rem`, `eq`, `sec`.\n\nAlso avoid using underscores (`_`) in labels and IDs as this can cause problems when rendering to PDF with LaTeX.\n\n:::\n:::\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\nOn this page you'll learn:\n\n* Different ways to use the `@` syntax to create [References](#references).\n* How to add [Lists](#lists) of references in LaTeX / PDF output.\n\nThen, we enumerate the syntax for the different types of elements you might want to reference:\n\n* [Floats](#floats): [Figures](#figures), [Tables](#tables) and [Code Listings](#code-listings)\n* Blocks: [Callouts](#callouts), [Theorems and Proofs](#theorems-and-proofs) and [Equations](#equations) \n* [Sections](#sections)\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](cross-reference-options.qmd) for details on how to customize the text used for cross-references.\n\n## References\n\nThe examples on this page all use 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 prefix had been changed via an [option](cross-reference-options.qmd#references) to use lower case (e.g. \"fig.\").\n\nThese syntax variations work not only for Figures, but for all cross-referenceable elements in Quarto such as Tables, Equations, Theorems, and so on.\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 guide on [Cross Reference Options](cross-reference-options.qmd#references) for additional details.\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## Floats\n\n[Figures](#figures), [tables](#tables) and [code listings](#code-listings) are known as \"float\" cross-references. Floats can appear in the rendered document at locations other than where they are defined, i.e. they float, and usually have captions. \n\nIn addition to the compact syntax for the most common uses of float cross-references, you can also define float cross-references with a div syntax. Use the div syntax when you need more flexibility in the content of your cross-reference, for example, to have a [video](cross-references-divs.qmd#videos) be referenced as a figure. Basic examples of the div syntax are included in the sections below, but you can find more complicated examples in [Cross-Reference Div Syntax](cross-references-divs.qmd). \n\nYou can also define custom types of float cross-reference to reference elements beyond figures, tables and code listings. Read more at [Custom Float Cross-References](cross-references-custom.qmd).\n\n\n### Figures\n\nAs described on the Overview 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\nTo create a cross-reference to a figure using div syntax, create a fenced div with an id starting with `fig-`, include the image followed by the caption inside the div:\n\n````markdown\n::: {#fig-elephant}\n\n![](elephant.png)\n\nAn Elephant\n:::\n````\n\n\n\nYou can read about using div syntax with figures at [Cross-Reference Div Syntax](cross-references-divs.qmd#figures).\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\n::: {.callout-tip}\n\n## Computed Captions\n\nIf you need to generate a dynamic caption, instead of using the `fig-cap` or `tbl-cap` code cell option, combine inline code with the [Cross-Reference Div Syntax](/docs/authoring/cross-references-divs.qmd#computed-captions).\n\n:::\n\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\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\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\nTo create a cross-reference to a table using div syntax, create a fenced div with an id starting with `tbl-`, include the table followed by the caption inside the div:\n\n````markdown\n::: {#tbl-letters}\n\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\nMy Caption\n\n::: \n````\n\n\n\nYou can read more about using div syntax with tables at [Cross-Reference Div Syntax](cross-references-divs.qmd#tables).\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\n::: {.callout-tip}\n\n## Computed Captions\n\nIf you need to generate a dynamic caption, instead of using the `fig-cap` or `tbl-cap` code cell option, combine inline code with the [Cross-Reference Div Syntax](/docs/authoring/cross-references-divs.qmd#computed-captions).\n\n:::\n\n\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\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\nTo create a cross-reference to a code listing using div syntax, create a fenced div with an id starting with `lst-`, include the code cell followed by the caption inside the div: \n\n````markdown\n::: {#lst-customers}\n\n```{.sql}\nSELECT * FROM Customers\n```\n\nCustomers Query\n\n:::\n````\n\n\n\nYou can read more about using div syntax for code listings in [Cross-Reference Div Syntax](cross-references-divs.qmd).\n\nTo cross-reference code from an executable code block, add the code cell options `lst-label` and `lst-cap`. The option `lst-label` provides the cross reference identifier and must begin with the prefix `lst-` to be treated as a code listing. The value of `lst-cap` provides the caption for the code listing. For example:\n\n````{.markdown}\n```{{python}}\n#| lst-label: lst-import\n#| lst-cap: Import pyplot\n\nimport matplotlib.pyplot as plt\n```\n\n@lst-import...\n````\n\nWhen rendered, this results in the following:\n\n::: {.border .p-3}\n\n::: {#0cdd1d30 .cell execution_count=1}\n``` {#lst-import .python .cell-code lst-cap=\"Import pyplot\"}\nimport matplotlib.pyplot as plt\n```\n:::\n\n\n@lst-import...\n\n:::\n\nIf the code cell produces a figure or table, you can combine the `lst-` options with `label` and `fig-cap`/`tbl-cap` to create cross references to both the code and output:\n\n````{.markdown}\n```{{python}}\n#| label: fig-plot\n#| fig-cap: Figure caption\n#| lst-label: lst-plot\n#| lst-cap: Listing caption\n\nplt.plot([1,23,2,4])\nplt.show()\n```\n\nThe code in @lst-plot produces the figure in @fig-plot.\n````\n\nWhen rendered, this produces the following output:\n\n:::{.border .p-3}\n\n::: {#cell-fig-plot .cell execution_count=2}\n``` {#lst-plot .python .cell-code lst-cap=\"Listing caption\"}\nplt.plot([1,23,2,4])\nplt.show()\n```\n\n::: {.cell-output .cell-output-display}\n![Figure caption](cross-references_files/figure-html/fig-plot-output-1.png){#fig-plot width=566 height=411}\n:::\n:::\n\n\nThe code in @lst-plot produces the plot in @fig-plot.\n:::\n\n\n\n## Callouts\n\nTo cross-reference a callout, add an ID attribute that starts with the appropriate callout prefix (see @tbl-callout-prefixes). You can then reference the callout using the usual `@` syntax. For example, here we add the ID `#tip-example` to the callout, and then refer back to it:\n\n``` markdown\n::: {#tip-example .callout-tip}\n## Cross-Referencing a Tip\n\nAdd an ID starting with `#tip-` to reference a tip.\n:::\n\nSee @tip-example...\n```\n\nThis renders as follows:\n\n::: {.border .p-3}\n::: {#tip-example .callout-tip}\n## Cross-Referencing a Tip\n\nAdd an ID starting with `#tip-` to reference a tip.\n:::\n\nSee @tip-example...\n:::\n\nThe prefixes for each type of callout are:\n\n| Callout Type | Prefix |\n|--------------|---------|\n| `note` | `#nte-` |\n| `tip` | `#tip-` |\n| `warning` | `#wrn-` |\n| `important` | `#imp-` |\n| `caution` | `#cau-` |\n\n: Prefixes for callout cross-references {#tbl-callout-prefixes}\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| `#sol-` | Solution | solution |\n| `#rem-` | Remark | remark |\n\nThe `proof` environment receives similar typesetting as theorems, however it is not numbered (and therefore cannot be cross-referenced). To create a proof add the `.proof` class to a div:\n\n``` markdown\n::: {.proof}\nBy induction.\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## 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", + "markdown": "---\ntitle: \"Cross References\"\nformat: html\ntoc-expand: 2\ntoc-depth: 4\naliases: \n - /docs/authoring/cross-references-listings.html\n - /docs/authoring/cross-references-callouts.html\n---\n\n\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---a unique identifier prefixed with a cross-reference type e.g. `#fig-element`. For example, this is a cross-referenceable figure:\n\n``` markdown\n![Elephant](elephant.png){#fig-elephant}\n```\n\nThe presence of the label (`#fig-elephant`) makes 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\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\n::: {#reserved-prefixes}\n::: {.callout-warning}\n\n## Reserved Prefixes \n\nUnless you are creating a cross-reference, avoid using the reserved cross-reference prefixes for code cell labels (e.g. set using the `label` code cell option) and element IDs (set using a `#` in an attribute). \n \nThe reserved prefixes are: `fig`, `tbl`, `lst`, `tip`, `nte`, `wrn`, `imp`, `cau`, `thm`, `lem`, `cor`, `prp`, `cnj`, `def`, `exm`, `exr`, `sol`, `rem`, `eq`, `sec`.\n\nAlso avoid using underscores (`_`) in labels and IDs as this can cause problems when rendering to PDF with LaTeX.\n\n:::\n:::\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\nOn this page you'll learn:\n\n* Different ways to use the `@` syntax to create [References](#references).\n* How to add [Lists](#lists) of references in LaTeX / PDF output.\n\nThen, we enumerate the syntax for the different types of elements you might want to reference:\n\n* [Floats](#floats): [Figures](#figures), [Tables](#tables) and [Code Listings](#code-listings)\n* Blocks: [Callouts](#callouts), [Theorems and Proofs](#theorems-and-proofs) and [Equations](#equations) \n* [Sections](#sections)\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](cross-reference-options.qmd) for details on how to customize the text used for cross-references.\n\n## References\n\nThe examples on this page all use 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 prefix had been changed via an [option](cross-reference-options.qmd#references) to use lower case (e.g. \"fig.\").\n\nThese syntax variations work not only for Figures, but for all cross-referenceable elements in Quarto such as Tables, Equations, Theorems, and so on.\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 guide on [Cross Reference Options](cross-reference-options.qmd#references) for additional details.\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## Floats\n\n[Figures](#figures), [tables](#tables) and [code listings](#code-listings) are known as \"float\" cross-references. Floats can appear in the rendered document at locations other than where they are defined, i.e. they float, and usually have captions. \n\nIn addition to the compact syntax for the most common uses of float cross-references, you can also define float cross-references with a div syntax. Use the div syntax when you need more flexibility in the content of your cross-reference, for example, to have a [video](cross-references-divs.qmd#videos) be referenced as a figure. Basic examples of the div syntax are included in the sections below, but you can find more complicated examples in [Cross-Reference Div Syntax](cross-references-divs.qmd). \n\nYou can also define custom types of float cross-reference to reference elements beyond figures, tables and code listings. Read more at [Custom Float Cross-References](cross-references-custom.qmd).\n\n\n### Figures\n\nAs described on the Overview 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\nTo create a cross-reference to a figure using div syntax, create a fenced div with an id starting with `fig-`, include the image followed by the caption inside the div:\n\n````markdown\n::: {#fig-elephant}\n\n![](elephant.png)\n\nAn Elephant\n:::\n````\n\n\n\nYou can read about using div syntax with figures at [Cross-Reference Div Syntax](cross-references-divs.qmd#figures).\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\n\n::: {.callout-tip}\n\n## Computed Captions\n\nIf you need to generate a dynamic caption, instead of using the `fig-cap` or `tbl-cap` code cell option, combine inline code with the [Cross-Reference Div Syntax](/docs/authoring/cross-references-divs.qmd#computed-captions).\n\n:::\n\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\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\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\nTo create a cross-reference to a table using div syntax, create a fenced div with an id starting with `tbl-`, include the table followed by the caption inside the div:\n\n````markdown\n::: {#tbl-letters}\n\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\nMy Caption\n\n::: \n````\n\n\n\nYou can read more about using div syntax with tables at [Cross-Reference Div Syntax](cross-references-divs.qmd#tables).\n\n#### Subtables\n\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\n\n::: {.callout-tip}\n\n## Computed Captions\n\nIf you need to generate a dynamic caption, instead of using the `fig-cap` or `tbl-cap` code cell option, combine inline code with the [Cross-Reference Div Syntax](/docs/authoring/cross-references-divs.qmd#computed-captions).\n\n:::\n\n\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\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\nTo create a cross-reference to a code listing using div syntax, create a fenced div with an id starting with `lst-`, include the code cell followed by the caption inside the div: \n\n````markdown\n::: {#lst-customers}\n\n```{.sql}\nSELECT * FROM Customers\n```\n\nCustomers Query\n\n:::\n````\n\n\n\nYou can read more about using div syntax for code listings in [Cross-Reference Div Syntax](cross-references-divs.qmd).\n\n\nTo cross-reference code from an executable code block, add the code cell options `lst-label` and `lst-cap`. The option `lst-label` provides the cross reference identifier and must begin with the prefix `lst-` to be treated as a code listing. The value of `lst-cap` provides the caption for the code listing. For example:\n\n````{.markdown}\n```{{python}}\n#| lst-label: lst-import\n#| lst-cap: Import pyplot\n\nimport matplotlib.pyplot as plt\n```\n\n@lst-import...\n````\n\nWhen rendered, this results in the following:\n\n::: {.border .p-3}\n\n::: {#7c670c7d .cell execution_count=1}\n``` {#lst-import .python .cell-code lst-cap=\"Import pyplot\"}\nimport matplotlib.pyplot as plt\n```\n:::\n\n\n@lst-import...\n\n:::\n\nIf the code cell produces a figure or table, you can combine the `lst-` options with `label` and `fig-cap`/`tbl-cap` to create cross references to both the code and output:\n\n````{.markdown}\n```{{python}}\n#| label: fig-plot\n#| fig-cap: Figure caption\n#| lst-label: lst-plot\n#| lst-cap: Listing caption\n\nplt.plot([1,23,2,4])\nplt.show()\n```\n\nThe code in @lst-plot produces the figure in @fig-plot.\n````\n\nWhen rendered, this produces the following output:\n\n:::{.border .p-3}\n\n::: {#cell-fig-plot .cell execution_count=2}\n``` {#lst-plot .python .cell-code lst-cap=\"Listing caption\"}\nplt.plot([1,23,2,4])\nplt.show()\n```\n\n::: {.cell-output .cell-output-display}\n![Figure caption](cross-references_files/figure-html/fig-plot-output-1.png){#fig-plot width=566 height=411}\n:::\n:::\n\n\nThe code in @lst-plot produces the plot in @fig-plot.\n:::\n\n\n\n## Callouts\n\n\nTo cross-reference a callout, add an ID attribute that starts with the appropriate callout prefix (see @tbl-callout-prefixes). You can then reference the callout using the usual `@` syntax. For example, here we add the ID `#tip-example` to the callout, and then refer back to it:\n\n``` markdown\n::: {#tip-example .callout-tip}\n## Cross-Referencing a Tip\n\nAdd an ID starting with `#tip-` to reference a tip.\n:::\n\nSee @tip-example...\n```\n\nThis renders as follows:\n\n::: {.border .p-3}\n::: {#tip-example .callout-tip}\n## Cross-Referencing a Tip\n\nAdd an ID starting with `#tip-` to reference a tip.\n:::\n\nSee @tip-example...\n:::\n\nThe prefixes for each type of callout are:\n\n| Callout Type | Prefix |\n|--------------|---------|\n| `note` | `#nte-` |\n| `tip` | `#tip-` |\n| `warning` | `#wrn-` |\n| `important` | `#imp-` |\n| `caution` | `#cau-` |\n\n: Prefixes for callout cross-references {#tbl-callout-prefixes}\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| `#sol-` | Solution | solution |\n| `#rem-` | Remark | remark |\n\nThe `proof` environment receives similar typesetting as theorems, however it is not numbered (and therefore cannot be cross-referenced). To create a proof add the `.proof` class to a div:\n\n``` markdown\n::: {.proof}\nBy induction.\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## 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 S^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", "supporting": [ "cross-references_files" ], diff --git a/docs/authoring/cross-references.qmd b/docs/authoring/cross-references.qmd index 8d0e872a90..5ba7f07329 100644 --- a/docs/authoring/cross-references.qmd +++ b/docs/authoring/cross-references.qmd @@ -366,7 +366,7 @@ Black-Scholes (@eq-black-scholes) is a mathematical model that seeks to explain $$ \frac{\partial \mathrm C}{ \partial \mathrm t } + \frac{1}{2}\sigma^{2} \mathrm S^{2} -\frac{\partial^{2} \mathrm C}{\partial \mathrm C^2} +\frac{\partial^{2} \mathrm C}{\partial \mathrm S^2} + \mathrm r \mathrm S \frac{\partial \mathrm C}{\partial \mathrm S}\ = \mathrm r \mathrm C $$ {#eq-black-scholes} @@ -401,5 +401,3 @@ title: "My Document" number-sections: true --- ``` - -