From 51039c90b99d105062e5c788f97973204eb62239 Mon Sep 17 00:00:00 2001 From: Charlotte Wickham Date: Tue, 22 Oct 2024 14:48:55 -0700 Subject: [PATCH 1/3] Add description of what disabling means (cherry picked from commit 115d6cce7d42b32c1b72df2465b8f96614a638c8) --- docs/authoring/tables.qmd | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/authoring/tables.qmd b/docs/authoring/tables.qmd index 0fc1d09768..f3f955b3e4 100644 --- a/docs/authoring/tables.qmd +++ b/docs/authoring/tables.qmd @@ -619,6 +619,8 @@ Content with HTML tables you don't want processed. ::: ```` +When 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. + ### Library authors If 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: From 8fdfa7e2b8fda110485377693710cc8676a8c970 Mon Sep 17 00:00:00 2001 From: Charlotte Wickham Date: Tue, 22 Oct 2024 15:23:03 -0700 Subject: [PATCH 2/3] Update freeze (cherry picked from commit f5921bf7190de85104b39f3363a7c4aa12967d69) --- _freeze/docs/authoring/tables/execute-results/html.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_freeze/docs/authoring/tables/execute-results/html.json b/_freeze/docs/authoring/tables/execute-results/html.json index 444bebfd78..4b2d0f6a4c 100644 --- a/_freeze/docs/authoring/tables/execute-results/html.json +++ b/_freeze/docs/authoring/tables/execute-results/html.json @@ -1,8 +1,8 @@ { - "hash": "cefdf10b565499a41d03a4ad20bb117a", + "hash": "78d7c1dfae51551ba9b284987dfa8be4", "result": { "engine": "jupyter", - "markdown": "---\ntitle: Tables\nengine: jupyter\naliases: \n - /docs/prerelease/1.5/lua-table-processing.html\n---\n\n\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\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\nSee the article on [Cross References](cross-references.qmd) for additional details.\n\n### Subtables\n\n\nYou may want to create a composition of several sub-tables. To do this, create a div with a main identifier, then apply sub-identifiers (and optional caption text) to the contained tables. For example:\n\n``` markdown\n::: {#tbl-panel layout-ncol=2}\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: First Table {#tbl-first}\n\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: Second Table {#tbl-second}\n\nMain Caption\n:::\n\nSee @tbl-panel for details, especially @tbl-second.\n```\n\nWhich looks like this when rendered to HTML:\n\n![](/docs/authoring/images/crossref-subtable.png){fig-alt=\"Two tables side-by-side. Both tables have 3 columns and 4 rows. The table on the left is titled '(a) First table'. The table on the right is titled '(b) Second Table'. Centered underneath both tables is the text 'Table 1: Main Caption'. The text 'See tbl. 2 for details, especially tbl. 2 (b)' is aligned to the left underneath that.\"}\n\nNote that the \"Main Caption\" for the table is provided as the last block within the containing div.\n\n\n\n## 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## 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\n\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::::\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 tables.\nThis is done by providing a data attribute `qmd` or `qmd-base64` in an embedded `span` or `div` node.\nThese 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\n\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\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\n\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\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\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\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\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\n\n\n````{markdown}\n```{{r}}\n#| html-table-processing: none\n\n# R Code that generates an HTML table\n```\n````\n\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\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\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\nSee the article on [Cross References](cross-references.qmd) for additional details.\n\n### Subtables\n\n\nYou may want to create a composition of several sub-tables. To do this, create a div with a main identifier, then apply sub-identifiers (and optional caption text) to the contained tables. For example:\n\n``` markdown\n::: {#tbl-panel layout-ncol=2}\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: First Table {#tbl-first}\n\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: Second Table {#tbl-second}\n\nMain Caption\n:::\n\nSee @tbl-panel for details, especially @tbl-second.\n```\n\nWhich looks like this when rendered to HTML:\n\n![](/docs/authoring/images/crossref-subtable.png){fig-alt=\"Two tables side-by-side. Both tables have 3 columns and 4 rows. The table on the left is titled '(a) First table'. The table on the right is titled '(b) Second Table'. Centered underneath both tables is the text 'Table 1: Main Caption'. The text 'See tbl. 2 for details, especially tbl. 2 (b)' is aligned to the left underneath that.\"}\n\nNote that the \"Main Caption\" for the table is provided as the last block within the containing div.\n\n\n\n## 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## 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\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:::: {}\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 tables.\nThis is done by providing a data attribute `qmd` or `qmd-base64` in an embedded `span` or `div` node.\nThese 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\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\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\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````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\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````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\nWhen disabling this step, Quarto will not process the HTML table as if it had been authored as a Markdown table.\nThese tables (and their contents) won't be visible by Lua filters that act on `Table` nodes, and so Quarto's table fixups will be generally unavailable.\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\n````{markdown}\n```{{r}}\n#| html-table-processing: none\n\n# R Code that generates an HTML table\n```\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\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.\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" ], From 23b8df0e04809a4b72c880b20a55fdcf279e6c8c Mon Sep 17 00:00:00 2001 From: Charlotte Wickham Date: Wed, 23 Oct 2024 14:15:37 -0700 Subject: [PATCH 3/3] Merge similar paragraphs (cherry picked from commit ffe339482d4c621311eea01494ec962e37a50494) --- _freeze/docs/authoring/tables/execute-results/html.json | 4 ++-- docs/authoring/tables.qmd | 9 +++++++-- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/_freeze/docs/authoring/tables/execute-results/html.json b/_freeze/docs/authoring/tables/execute-results/html.json index 4b2d0f6a4c..468d9d2bfc 100644 --- a/_freeze/docs/authoring/tables/execute-results/html.json +++ b/_freeze/docs/authoring/tables/execute-results/html.json @@ -1,8 +1,8 @@ { - "hash": "78d7c1dfae51551ba9b284987dfa8be4", + "hash": "f5ba4756cc531f11e9ea2b640cae0834", "result": { "engine": "jupyter", - "markdown": "---\ntitle: Tables\nengine: jupyter\naliases: \n - /docs/prerelease/1.5/lua-table-processing.html\n---\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\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\nSee the article on [Cross References](cross-references.qmd) for additional details.\n\n### Subtables\n\n\nYou may want to create a composition of several sub-tables. To do this, create a div with a main identifier, then apply sub-identifiers (and optional caption text) to the contained tables. For example:\n\n``` markdown\n::: {#tbl-panel layout-ncol=2}\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: First Table {#tbl-first}\n\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: Second Table {#tbl-second}\n\nMain Caption\n:::\n\nSee @tbl-panel for details, especially @tbl-second.\n```\n\nWhich looks like this when rendered to HTML:\n\n![](/docs/authoring/images/crossref-subtable.png){fig-alt=\"Two tables side-by-side. Both tables have 3 columns and 4 rows. The table on the left is titled '(a) First table'. The table on the right is titled '(b) Second Table'. Centered underneath both tables is the text 'Table 1: Main Caption'. The text 'See tbl. 2 for details, especially tbl. 2 (b)' is aligned to the left underneath that.\"}\n\nNote that the \"Main Caption\" for the table is provided as the last block within the containing div.\n\n\n\n## 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## 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\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:::: {}\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 tables.\nThis is done by providing a data attribute `qmd` or `qmd-base64` in an embedded `span` or `div` node.\nThese 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\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\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\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````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\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````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\nWhen disabling this step, Quarto will not process the HTML table as if it had been authored as a Markdown table.\nThese tables (and their contents) won't be visible by Lua filters that act on `Table` nodes, and so Quarto's table fixups will be generally unavailable.\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\n````{markdown}\n```{{r}}\n#| html-table-processing: none\n\n# R Code that generates an HTML table\n```\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\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.\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\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\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\nSee the article on [Cross References](cross-references.qmd) for additional details.\n\n### Subtables\n\n\nYou may want to create a composition of several sub-tables. To do this, create a div with a main identifier, then apply sub-identifiers (and optional caption text) to the contained tables. For example:\n\n``` markdown\n::: {#tbl-panel layout-ncol=2}\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: First Table {#tbl-first}\n\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: Second Table {#tbl-second}\n\nMain Caption\n:::\n\nSee @tbl-panel for details, especially @tbl-second.\n```\n\nWhich looks like this when rendered to HTML:\n\n![](/docs/authoring/images/crossref-subtable.png){fig-alt=\"Two tables side-by-side. Both tables have 3 columns and 4 rows. The table on the left is titled '(a) First table'. The table on the right is titled '(b) Second Table'. Centered underneath both tables is the text 'Table 1: Main Caption'. The text 'See tbl. 2 for details, especially tbl. 2 (b)' is aligned to the left underneath that.\"}\n\nNote that the \"Main Caption\" for the table is provided as the last block within the containing div.\n\n\n\n## 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## 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\n\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::::\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 tables.\nThis is done by providing a data attribute `qmd` or `qmd-base64` in an embedded `span` or `div` node.\nThese 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\n\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\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\n\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\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\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\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\n\n\n````{markdown}\n```{{r}}\n#| html-table-processing: none\n\n# R Code that generates an HTML table\n```\n````\n\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/tables.qmd b/docs/authoring/tables.qmd index f3f955b3e4..4f87e7c03f 100644 --- a/docs/authoring/tables.qmd +++ b/docs/authoring/tables.qmd @@ -589,6 +589,13 @@ Markdown supports specification of alignment by column, but does not allow setti It'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). +<<<<<<< HEAD +======= + +When 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. +The tables also won't be visible to Lua filters that act on `Table` nodes. + +>>>>>>> ffe339482 (Merge similar paragraphs) You can disable Quarto's HTML table processing at a document level or project level with the option `html-table-processing`: ```{.yaml} @@ -619,8 +626,6 @@ Content with HTML tables you don't want processed. ::: ```` -When 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. - ### Library authors If 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: