diff --git a/_freeze/docs/authoring/cross-references/execute-results/html.json b/_freeze/docs/authoring/cross-references/execute-results/html.json index f1d2691237..586febffde 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": "73687d731b0958f2db2cfbc7be4ad153", "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`, `alg`, `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\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\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::: 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\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#### 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\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\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::: {#e00739bc .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## 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## 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| `#alg-` | Algorithm | algorithm |\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", + "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`, `alg`, `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\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\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::: light-content\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::: dark-content\n![](images/crossref-table-dark.png){fig-alt=\"A table with 3 columns and four rows. The text 'Table 1: My Caption' is above the header column. The text 'See tbl. 1' is aligned to the left underneath the last column.\" width=\"500\"}\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\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#### 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\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\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::: {#30d5a652 .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## 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\nThe text used for each callout cross-reference (for example, \"Note 1\" in \"See Note 1...\") can be localised by setting `crossref-{nte,tip,wrn,imp,cau}-prefix` under `language:`:\n\n``` yaml\n---\nlang: fr\nlanguage:\n crossref-nte-prefix: \"Note\"\n crossref-tip-prefix: \"Astuce\"\n crossref-wrn-prefix: \"Avertissement\"\n crossref-imp-prefix: \"Important\"\n crossref-cau-prefix: \"Mise en garde\"\n---\n```\n\nSee [Cross-Reference Titles and Prefixes](language.qmd#cross-reference-titles-and-prefixes) for the full localisation pattern, including per-language subkeys.\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| `#alg-` | Algorithm | algorithm |\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/_freeze/docs/authoring/cross-references/figure-html/fig-plot-output-1.png b/_freeze/docs/authoring/cross-references/figure-html/fig-plot-output-1.png index a4ca94ac2e..f7534010ce 100644 Binary files a/_freeze/docs/authoring/cross-references/figure-html/fig-plot-output-1.png and b/_freeze/docs/authoring/cross-references/figure-html/fig-plot-output-1.png differ diff --git a/_freeze/docs/authoring/tables/execute-results/html.json b/_freeze/docs/authoring/tables/execute-results/html.json index d66c809c9e..3c47aa06c5 100644 --- a/_freeze/docs/authoring/tables/execute-results/html.json +++ b/_freeze/docs/authoring/tables/execute-results/html.json @@ -1,8 +1,8 @@ { - "hash": "7846992e58fd664a40939ae7beed6173", + "hash": "58ad76fc21eb84f4fa8452b9ce150226", "result": { "engine": "jupyter", - "markdown": "---\ntitle: Tables\nengine: jupyter\naliases: \n - /docs/prerelease/1.5/lua-table-processing.html\n---\n\n## Overview\n\nQuarto includes a number of features aimed at making it easy to to author and customize markdown table output, including:\n\n- Specifying column alignment and widths.\n- Providing captions, subcaptions, and cross-references.\n- Generating tables dynamically from executable code cells.\n\nThis article covers using these features in-depth.\n\n## Markdown Tables\n\nThe most commonly used markdown table is known as a pipe table. Pipe tables support specifying per column alignment as well as captions. For example:\n\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n| Default | Left | Right | Center |\n|---------|:-----|------:|:------:|\n| 12 | 12 | 12 | 12 |\n| 123 | 123 | 123 | 123 |\n| 1 | 1 | 1 | 1 |\n\n: Demonstration of pipe table syntax\n```\n\n::::\n\n:::: {}\n\n| Default | Left | Right | Center |\n|---------|:-----|------:|:------:|\n| 12 | 12 | 12 | 12 |\n| 123 | 123 | 123 | 123 |\n| 1 | 1 | 1 | 1 |\n\n: Demonstration of pipe table syntax\n\n::::\n\n:::\n\nThe beginning and ending pipe characters are optional, but pipes are required between all columns. The colons indicate column alignment as shown. The header cannot be omitted, however you can simulate a headerless table by including a header with blank cells.\n\nSince the pipes indicate column boundaries, columns need not be vertically aligned, as they are in the above example. So, this is a perfectly legal (though ugly) pipe table:\n\n``` markdown\nfruit| price\n-----|-----:\napple|2.05\npear|1.37\norange|3.09\n```\n\nThe cells of pipe tables cannot contain block elements like paragraphs and lists, and cannot span multiple lines. If a pipe table contains a row whose markdown content is wider than the column width (see `columns` option), then the table will take up the full text width and the cell contents will wrap, with the relative cell widths determined by the number of dashes in the line separating the table header from the table body.\n\nFor example `---|-` would make the first column 3/4 and the second column 1/4 of the full text width. On the other hand, if no lines are wider than column width, then cell contents will not be wrapped, and the cells will be sized to their contents.\n\n### Using Bootstrap classes\n\nBootstrap table classes given as attributes next to a table caption are inserted into the `` element.\nThe classes permitted are those that apply expressly to the entire table, and these are:\n`\"primary\"`, `\"secondary\"`, `\"success\"`, `\"danger\"`, `\"warning\"`, `\"info\"`, `\"light\"`, `\"dark\"`, `\"striped\"`, `\"hover\"`, `\"active\"`, `\"bordered\"`, `\"borderless\"`, `\"sm\"`, `\"responsive\"`, `\"responsive-sm\"`, `\"responsive-md\"`, `\"responsive-lg\"`, `\"responsive-xl\"`, `\"responsive-xxl\"`.\nFor example, the following Markdown table will be rendered with row stripes and the rows will also be highlighted on hover:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n\n``` markdown\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: Fruit prices {.striped .hover}\n```\n\n::::\n\n:::: {}\n\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: Fruit prices {.striped .hover}\n\n::::\n\n:::\n\n### Authoring\n\nFor simple tables with only a few cells it's straightforward to create them directly in markdown. As tables get larger, it makes sense to use an authoring tool. Some table authoring tools to consider include:\n\n+------------------------------------------------------------------------+---------------------------------------------------------------+\n| [TablesGenerator](https://www.tablesgenerator.com/markdown_tables) | Online tool for generating markdown tables |\n+------------------------------------------------------------------------+---------------------------------------------------------------+\n| [Emacs TableMode](https://www.emacswiki.org/emacs/TableMode) | Text based table creation and editing capabilities for Emacs. |\n+------------------------------------------------------------------------+---------------------------------------------------------------+\n| [Quarto Visual Editor](/docs/visual-editor/content.qmd#editing-tables) | Visual editor for `.qmd` files with table editing support. |\n+------------------------------------------------------------------------+---------------------------------------------------------------+\n\n: {tbl-colwidths=\"\\[35,65\\]\"}\n\n## Column Widths\n\nAbove we describe a means of specifying column widths using the relative number of dashes in each column header (_e.g._, `---|-` to get a 75% / 25% split for a two-column table).\n\nYou can also explicitly specify columns widths using the `tbl-colwidths` attribute or document-level option. For an individual markdown table, add the attribute after the caption. For example:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: Fruit prices {tbl-colwidths=\"[75,25]\"}\n```\n\n::::\n\n:::: {}\n\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: Fruit prices {tbl-colwidths=\"[75,25]\"}\n\n::::\n\n:::\n\nIf your table doesn't have a caption, then you can still specify only `tbl-colwidths`:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: {tbl-colwidths=\"[75,25]\"}\n```\n\n::::\n\n:::: {}\n\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: {tbl-colwidths=\"[75,25]\"}\n\n::::\n\n:::\n\nColumn widths can also be specified at the document level (_e.g._, to have uniform widths across a set of tables):\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: html\ntbl-colwidths: [75,25]\n---\n```\n\n## Cross References\n\nFor tables produced by executable code cells, include a label with a `tbl-` prefix to make them cross-referenceable.\nFor example:\n\n::: {#tbl-planets .cell tbl-cap='Astronomical object' execution_count=1}\n```` { .cell-code}\n```{{python}}\n#| label: tbl-planets\n#| tbl-cap: Astronomical object\n\nfrom IPython.display import Markdown\nfrom tabulate import tabulate\ntable = [[\"Sun\",\"696,000\",1.989e30],\n [\"Earth\",\"6,371\",5.972e24],\n [\"Moon\",\"1,737\",7.34e22],\n [\"Mars\",\"3,390\",6.39e23]]\nMarkdown(tabulate(\n table, \n headers=[\"Astronomical object\",\"R (km)\", \"mass (kg)\"]\n))\n```\n\n````\n\n::: {.cell-output .cell-output-display .cell-output-markdown execution_count=1}\nAstronomical object R (km) mass (kg)\n--------------------- -------- -----------\nSun 696,000 1.989e+30\nEarth 6,371 5.972e+24\nMoon 1,737 7.34e+22\nMars 3,390 6.39e+23\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\nSee the article on [Cross References](cross-references.qmd) for additional details.\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## Caption Location\n\nBy default, table captions are positioned above tables. You can modify this behavior using the `tbl-cap-location` option. For example:\n\n``` yaml\n---\ntbl-cap-location: top\n---\n```\n\nNote that this option is specified at the top level so that it can be shared by both PDF and HTML formats. If you are only targeting a single format you can place it alongside other `format` specific options.\n\nValid values for the caption location include:\n\n| Value | Description |\n|----------|---------------------------------------|\n| `top` | Position the caption above the table. |\n| `bottom` | Position the caption below the table. |\n| `margin` | Position the caption in the margin. |\n\nSee the article on [Article Layout](article-layout.qmd#margin-captions) for additional details on placing captions in the margin.\n\n## Computations\n\nAll of the options described above work for tables produced by executable code cells. For example, here we use the Python [tabulate](https://pypi.org/project/tabulate/) package along with the `Markdown()` function from the IPython [display](https://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html#) module to print a markdown table:\n\n::: {#tbl-planet-measures .cell tbl-cap='Astronomical object' execution_count=2}\n```` { .cell-code}\n```{{python}}\n#| label: tbl-planet-measures\n#| tbl-cap: Astronomical object\n\nfrom IPython.display import Markdown\nfrom tabulate import tabulate\ntable = [[\"Sun\",\"696,000\",1.989e30],\n [\"Earth\",\"6,371\",5.972e24],\n [\"Moon\",\"1,737\",7.34e22],\n [\"Mars\",\"3,390\",6.39e23]]\nMarkdown(tabulate(\n table, \n headers=[\"Astronomical object\",\"R (km)\", \"mass (kg)\"]\n))\n```\n\n````\n\n::: {.cell-output .cell-output-display .cell-output-markdown execution_count=2}\nAstronomical object R (km) mass (kg)\n--------------------- -------- -----------\nSun 696,000 1.989e+30\nEarth 6,371 5.972e+24\nMoon 1,737 7.34e+22\nMars 3,390 6.39e+23\n:::\n:::\n\n\nHere we apply the `tbl-cap` and `tbl-colwidths` options to a code cell that uses the knitr `kable()` function to write a markdown table:\n\n```{{r}}\n#| label: tbl-cars\n#| tbl-cap: \"Cars\"\n#| tbl-colwidths: [60,40]\n\nkable(head(cars))\n```\n\nIf your code cell produces multiple tables, you can also specify subcaptions and layout using cell options:\n\n::: {.panel-tabset group=\"language\"}\n\n## Python\n\n````python\n```{{python}}\n#| label: tbl-example\n#| tbl-cap: \"Example\"\n#| tbl-subcap: \n#| - \"MPG\"\n#| - \"Taxis\"\n#| layout-ncol: 2\n\nimport seaborn as sns\nfrom IPython.display import Markdown, display\nmpg = sns.load_dataset(\"mpg\").head(10)\ntaxis = sns.load_dataset(\"taxis\").head(10)\n\ndisplay(Markdown(mpg.to_markdown(index = False)))\ndisplay(Markdown(taxis.to_markdown(index = False)))\n```\n````\n\nNote that we use the [`display()`](https://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html#IPython.display.display) function imported from `IPython` so that we can render multiple outputs from a single cell (by default cells only output their last expression).\n\n## R\n\n````python\n```{{r}}\n#| label: tbl-example\n#| tbl-cap: \"Example\"\n#| tbl-subcap: \n#| - \"Cars\"\n#| - \"Pressure\"\n#| layout-ncol: 2\n\nlibrary(knitr)\nkable(head(cars))\nkable(head(pressure))\n```\n````\n\n\n:::\n\n### Computational Table Styling\n\nQuarto adds additional styling to tables generated by computations. By default, such tables are styled to be smaller and have striped rows.\nIf you want to disable this treatment, add `plain` to the classes of the code cell:\n\n````python\n```{{r}}\n#| classes: plain\n\ntibble::tribble(\n ~fruit, ~price,\n \"apple\", 2.05,\n \"pear\", 1.37,\n \"orange\", 3.09\n) |> \n gt::gt()\n```\n````\n\n## List Tables\n\nList tables provide an alternative syntax for creating tables with complex content like multiple paragraphs, code blocks, or lists. Unlike [grid tables](#grid-tables), list tables use familiar bullet list syntax, making them easier to write and maintain.\n\nA list table is a fenced div with the `.list-table` class containing a bullet list. Each top-level bullet represents a row, and nested bullets represent cells:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n::: {.list-table}\n- - Fruit\n - Price\n\n- - Apple\n - 1.20\n\n- - Orange\n - 0.90\n:::\n```\n\n::::\n\n:::: {}\n\n::: {.list-table}\n- - Fruit\n - Price\n\n- - Apple\n - 1.20\n\n- - Orange\n - 0.90\n:::\n\n::::\n\n:::\n\nList tables support block elements within cells, including code blocks and lists:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n```` markdown\n::: {.list-table}\n- - Function\n - Description\n\n- - `sum()`\n - Add values:\n\n ```python\n sum([1, 2, 3])\n ```\n\n- - `len()`\n - Count items:\n\n - Works on lists\n - Works on strings\n:::\n````\n\n::::\n\n:::: {}\n\n::: {.list-table}\n- - Function\n - Description\n\n- - `sum()`\n - Add values:\n\n ```python\n sum([1, 2, 3])\n ```\n\n- - `len()`\n - Count items:\n\n - Works on lists\n - Works on strings\n:::\n\n::::\n\n:::\n\nBe careful to maintain the usual whitespace requirements: indent nested items and include blank lines around code blocks.\n\n### Header Rows \n\nBy default, the first row is treated as a header. To change this, set the `header-rows` attribute to `0`:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n::: {.list-table header-rows=0}\n- - Apple\n - 1.20\n\n- - Orange\n - 0.90\n:::\n```\n\n::::\n\n:::: {}\n\n::: {.list-table header-rows=0}\n- - Apple\n - 1.20\n\n- - Orange\n - 0.90\n:::\n\n::::\n\n:::\n\n### Column Alignment\n\nSpecify column alignment with the `aligns` attribute using `d` (default), `l` (left), `r` (right), or `c` (center):\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n::: {.list-table aligns=\"l,r\"}\n- - Fruit\n - Price\n\n- - Apple\n - 1.20\n\n- - Orange\n - 0.90\n:::\n```\n\n::::\n\n:::: {}\n\n::: {.list-table aligns=\"l,r\"}\n- - Fruit\n - Price\n\n- - Apple\n - 1.20\n\n- - Orange\n - 0.90\n:::\n\n::::\n\n:::\n\n### Column Widths\n\nYou can specify relative column widths by adding the `tbl-colwidths` attribute:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n::: {.list-table tbl-colwidths=\"[75,25]\"}\n- - Fruit\n - Price\n\n- - Apple\n - 1.20\n\n- - Orange\n - 0.90\n:::\n```\n\n::::\n\n:::: {}\n\n::: {.list-table tbl-colwidths=\"[75,25]\"}\n- - Fruit\n - Price\n\n- - Apple\n - 1.20\n\n- - Orange\n - 0.90\n:::\n\n::::\n\n:::\n\n### Captions and Cross References\n\nAdd a caption by including a paragraph at the start of the div:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n::: {.list-table}\nFruit prices\n\n- - Fruit\n - Price\n\n- - Apple\n - 1.20\n:::\n```\n\n::::\n\n:::: {}\n\n::: {.list-table}\nFruit prices\n\n- - Fruit\n - Price\n\n- - Apple\n - 1.20\n:::\n\n::::\n\n:::\n\nTo make a list table cross-referenceable, add an id with the `tbl-` prefix:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n::: {#tbl-fruits .list-table}\nFruit prices\n\n- - Fruit\n - Price\n\n- - Apple\n - 1.20\n:::\n\nSee @tbl-fruits.\n```\n\n::::\n\n:::: {}\n\n::: {#tbl-fruits .list-table}\nFruit prices\n\n- - Fruit\n - Price\n\n- - Apple\n - 1.20\n:::\n\nSee @tbl-fruits.\n\n::::\n\n:::\n\n### Cell Attributes\n\nTo add attributes to a cell, start the cell with an empty span containing the attributes. For example, use `rowspan` and `colspan` to span cells across rows or columns:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n::: {.list-table}\n- - []{colspan=2} Item\n - Price\n\n- - []{rowspan=2} Citrus\n - Orange\n - 0.90\n\n- - Lemon\n - 0.80\n\n- - []{rowspan=2} Stone Fruit\n - Peach\n - 1.20\n\n- - Plum\n - 1.00\n:::\n```\n\n::::\n\n:::: {}\n\n::: {.list-table}\n- - []{colspan=2} Item\n - Price\n\n- - []{rowspan=2} Citrus\n - Orange\n - 0.90\n\n- - Lemon\n - 0.80\n\n- - []{rowspan=2} Stone Fruit\n - Peach\n - 1.20\n\n- - Plum\n - 1.00\n:::\n\n::::\n\n:::\n\nThe empty span must be the first inline element in the cell. Cells with `rowspan` or `colspan` still count toward the total number of cells in a row—subsequent rows should have fewer cells to account for the span.\n\n## Grid Tables\n\nGrid tables are a more advanced type of markdown tables that allow arbitrary block elements (multiple paragraphs, code blocks, lists, etc.). For example:\n\n\n``` markdown\n+-----------+-----------+--------------------+\n| Fruit | Price | Advantages |\n+===========+===========+====================+\n| Bananas | $1.34 | - built-in wrapper |\n| | | - bright color |\n+-----------+-----------+--------------------+\n| Oranges | $2.10 | - cures scurvy |\n| | | - tasty |\n+-----------+-----------+--------------------+\n\n: Sample grid table.\n```\n\nWhich looks like this when rendered to HTML:\n\n+-----------+-----------+--------------------+\n| Fruit | Price | Advantages |\n+===========+===========+====================+\n| Bananas | $1.34 | - built-in wrapper |\n| | | - bright color |\n+-----------+-----------+--------------------+\n| Oranges | $2.10 | - cures scurvy |\n| | | - tasty |\n+-----------+-----------+--------------------+\n\n: Sample grid table.\n\n\nThe row of `=`s separates the header from the table body, and can be omitted for a headerless table. The cells of grid tables may contain arbitrary block elements (multiple paragraphs, code blocks, lists, etc.)\n\nAlignments can be specified as with pipe tables, by putting colons at the boundaries of the separator line after the header:\n\n\n``` markdown\n+---------+--------+------------------+\n| Right | Left | Centered |\n+========:+:=======+:================:+\n| Bananas | $1.34 | built-in wrapper |\n+---------+--------+------------------+\n```\nWhich looks like this when rendered to HTML:\n\n+---------+--------+------------------+\n| Right | Left | Centered |\n+========:+:=======+:================:+\n| Bananas | $1.34 | built-in wrapper |\n+---------+--------+------------------+\n\n\nFor headerless tables, the colons go on the top line instead:\n\n``` markdown\n+----------:+:----------+:--------:+\n| Right | Left | Centered |\n+-----------+-----------+----------+\n```\n\nWhich looks like this when rendered to HTML:\n\n+----------:+:----------+:--------:+\n| Right | Left | Centered |\n+-----------+-----------+----------+\n\n\nNote that grid tables are quite awkward to write with a plain text editor (because unlike pipe tables, the column indicators must align). Here are some tools that can assist with creating grid tables:\n\n- Emacs' [table-mode](https://www.gnu.org/software/emacs/manual/html_node/emacs/Text-Based-Tables.html) (`M-x table-insert`)\n- Quarto [Visual Editor](/docs/visual-editor/content.qmd#editing-tables)\n- Tables Generator's [Plain Text mode](https://www.tablesgenerator.com/text_tables) with `Use reStructuredText syntax` enabled\n\n## HTML Tables\n\nQuarto can process HTML tables in `html` `RawBlock` nodes (_i.e._, `{=html}`) and convert them to Markdown tables, regardless of the output format (intentionally including non-HTML formats).\nAs a result, you can use HTML table syntax in your documents and it will be converted to Markdown syntax for all formats.\nAdditionally, libraries that emit computational tables in HTML format can work in other output formats.\n\nFor example, consider the following raw HTML block:\n\n````markdown\n```{=html}\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
As described in the section above, Quarto tables are great.
Header 1Header 2
\"AfricanRegular output
\n```\n````\n\nWhen rendered, this results in the following output for HTML and PDF formats:\n\n::: {layout-ncol=2}\n\n:::: {}\n### HTML Output\n\n```{=html}\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n
As described in the section above, Quarto tables are great.
Header 1Header 2
\"AfricanRegular output
\n```\n::::\n\n:::: {}\n### PDF Output\n\n![](images/raw-table-pdf.png){.border fig-alt=\"Screenshot of PDF output showing a table with a caption and two columns. The column headers are Header 1 and Header 2, and the cell contents are an image of an elephant and text that reads Regular Output.\"}\n::::\n\n:::\n\nIn addition, Quarto supports the specification of embedded Markdown content in raw table markup. This allows Quarto features like cross-references, shortcodes, and markdown formatting to be used inside tables produced by libraries that emit raw HTML or LaTeX.\n\n#### HTML Raw Blocks\n\nFor HTML raw blocks, this is done by providing a data attribute `qmd` or `qmd-base64` in an embedded `span` or `div` node. These nodes can appear anywhere that such content is allowed: table headers, footers, cells, captions, _etc._\n\nFor example, the following table includes a cross reference, markdown formatting and a shortcode:\n\n:::: {layout-nrow=\"2\"}\n\n::: {}\n\n```` markdown\n## HTML Tables Example {#sec-html-tables}\n\n```{=html}\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n
}}}\">Regular output
\n```\n````\n\n:::\n\n::: {}\n\nWhich renders as follows:\n\n## HTML Tables Example {#sec-html-tables}\n\n```{=html}\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n
}}\">Regular output
\n```\n\n:::\n\n::::\n\n#### LaTeX Raw Blocks\n\nFor LaTeX raw blocks (used in PDF output), the equivalent syntax is `\\QuartoMarkdownBase64{<>}`. When Quarto detects this command, it decodes the base64 content, processes it as Quarto markdown (including cross-references, shortcodes, and user filters), and inserts the result back into the LaTeX output.\n\nFor example, the following LaTeX raw block uses cross-references and markdown formatting inside a table:\n\n```` markdown\n## LaTeX Tables Example {#sec-latex-tables}\n\n```{=latex}\n\\begin{tabular}{ll}\n % X0hlYWRlciAxXw== is base64 for \"_Header 1_\"\n \\QuartoMarkdownBase64{X0hlYWRlciAxXw==} &\n % X0hlYWRlciAyXw== is base64 for \"_Header 2_\"\n \\QuartoMarkdownBase64{X0hlYWRlciAyXw==} \\\\\n % U2VlIEBzZWMtbGF0ZXgtdGFibGVzLg== is base64 for\n % \"See @sec-latex-tables.\"\n \\QuartoMarkdownBase64{U2VlIEBzZWMtbGF0ZXgtdGFibGVzLg==} &\n Regular output \\\\\n\\end{tabular}\n```\n````\n\nWhen rendered to PDF, this table would display with italic headers (*Header 1* and *Header 2*), and the cross-reference `@sec-latex-tables` would be resolved to a clickable section link.\n\n::: {.callout-note}\nUnlike the HTML feature, only base64-encoded content is supported for LaTeX raw blocks (there is no plain-text equivalent of `data-qmd`). This feature cannot be disabled, but this should not be necessary since `\\QuartoMarkdownBase64` is unlikely to conflict with existing LaTeX commands.\n:::\n\n::: {.callout-warning}\nCitations do not currently work inside `\\QuartoMarkdownBase64`. See [GitHub issue #9342](https://github.com/quarto-dev/quarto-cli/issues/9342) for details.\n:::\n\n### Colspans and Rowspans\n\nTables containing cells spanning multiple rows or columns are supported across output formats[except in PDF margins]{.aside}.\n\nHowever, using markdown, it is tricky to draw grid tables with spans, and there is no way to express spans in pipe tables. \n\nIf you are comfortable with HTML, or use a package that generates HTML, the table cell HTML attributes `colspan` and `rowspan` are a better option.\n\n```{=html}\n\n\t\n\t\t\n\t\n\t\n\t\t\n\t\n\t\n\t\t\n\t\n
I span two columnsC1
I span two rowsB2C2
B3C3
\n\n```\n\n````html\n```{=html}\n\n\t\n\t\t\n\t\n\t\n\t\t\n\t\n\t\n\t\t\n\t\n
I span two columnsC1
I span two rowsB2C2
B3C3
\n\n```\n````\n\n\n### Individual cell alignment\n\nMarkdown supports specification of alignment by column, but does not allow setting the alignment of individual cells. The CSS properties `text-align` and `vertical-align` are only available through Raw HTML. (These are not currently supported by PDF/Latex or Pptx output formats, and Docx only supports `text-align`.)\n\n\n```{=html}\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
vertical-align: topvertical-align: middlevertical-align: bottom
text-align: left
text-align: center
text-align: right
\n \n\n```\n\n````html\n```{=html}\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
vertical-align: topvertical-align: middlevertical-align: bottom
text-align: left
text-align: center
text-align: right
\n \n\n```\n````\n\n## Disabling Quarto Table Processing\n\nIt's possible that Quarto's processing of HTML tables may interfere with the HTML produced computationally with table packages in R and Python (or other supported languages).\n\n\nWhen you disable Quarto's HTML table processing, tables are not translated to Markdown, will not be rendered to other output formats, and can not use Quarto Markdown features, like cross-references, shortcodes, etc.\nThe tables also won't be visible to Lua filters that act on `Table` nodes.\n\nYou can disable Quarto's HTML table processing at a document level or project level with the option `html-table-processing`:\n\n```{.yaml}\n---\nformat:\n html:\n html-table-processing: none\n---\n```\n\nThis option is also available as a code cell option for Knitr and Jupyter, e.g. \n\n````{markdown}\n```{{r}}\n#| html-table-processing: none\n\n# R Code that generates an HTML table\n```\n````\n\nTo disable Quarto's HTML table processing for parts of a document use a div with the attribute `html-table-processing=\"none\"`:\n\n````{.markdown}\n::: {html-table-processing=\"none\"}\n\nContent with HTML tables you don't want processed.\n\n:::\n````\n\n### Library authors\n\nIf you are the author of a library that emits HTML tables you might like to disable Quarto's processing of HTML tables by adding the attribute `data-quarto-disable-processing=\"true\"` to the `` element. For example:\n\n```html\n
\n ...\n
\n```\n\nAdditionally, you can add the comment `` to the HTML raw block, and Quarto will not attempt to process it.\n\n", + "markdown": "---\ntitle: Tables\nengine: jupyter\naliases: \n - /docs/prerelease/1.5/lua-table-processing.html\n---\n\n## Overview\n\nQuarto includes a number of features aimed at making it easy to to author and customize markdown table output, including:\n\n- Specifying column alignment and widths.\n- Providing captions, subcaptions, and cross-references.\n- Generating tables dynamically from executable code cells.\n\nThis article covers using these features in-depth.\n\n## Markdown Tables\n\nThe most commonly used markdown table is known as a pipe table. Pipe tables support specifying per column alignment as well as captions. For example:\n\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n| Default | Left | Right | Center |\n|---------|:-----|------:|:------:|\n| 12 | 12 | 12 | 12 |\n| 123 | 123 | 123 | 123 |\n| 1 | 1 | 1 | 1 |\n\n: Demonstration of pipe table syntax\n```\n\n::::\n\n:::: {}\n\n| Default | Left | Right | Center |\n|---------|:-----|------:|:------:|\n| 12 | 12 | 12 | 12 |\n| 123 | 123 | 123 | 123 |\n| 1 | 1 | 1 | 1 |\n\n: Demonstration of pipe table syntax\n\n::::\n\n:::\n\nThe beginning and ending pipe characters are optional, but pipes are required between all columns. The colons indicate column alignment as shown. The header cannot be omitted, however you can simulate a headerless table by including a header with blank cells.\n\nSince the pipes indicate column boundaries, columns need not be vertically aligned, as they are in the above example. So, this is a perfectly legal (though ugly) pipe table:\n\n``` markdown\nfruit| price\n-----|-----:\napple|2.05\npear|1.37\norange|3.09\n```\n\nThe cells of pipe tables cannot contain block elements like paragraphs and lists, and cannot span multiple lines. If a pipe table contains a row whose markdown content is wider than the column width (see `columns` option), then the table will take up the full text width and the cell contents will wrap, with the relative cell widths determined by the number of dashes in the line separating the table header from the table body.\n\nFor example `---|-` would make the first column 3/4 and the second column 1/4 of the full text width. On the other hand, if no lines are wider than column width, then cell contents will not be wrapped, and the cells will be sized to their contents.\n\n### Using Bootstrap classes\n\nBootstrap table classes given as attributes next to a table caption are inserted into the `` element.\nThe classes permitted are those that apply expressly to the entire table, and these are:\n`\"primary\"`, `\"secondary\"`, `\"success\"`, `\"danger\"`, `\"warning\"`, `\"info\"`, `\"light\"`, `\"dark\"`, `\"striped\"`, `\"hover\"`, `\"active\"`, `\"bordered\"`, `\"borderless\"`, `\"sm\"`, `\"responsive\"`, `\"responsive-sm\"`, `\"responsive-md\"`, `\"responsive-lg\"`, `\"responsive-xl\"`, `\"responsive-xxl\"`.\nFor example, the following Markdown table will be rendered with row stripes and the rows will also be highlighted on hover:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n\n``` markdown\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: Fruit prices {.striped .hover}\n```\n\n::::\n\n:::: {}\n\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: Fruit prices {.striped .hover}\n\n::::\n\n:::\n\n### Authoring\n\nFor simple tables with only a few cells it's straightforward to create them directly in markdown. As tables get larger, it makes sense to use an authoring tool. Some table authoring tools to consider include:\n\n+------------------------------------------------------------------------+---------------------------------------------------------------+\n| [TablesGenerator](https://www.tablesgenerator.com/markdown_tables) | Online tool for generating markdown tables |\n+------------------------------------------------------------------------+---------------------------------------------------------------+\n| [Emacs TableMode](https://www.emacswiki.org/emacs/TableMode) | Text based table creation and editing capabilities for Emacs. |\n+------------------------------------------------------------------------+---------------------------------------------------------------+\n| [Quarto Visual Editor](/docs/visual-editor/content.qmd#editing-tables) | Visual editor for `.qmd` files with table editing support. |\n+------------------------------------------------------------------------+---------------------------------------------------------------+\n\n: {tbl-colwidths=\"\\[35,65\\]\"}\n\n## Column Widths\n\nAbove we describe a means of specifying column widths using the relative number of dashes in each column header (_e.g._, `---|-` to get a 75% / 25% split for a two-column table).\n\nYou can also explicitly specify columns widths using the `tbl-colwidths` attribute or document-level option. For an individual markdown table, add the attribute after the caption. For example:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: Fruit prices {tbl-colwidths=\"[75,25]\"}\n```\n\n::::\n\n:::: {}\n\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: Fruit prices {tbl-colwidths=\"[75,25]\"}\n\n::::\n\n:::\n\nIf your table doesn't have a caption, then you can still specify only `tbl-colwidths`:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: {tbl-colwidths=\"[75,25]\"}\n```\n\n::::\n\n:::: {}\n\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: {tbl-colwidths=\"[75,25]\"}\n\n::::\n\n:::\n\nColumn widths can also be specified at the document level (_e.g._, to have uniform widths across a set of tables):\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: html\ntbl-colwidths: [75,25]\n---\n```\n\n## Cross References\n\nFor tables produced by executable code cells, include a label with a `tbl-` prefix to make them cross-referenceable.\nFor example:\n\n::: {#tbl-planets .cell tbl-cap='Astronomical object' execution_count=1}\n```` { .cell-code}\n```{{python}}\n#| label: tbl-planets\n#| tbl-cap: Astronomical object\n\nfrom IPython.display import Markdown\nfrom tabulate import tabulate\ntable = [[\"Sun\",\"696,000\",1.989e30],\n [\"Earth\",\"6,371\",5.972e24],\n [\"Moon\",\"1,737\",7.34e22],\n [\"Mars\",\"3,390\",6.39e23]]\nMarkdown(tabulate(\n table, \n headers=[\"Astronomical object\",\"R (km)\", \"mass (kg)\"]\n))\n```\n\n````\n\n::: {.cell-output .cell-output-display .cell-output-markdown execution_count=1}\nAstronomical object R (km) mass (kg)\n--------------------- -------- -----------\nSun 696,000 1.989e+30\nEarth 6,371 5.972e+24\nMoon 1,737 7.34e+22\nMars 3,390 6.39e+23\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::: light-content\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::: dark-content\n![](images/crossref-table-dark.png){fig-alt=\"A table with 3 columns and four rows. The text 'Table 1: My Caption' is above the header column. The text 'See tbl. 1' is aligned to the left underneath the last column.\" width=\"500\"}\n:::\n\n\nSee the article on [Cross References](cross-references.qmd) for additional details.\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## Caption Location\n\nBy default, table captions are positioned above tables. You can modify this behavior using the `tbl-cap-location` option. For example:\n\n``` yaml\n---\ntbl-cap-location: top\n---\n```\n\nNote that this option is specified at the top level so that it can be shared by both PDF and HTML formats. If you are only targeting a single format you can place it alongside other `format` specific options.\n\nValid values for the caption location include:\n\n| Value | Description |\n|----------|---------------------------------------|\n| `top` | Position the caption above the table. |\n| `bottom` | Position the caption below the table. |\n| `margin` | Position the caption in the margin. |\n\nSee the article on [Article Layout](article-layout.qmd#margin-captions) for additional details on placing captions in the margin.\n\n## Computations\n\nAll of the options described above work for tables produced by executable code cells. For example, here we use the Python [tabulate](https://pypi.org/project/tabulate/) package along with the `Markdown()` function from the IPython [display](https://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html#) module to print a markdown table:\n\n::: {#tbl-planet-measures .cell tbl-cap='Astronomical object' execution_count=2}\n```` { .cell-code}\n```{{python}}\n#| label: tbl-planet-measures\n#| tbl-cap: Astronomical object\n\nfrom IPython.display import Markdown\nfrom tabulate import tabulate\ntable = [[\"Sun\",\"696,000\",1.989e30],\n [\"Earth\",\"6,371\",5.972e24],\n [\"Moon\",\"1,737\",7.34e22],\n [\"Mars\",\"3,390\",6.39e23]]\nMarkdown(tabulate(\n table, \n headers=[\"Astronomical object\",\"R (km)\", \"mass (kg)\"]\n))\n```\n\n````\n\n::: {.cell-output .cell-output-display .cell-output-markdown execution_count=2}\nAstronomical object R (km) mass (kg)\n--------------------- -------- -----------\nSun 696,000 1.989e+30\nEarth 6,371 5.972e+24\nMoon 1,737 7.34e+22\nMars 3,390 6.39e+23\n:::\n:::\n\n\nHere we apply the `tbl-cap` and `tbl-colwidths` options to a code cell that uses the knitr `kable()` function to write a markdown table:\n\n```{{r}}\n#| label: tbl-cars\n#| tbl-cap: \"Cars\"\n#| tbl-colwidths: [60,40]\n\nkable(head(cars))\n```\n\nIf your code cell produces multiple tables, you can also specify subcaptions and layout using cell options:\n\n::: {.panel-tabset group=\"language\"}\n\n## Python\n\n````python\n```{{python}}\n#| label: tbl-example\n#| tbl-cap: \"Example\"\n#| tbl-subcap: \n#| - \"MPG\"\n#| - \"Taxis\"\n#| layout-ncol: 2\n\nimport seaborn as sns\nfrom IPython.display import Markdown, display\nmpg = sns.load_dataset(\"mpg\").head(10)\ntaxis = sns.load_dataset(\"taxis\").head(10)\n\ndisplay(Markdown(mpg.to_markdown(index = False)))\ndisplay(Markdown(taxis.to_markdown(index = False)))\n```\n````\n\nNote that we use the [`display()`](https://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html#IPython.display.display) function imported from `IPython` so that we can render multiple outputs from a single cell (by default cells only output their last expression).\n\n## R\n\n````python\n```{{r}}\n#| label: tbl-example\n#| tbl-cap: \"Example\"\n#| tbl-subcap: \n#| - \"Cars\"\n#| - \"Pressure\"\n#| layout-ncol: 2\n\nlibrary(knitr)\nkable(head(cars))\nkable(head(pressure))\n```\n````\n\n\n:::\n\n### Computational Table Styling\n\nQuarto adds additional styling to tables generated by computations. By default, such tables are styled to be smaller and have striped rows.\nIf you want to disable this treatment, add `plain` to the classes of the code cell:\n\n````python\n```{{r}}\n#| classes: plain\n\ntibble::tribble(\n ~fruit, ~price,\n \"apple\", 2.05,\n \"pear\", 1.37,\n \"orange\", 3.09\n) |> \n gt::gt()\n```\n````\n\n## List Tables\n\nList tables provide an alternative syntax for creating tables with complex content like multiple paragraphs, code blocks, or lists. Unlike [grid tables](#grid-tables), list tables use familiar bullet list syntax, making them easier to write and maintain.\n\nA list table is a fenced div with the `.list-table` class containing a bullet list. Each top-level bullet represents a row, and nested bullets represent cells:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n::: {.list-table}\n- - Fruit\n - Price\n\n- - Apple\n - 1.20\n\n- - Orange\n - 0.90\n:::\n```\n\n::::\n\n:::: {}\n\n::: {.list-table}\n- - Fruit\n - Price\n\n- - Apple\n - 1.20\n\n- - Orange\n - 0.90\n:::\n\n::::\n\n:::\n\nList tables support block elements within cells, including code blocks and lists:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n```` markdown\n::: {.list-table}\n- - Function\n - Description\n\n- - `sum()`\n - Add values:\n\n ```python\n sum([1, 2, 3])\n ```\n\n- - `len()`\n - Count items:\n\n - Works on lists\n - Works on strings\n:::\n````\n\n::::\n\n:::: {}\n\n::: {.list-table}\n- - Function\n - Description\n\n- - `sum()`\n - Add values:\n\n ```python\n sum([1, 2, 3])\n ```\n\n- - `len()`\n - Count items:\n\n - Works on lists\n - Works on strings\n:::\n\n::::\n\n:::\n\nBe careful to maintain the usual whitespace requirements: indent nested items and include blank lines around code blocks.\n\n### Header Rows \n\nBy default, the first row is treated as a header. To change this, set the `header-rows` attribute to `0`:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n::: {.list-table header-rows=0}\n- - Apple\n - 1.20\n\n- - Orange\n - 0.90\n:::\n```\n\n::::\n\n:::: {}\n\n::: {.list-table header-rows=0}\n- - Apple\n - 1.20\n\n- - Orange\n - 0.90\n:::\n\n::::\n\n:::\n\n### Column Alignment\n\nSpecify column alignment with the `aligns` attribute using `d` (default), `l` (left), `r` (right), or `c` (center):\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n::: {.list-table aligns=\"l,r\"}\n- - Fruit\n - Price\n\n- - Apple\n - 1.20\n\n- - Orange\n - 0.90\n:::\n```\n\n::::\n\n:::: {}\n\n::: {.list-table aligns=\"l,r\"}\n- - Fruit\n - Price\n\n- - Apple\n - 1.20\n\n- - Orange\n - 0.90\n:::\n\n::::\n\n:::\n\n### Column Widths\n\nYou can specify relative column widths by adding the `tbl-colwidths` attribute:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n::: {.list-table tbl-colwidths=\"[75,25]\"}\n- - Fruit\n - Price\n\n- - Apple\n - 1.20\n\n- - Orange\n - 0.90\n:::\n```\n\n::::\n\n:::: {}\n\n::: {.list-table tbl-colwidths=\"[75,25]\"}\n- - Fruit\n - Price\n\n- - Apple\n - 1.20\n\n- - Orange\n - 0.90\n:::\n\n::::\n\n:::\n\n### Captions and Cross References\n\nAdd a caption by including a paragraph at the start of the div:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n::: {.list-table}\nFruit prices\n\n- - Fruit\n - Price\n\n- - Apple\n - 1.20\n:::\n```\n\n::::\n\n:::: {}\n\n::: {.list-table}\nFruit prices\n\n- - Fruit\n - Price\n\n- - Apple\n - 1.20\n:::\n\n::::\n\n:::\n\nTo make a list table cross-referenceable, add an id with the `tbl-` prefix:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n::: {#tbl-fruits .list-table}\nFruit prices\n\n- - Fruit\n - Price\n\n- - Apple\n - 1.20\n:::\n\nSee @tbl-fruits.\n```\n\n::::\n\n:::: {}\n\n::: {#tbl-fruits .list-table}\nFruit prices\n\n- - Fruit\n - Price\n\n- - Apple\n - 1.20\n:::\n\nSee @tbl-fruits.\n\n::::\n\n:::\n\n### Cell Attributes\n\nTo add attributes to a cell, start the cell with an empty span containing the attributes. For example, use `rowspan` and `colspan` to span cells across rows or columns:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n::: {.list-table}\n- - []{colspan=2} Item\n - Price\n\n- - []{rowspan=2} Citrus\n - Orange\n - 0.90\n\n- - Lemon\n - 0.80\n\n- - []{rowspan=2} Stone Fruit\n - Peach\n - 1.20\n\n- - Plum\n - 1.00\n:::\n```\n\n::::\n\n:::: {}\n\n::: {.list-table}\n- - []{colspan=2} Item\n - Price\n\n- - []{rowspan=2} Citrus\n - Orange\n - 0.90\n\n- - Lemon\n - 0.80\n\n- - []{rowspan=2} Stone Fruit\n - Peach\n - 1.20\n\n- - Plum\n - 1.00\n:::\n\n::::\n\n:::\n\nThe empty span must be the first inline element in the cell. Cells with `rowspan` or `colspan` still count toward the total number of cells in a row—subsequent rows should have fewer cells to account for the span.\n\n## Grid Tables\n\nGrid tables are a more advanced type of markdown tables that allow arbitrary block elements (multiple paragraphs, code blocks, lists, etc.). For example:\n\n\n``` markdown\n+-----------+-----------+--------------------+\n| Fruit | Price | Advantages |\n+===========+===========+====================+\n| Bananas | $1.34 | - built-in wrapper |\n| | | - bright color |\n+-----------+-----------+--------------------+\n| Oranges | $2.10 | - cures scurvy |\n| | | - tasty |\n+-----------+-----------+--------------------+\n\n: Sample grid table.\n```\n\nWhich looks like this when rendered to HTML:\n\n+-----------+-----------+--------------------+\n| Fruit | Price | Advantages |\n+===========+===========+====================+\n| Bananas | $1.34 | - built-in wrapper |\n| | | - bright color |\n+-----------+-----------+--------------------+\n| Oranges | $2.10 | - cures scurvy |\n| | | - tasty |\n+-----------+-----------+--------------------+\n\n: Sample grid table.\n\n\nThe row of `=`s separates the header from the table body, and can be omitted for a headerless table. The cells of grid tables may contain arbitrary block elements (multiple paragraphs, code blocks, lists, etc.)\n\nAlignments can be specified as with pipe tables, by putting colons at the boundaries of the separator line after the header:\n\n\n``` markdown\n+---------+--------+------------------+\n| Right | Left | Centered |\n+========:+:=======+:================:+\n| Bananas | $1.34 | built-in wrapper |\n+---------+--------+------------------+\n```\nWhich looks like this when rendered to HTML:\n\n+---------+--------+------------------+\n| Right | Left | Centered |\n+========:+:=======+:================:+\n| Bananas | $1.34 | built-in wrapper |\n+---------+--------+------------------+\n\n\nFor headerless tables, the colons go on the top line instead:\n\n``` markdown\n+----------:+:----------+:--------:+\n| Right | Left | Centered |\n+-----------+-----------+----------+\n```\n\nWhich looks like this when rendered to HTML:\n\n+----------:+:----------+:--------:+\n| Right | Left | Centered |\n+-----------+-----------+----------+\n\n\nNote that grid tables are quite awkward to write with a plain text editor (because unlike pipe tables, the column indicators must align). Here are some tools that can assist with creating grid tables:\n\n- Emacs' [table-mode](https://www.gnu.org/software/emacs/manual/html_node/emacs/Text-Based-Tables.html) (`M-x table-insert`)\n- Quarto [Visual Editor](/docs/visual-editor/content.qmd#editing-tables)\n- Tables Generator's [Plain Text mode](https://www.tablesgenerator.com/text_tables) with `Use reStructuredText syntax` enabled\n\n::: callout-warning\n\n## Shortcodes are not supported\n\nIn Quarto, shortcodes are processed internally by transforming the Markdown text ahead of Pandoc.\nUnfortunately, it's not possible to do this transformation in a way that preserves the grid table structure.\nAs a result, shortcodes are not supported inside grid tables. Consider using [list tables](#list-tables) instead.\n\n:::\n\n## HTML Tables\n\nQuarto can process HTML tables in `html` `RawBlock` nodes (_i.e._, `{=html}`) and convert them to Markdown tables, regardless of the output format (intentionally including non-HTML formats).\nAs a result, you can use HTML table syntax in your documents and it will be converted to Markdown syntax for all formats.\nAdditionally, libraries that emit computational tables in HTML format can work in other output formats.\n\nFor example, consider the following raw HTML block:\n\n````markdown\n```{=html}\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
As described in the section above, Quarto tables are great.
Header 1Header 2
\"AfricanRegular output
\n```\n````\n\nWhen rendered, this results in the following output for HTML and PDF formats:\n\n::: {layout-ncol=2}\n\n:::: {}\n### HTML Output\n\n```{=html}\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n
As described in the section above, Quarto tables are great.
Header 1Header 2
\"AfricanRegular output
\n```\n::::\n\n:::: {}\n### PDF Output\n\n![](images/raw-table-pdf.png){.border fig-alt=\"Screenshot of PDF output showing a table with a caption and two columns. The column headers are Header 1 and Header 2, and the cell contents are an image of an elephant and text that reads Regular Output.\"}\n::::\n\n:::\n\nIn addition, Quarto supports the specification of embedded Markdown content in raw table markup. This allows Quarto features like cross-references, shortcodes, and markdown formatting to be used inside tables produced by libraries that emit raw HTML or LaTeX.\n\n#### HTML Raw Blocks\n\nFor HTML raw blocks, this is done by providing a data attribute `qmd` or `qmd-base64` in an embedded `span` or `div` node. These nodes can appear anywhere that such content is allowed: table headers, footers, cells, captions, _etc._\n\nFor example, the following table includes a cross reference, markdown formatting and a shortcode:\n\n:::: {layout-nrow=\"2\"}\n\n::: {}\n\n```` markdown\n## HTML Tables Example {#sec-html-tables}\n\n```{=html}\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n
}}}\">Regular output
\n```\n````\n\n:::\n\n::: {}\n\nWhich renders as follows:\n\n## HTML Tables Example {#sec-html-tables}\n\n```{=html}\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n
}}\">Regular output
\n```\n\n:::\n\n::::\n\n#### LaTeX Raw Blocks\n\nFor LaTeX raw blocks (used in PDF output), the equivalent syntax is `\\QuartoMarkdownBase64{<>}`. When Quarto detects this command, it decodes the base64 content, processes it as Quarto markdown (including cross-references, shortcodes, and user filters), and inserts the result back into the LaTeX output.\n\nFor example, the following LaTeX raw block uses cross-references and markdown formatting inside a table:\n\n```` markdown\n## LaTeX Tables Example {#sec-latex-tables}\n\n```{=latex}\n\\begin{tabular}{ll}\n % X0hlYWRlciAxXw== is base64 for \"_Header 1_\"\n \\QuartoMarkdownBase64{X0hlYWRlciAxXw==} &\n % X0hlYWRlciAyXw== is base64 for \"_Header 2_\"\n \\QuartoMarkdownBase64{X0hlYWRlciAyXw==} \\\\\n % U2VlIEBzZWMtbGF0ZXgtdGFibGVzLg== is base64 for\n % \"See @sec-latex-tables.\"\n \\QuartoMarkdownBase64{U2VlIEBzZWMtbGF0ZXgtdGFibGVzLg==} &\n Regular output \\\\\n\\end{tabular}\n```\n````\n\nWhen rendered to PDF, this table would display with italic headers (*Header 1* and *Header 2*), and the cross-reference `@sec-latex-tables` would be resolved to a clickable section link.\n\n::: {.callout-note}\nUnlike the HTML feature, only base64-encoded content is supported for LaTeX raw blocks (there is no plain-text equivalent of `data-qmd`). This feature cannot be disabled, but this should not be necessary since `\\QuartoMarkdownBase64` is unlikely to conflict with existing LaTeX commands.\n:::\n\n::: {.callout-warning}\nCitations do not currently work inside `\\QuartoMarkdownBase64`. See [GitHub issue #9342](https://github.com/quarto-dev/quarto-cli/issues/9342) for details.\n:::\n\n### Colspans and Rowspans\n\nTables containing cells spanning multiple rows or columns are supported across output formats[except in PDF margins]{.aside}.\n\nHowever, using markdown, it is tricky to draw grid tables with spans, and there is no way to express spans in pipe tables. \n\nIf you are comfortable with HTML, or use a package that generates HTML, the table cell HTML attributes `colspan` and `rowspan` are a better option.\n\n```{=html}\n\n\t\n\t\t\n\t\n\t\n\t\t\n\t\n\t\n\t\t\n\t\n
I span two columnsC1
I span two rowsB2C2
B3C3
\n\n```\n\n````html\n```{=html}\n\n\t\n\t\t\n\t\n\t\n\t\t\n\t\n\t\n\t\t\n\t\n
I span two columnsC1
I span two rowsB2C2
B3C3
\n\n```\n````\n\n\n### Individual cell alignment\n\nMarkdown supports specification of alignment by column, but does not allow setting the alignment of individual cells. The CSS properties `text-align` and `vertical-align` are only available through Raw HTML. (These are not currently supported by PDF/Latex or Pptx output formats, and Docx only supports `text-align`.)\n\n\n```{=html}\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
vertical-align: topvertical-align: middlevertical-align: bottom
text-align: left
text-align: center
text-align: right
\n \n\n```\n\n````html\n```{=html}\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
vertical-align: topvertical-align: middlevertical-align: bottom
text-align: left
text-align: center
text-align: right
\n \n\n```\n````\n\n## Disabling Quarto Table Processing\n\nIt's possible that Quarto's processing of HTML tables may interfere with the HTML produced computationally with table packages in R and Python (or other supported languages).\n\n\nWhen you disable Quarto's HTML table processing, tables are not translated to Markdown, will not be rendered to other output formats, and can not use Quarto Markdown features, like cross-references, shortcodes, etc.\nThe tables also won't be visible to Lua filters that act on `Table` nodes.\n\nYou can disable Quarto's HTML table processing at a document level or project level with the option `html-table-processing`:\n\n```{.yaml}\n---\nformat:\n html:\n html-table-processing: none\n---\n```\n\nThis option is also available as a code cell option for Knitr and Jupyter, e.g. \n\n````{markdown}\n```{{r}}\n#| html-table-processing: none\n\n# R Code that generates an HTML table\n```\n````\n\nTo disable Quarto's HTML table processing for parts of a document use a div with the attribute `html-table-processing=\"none\"`:\n\n````{.markdown}\n::: {html-table-processing=\"none\"}\n\nContent with HTML tables you don't want processed.\n\n:::\n````\n\n### Library authors\n\nIf you are the author of a library that emits HTML tables you might like to disable Quarto's processing of HTML tables by adding the attribute `data-quarto-disable-processing=\"true\"` to the `` element. For example:\n\n```html\n
\n ...\n
\n```\n\nAdditionally, you can add the comment `` to the HTML raw block, and Quarto will not attempt to process it.\n\n", "supporting": [ "tables_files" ], diff --git a/docs/authoring/_table-crossrefs.md b/docs/authoring/_table-crossrefs.md index 4ecf522057..dfd8b9a927 100644 --- a/docs/authoring/_table-crossrefs.md +++ b/docs/authoring/_table-crossrefs.md @@ -16,4 +16,10 @@ See @tbl-letters. Which looks like this when rendered to HTML: +::: light-content ![](images/crossref-table.png){fig-alt="A table with 3 columns and four rows. The text 'Table 1: My Caption' is above the header column. The text 'See tbl. 1' is aligned to the left underneath the last column." width="500"} +::: + +::: dark-content +![](images/crossref-table-dark.png){fig-alt="A table with 3 columns and four rows. The text 'Table 1: My Caption' is above the header column. The text 'See tbl. 1' is aligned to the left underneath the last column." width="500"} +::: diff --git a/docs/authoring/elephant-dark.png b/docs/authoring/elephant-dark.png new file mode 100644 index 0000000000..b379ed621e Binary files /dev/null and b/docs/authoring/elephant-dark.png differ diff --git a/docs/authoring/figures.qmd b/docs/authoring/figures.qmd index f00d6e9086..0891335416 100644 --- a/docs/authoring/figures.qmd +++ b/docs/authoring/figures.qmd @@ -18,9 +18,21 @@ In Pandoc markdown, a figure is created whenever a captioned image appears by-it This results in the following treatment for various output types: -| HTML | PDF | Word | -|---------------------------|-----------------------|-----------------------| -| ![](images/html-figure.png){fig-alt="A line drawing of an elephant." width="340"} | ![](images/pdf-figure.png){fig-alt="A line drawing of an elephant."} | ![](images/word-figure.png){fig-alt="A line drawing of an elephant."} | +::: {.list-table header-rows=1 tbl-colwidths="[33,33,33]"} +- - HTML + - PDF + - Word + +- - ::: light-content + ![](images/html-figure.png){fig-alt="A line drawing of an elephant." width="340"} + ::: + + ::: dark-content + ![](images/html-figure-dark.png){fig-alt="A line drawing of an elephant." width="340"} + ::: + - ![](images/pdf-figure.png){fig-alt="A line drawing of an elephant."} + - ![](images/word-figure.png){fig-alt="A line drawing of an elephant."} +::: Note that for LaTeX / PDF output figures are automatically numbered (you can arrange for figures to be numbered in other formats using [Cross References](cross-references.qmd)). @@ -139,9 +151,15 @@ format: In HTML output formats you can add lightbox styling and behavior to images to allow a reader to click to see a larger version of the image. For example, the following image has lightbox treatment (click on the image to see lightbox in action): +::: light-content ![An elephant](elephant.png){.lightbox width=50%} +::: + +::: dark-content +![An elephant](elephant-dark.png){.lightbox width=50%} +::: -Lightbox treatment can be added by adding the class `.lightbox` to an image: +Lightbox treatment can be added by adding the class `.lightbox` to an image: ```markdown ![An elephant](elephant.png){.lightbox} @@ -205,7 +223,13 @@ Famous Elephants Again, the last paragraph provides the main caption, and the individual figures carry the sub-captions. Here is what this looks like when rendered as HTML: +::: light-content ![](images/elephant-subfigures.png){fig-alt="An artistic rendition of Surus, Hannibal's last war elephant, is on the left. Underneath this picture is the caption '(a) Surus.' On the right is a line drawing of Hanno, a famous elephant. Underneath this picture is the caption '(b) Hanno.' The words 'Figure 1: Famous elephants' are centered beneath both pictures."} +::: + +::: dark-content +![](images/elephant-subfigures-dark.png){fig-alt="An artistic rendition of Surus, Hannibal's last war elephant, is on the left. Underneath this picture is the caption '(a) Surus.' On the right is a line drawing of Hanno, a famous elephant. Underneath this picture is the caption '(b) Hanno.' The words 'Figure 1: Famous elephants' are centered beneath both pictures."} +::: Note that the empty lines between the figures (and between the last figure and the caption) are required (it's what indicates that these images belong to their own paragraphs rather than being multiple images within the same paragraph). @@ -225,7 +249,13 @@ To layout two figures with their own standalone captions (and no main caption), ::: ``` +::: light-content ![](images/elephant-figures-no-subcaption.png){fig-alt="An artistic rendition of Surus, Hannibal's last war elephant, is on the left. Underneath this picture is the caption 'Surus.' On the right is a line drawing of Hanno, a famous elephant. Underneath this picture is the caption 'Hanno.'"} +::: + +::: dark-content +![](images/elephant-figures-no-subcaption-dark.png){fig-alt="An artistic rendition of Surus, Hannibal's last war elephant, is on the left. Underneath this picture is the caption 'Surus.' On the right is a line drawing of Hanno, a famous elephant. Underneath this picture is the caption 'Hanno.'"} +::: You can also eliminate the captions entirely: @@ -253,7 +283,13 @@ If you have more than 2 images, you might want to lay them out across multiple r ::: ``` +::: light-content ![](images/elephant-rows.png){fig-alt="A 2x2 grid of pictures of elephants. There are labels underneath each of the pictures. Clockwise from the upper left, the labels say: Surus, Hanno, Lin Wang, and Abdul Abbas."} +::: + +::: dark-content +![](images/elephant-rows-dark.png){fig-alt="A 2x2 grid of pictures of elephants. There are labels underneath each of the pictures. Clockwise from the upper left, the labels say: Surus, Hanno, Lin Wang, and Abdul Abbas."} +::: More complex figure arrangements (e.g. rows with varying column layouts) are possible. See the [Custom Layouts](#complex-layouts) section below for more details. @@ -404,7 +440,13 @@ For example, this defines a layout with two equally sized figures in the first r ::: ``` +::: light-content ![](images/layout-attrib.png){fig-alt="Three elephant pictures arranged such that two pictures are side-by-side in the first row, and the third picture is underneath both of these. The picture on the left in the first row is captioned 'Surus' and the picture on the right is captioned 'Hanno'. The picture underneath these two is captioned 'Lin Wang' and is as as wide and tall as the other two put together."} +::: + +::: dark-content +![](images/layout-attrib-dark.png){fig-alt="Three elephant pictures arranged such that two pictures are side-by-side in the first row, and the third picture is underneath both of these. The picture on the left in the first row is captioned 'Surus' and the picture on the right is captioned 'Hanno'. The picture underneath these two is captioned 'Lin Wang' and is as as wide and tall as the other two put together."} +::: The `layout` attribute is a 2-dimensional array where the first dimension defines rows and the second columns. In this case `"layout="[[1,1], [1]]"` translates to: create two rows, the first of which has two columns of equal size and the second of which has a single column. @@ -432,7 +474,13 @@ You can also use negative values to create space between elements. For example: ::: ``` +::: light-content ![](images/layout-attrib-negative.png){fig-alt="Three elephant pictures arranged such that two pictures are side-by-side in the first row, and the third picture is underneath both of these. The picture on the left in the first row is captioned 'Surus' and the picture on the right is captioned 'Hanno'. The two pictures are separated by some whitespace. The picture underneath these two is captioned 'Lin Wang' and is wider and taller than the other two put together."} +::: + +::: dark-content +![](images/layout-attrib-negative-dark.png){fig-alt="Three elephant pictures arranged such that two pictures are side-by-side in the first row, and the third picture is underneath both of these. The picture on the left in the first row is captioned 'Surus' and the picture on the right is captioned 'Hanno'. The two pictures are separated by some whitespace. The picture underneath these two is captioned 'Lin Wang' and is wider and taller than the other two put together."} +::: ### Vertical Alignment @@ -446,7 +494,13 @@ If you have a layout with a row of images of differing heights, you can control ::: ``` +::: light-content ![](images/valign.png){fig-alt="Two pictures of elephants side by side. The picture on the left has the label 'Figure 1: Surus' underneath it. The picture on the right has the label 'Figure 2: Lin Wang' underneath it. The figure on the left is more than twice the width and height of the figure on the right."} +::: + +::: dark-content +![](images/valign-dark.png){fig-alt="Two pictures of elephants side by side. The picture on the left has the label 'Figure 1: Surus' underneath it. The picture on the right has the label 'Figure 2: Lin Wang' underneath it. The figure on the left is more than twice the width and height of the figure on the right."} +::: Note that vertical alignment isn't limited to images, you can also vertically align any other elements that are included in a panel. diff --git a/docs/authoring/images/crossref-table-dark.png b/docs/authoring/images/crossref-table-dark.png new file mode 100644 index 0000000000..c1a85aa7e6 Binary files /dev/null and b/docs/authoring/images/crossref-table-dark.png differ diff --git a/docs/authoring/images/elephant-figures-no-subcaption-dark.png b/docs/authoring/images/elephant-figures-no-subcaption-dark.png new file mode 100644 index 0000000000..0f467d7470 Binary files /dev/null and b/docs/authoring/images/elephant-figures-no-subcaption-dark.png differ diff --git a/docs/authoring/images/elephant-rows-dark.png b/docs/authoring/images/elephant-rows-dark.png new file mode 100644 index 0000000000..67335d687e Binary files /dev/null and b/docs/authoring/images/elephant-rows-dark.png differ diff --git a/docs/authoring/images/elephant-subfigures-dark.png b/docs/authoring/images/elephant-subfigures-dark.png new file mode 100644 index 0000000000..3add5f9028 Binary files /dev/null and b/docs/authoring/images/elephant-subfigures-dark.png differ diff --git a/docs/authoring/images/html-figure-dark.png b/docs/authoring/images/html-figure-dark.png new file mode 100644 index 0000000000..44f2b28d87 Binary files /dev/null and b/docs/authoring/images/html-figure-dark.png differ diff --git a/docs/authoring/images/layout-attrib-dark.png b/docs/authoring/images/layout-attrib-dark.png new file mode 100644 index 0000000000..b9f9103a30 Binary files /dev/null and b/docs/authoring/images/layout-attrib-dark.png differ diff --git a/docs/authoring/images/layout-attrib-negative-dark.png b/docs/authoring/images/layout-attrib-negative-dark.png new file mode 100644 index 0000000000..6495ea275f Binary files /dev/null and b/docs/authoring/images/layout-attrib-negative-dark.png differ diff --git a/docs/authoring/images/valign-dark.png b/docs/authoring/images/valign-dark.png new file mode 100644 index 0000000000..6f9fdc93f9 Binary files /dev/null and b/docs/authoring/images/valign-dark.png differ diff --git a/docs/authoring/markdown-basics.css b/docs/authoring/markdown-basics.css new file mode 100644 index 0000000000..18d7e97562 --- /dev/null +++ b/docs/authoring/markdown-basics.css @@ -0,0 +1,9 @@ +.heading-output { + border-bottom: none; + margin-top: 0; + margin-bottom: 0; +} + +.pad-to-code-block { + padding-top: 1rem; +} diff --git a/docs/authoring/markdown-basics.qmd b/docs/authoring/markdown-basics.qmd index 7223ee7f96..872f84f2f5 100644 --- a/docs/authoring/markdown-basics.qmd +++ b/docs/authoring/markdown-basics.qmd @@ -1,10 +1,12 @@ --- title: Markdown Basics format: html -language: +language: section-title-footnotes: Example Footnotes -aliases: +aliases: - /docs/authoring/ +css: + - markdown-basics.css --- ## Overview @@ -80,56 +82,107 @@ Violets are blue. : {tbl-colwidths="[50, 50]"} -```{=html} - -``` ## Links & Images -+------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+ -| Markdown Syntax | Output | -+========================================================================+========================================================================================================+ -| ``` markdown | | -| | | -| ``` | | -+------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+ -| ``` markdown | [Quarto](https://quarto.org) | -| [Quarto](https://quarto.org) | | -| ``` | | -+------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+ -| ``` markdown | [Markdown Basics](./markdown-basics.qmd) | -| [Markdown Basics](./markdown-basics.qmd) | | -| ``` | | -+------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+ -| ``` markdown | [Markdown Basics - Links & Images](./markdown-basics.qmd#links-images) | -| [Markdown Basics - Links & Images](./markdown-basics.qmd#links-images) | | -| ``` | | -+------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+ -| ``` markdown | [Markdown Basics - Links & Images](#links-images) | -| [Markdown Basics - Links & Images](#links-images) | | -| ``` | | -+------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+ -| ``` markdown | ![Caption](elephant.png){fig-alt="A line drawing of an elephant."} | -| ![Caption](elephant.png) | | -| ``` | | -+------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+ -| ``` markdown | [![Caption](elephant.png)](https://quarto.org) | -| [![Caption](elephant.png)](https://quarto.org) | | -| ``` | | -+------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+ -| ``` markdown | [![Caption](elephant.png "An elephant"){fig-alt="A line drawing of an elephant."}](https://quarto.org) | -| [![Caption](elephant.png "An elephant")](https://quarto.org) | | -| ``` | | -+------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+ -| ``` markdown | [![](elephant.png){fig-alt="A line drawing of an elephant."}](https://quarto.org) | -| [![](elephant.png){fig-alt="Alt text"}](https://quarto.org) | | -| ``` | | -+------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------+ +::: {.list-table header-rows=1 tbl-colwidths="[50, 50]"} +- - Markdown Syntax + - Output + +- - ``` markdown + + ``` + - ::: pad-to-code-block + + ::: + +- - ``` markdown + [Quarto](https://quarto.org) + ``` + - ::: pad-to-code-block + [Quarto](https://quarto.org) + ::: + +- - ``` markdown + [Markdown Basics](./markdown-basics.qmd) + ``` + - ::: pad-to-code-block + [Markdown Basics](./markdown-basics.qmd) + ::: + +- - ``` markdown + [Markdown Basics - Links & Images](./markdown-basics.qmd#links-images) + ``` + - ::: pad-to-code-block + [Markdown Basics - Links & Images](./markdown-basics.qmd#links-images) + ::: + +- - ``` markdown + [Markdown Basics - Links & Images](#links-images) + ``` + - ::: pad-to-code-block + [Markdown Basics - Links & Images](#links-images) + ::: + +- - ``` markdown + ![Caption](elephant.png) + ``` + - ::: pad-to-code-block + + ::: light-content + ![Caption](elephant.png){fig-alt="A line drawing of an elephant."} + ::: + + ::: dark-content + ![Caption](elephant-dark.png){fig-alt="A line drawing of an elephant."} + ::: + + ::: + +- - ``` markdown + [![Caption](elephant.png)](https://quarto.org) + ``` + - ::: pad-to-code-block + + ::: light-content + [![Caption](elephant.png)](https://quarto.org) + ::: + + ::: dark-content + [![Caption](elephant-dark.png)](https://quarto.org) + ::: + + ::: + +- - ``` markdown + [![Caption](elephant.png "An elephant")](https://quarto.org) + ``` + - ::: pad-to-code-block + + ::: light-content + [![Caption](elephant.png "An elephant"){fig-alt="A line drawing of an elephant."}](https://quarto.org) + ::: + + ::: dark-content + [![Caption](elephant-dark.png "An elephant"){fig-alt="A line drawing of an elephant."}](https://quarto.org) + ::: + + ::: + +- - ``` markdown + [![](elephant.png){fig-alt="Alt text"}](https://quarto.org) + ``` + - ::: pad-to-code-block + + ::: light-content + [![](elephant.png){fig-alt="A line drawing of an elephant."}](https://quarto.org) + ::: + + ::: dark-content + [![](elephant-dark.png){fig-alt="A line drawing of an elephant."}](https://quarto.org) + ::: + + ::: +::: ## Lists