From 8fa3774be0ccd213ff9e011749fcc171b39641f5 Mon Sep 17 00:00:00 2001 From: Carlos Scheidegger Date: Thu, 9 Oct 2025 19:13:14 -0500 Subject: [PATCH 1/3] docs --- docs/authoring/tables.qmd | 352 +++++++++++++++++++++++++++- docs/prerelease/1.9/_highlights.qmd | 2 + 2 files changed, 353 insertions(+), 1 deletion(-) diff --git a/docs/authoring/tables.qmd b/docs/authoring/tables.qmd index cecf456a7e..d98129858f 100644 --- a/docs/authoring/tables.qmd +++ b/docs/authoring/tables.qmd @@ -353,7 +353,15 @@ tibble::tribble( ## Grid Tables -Grid tables are a more advanced type of markdown tables that allow arbitrary block elements (multiple paragraphs, code blocks, lists, etc.). For example: +Grid tables are a more advanced type of markdown tables that allow arbitrary block elements (multiple paragraphs, code blocks, lists, etc.). + +::: {.callout-tip} +## Consider List Tables + +While grid tables are fully supported, [List Tables](#list-tables) provide an easier-to-maintain alternative with the same capabilities. List tables are easier to edit in plain text and produce cleaner diffs in version control. +::: + +For example: ``` markdown @@ -427,6 +435,348 @@ Note that grid tables are quite awkward to write with a plain text editor (becau - Quarto [Visual Editor](/docs/visual-editor/content.qmd#editing-tables) - Tables Generator's [Plain Text mode](https://www.tablesgenerator.com/text_tables) with `Use reStructuredText syntax` enabled +## List Tables + +List tables provide an easier-to-maintain alternative to grid tables, using a ReStructuredText-inspired syntax based on nested lists. They support the same advanced features as grid tables (arbitrary block elements, multiple paragraphs, code blocks, lists, etc.) while being much easier to edit in a plain text editor. + +::: {.callout-note} +List table syntax was originally developed by [Martin Fischer](https://github.com/pushshift) with contributions from [Albert Krewinkel](https://github.com/tarleb) and [William Lupton](https://github.com/wlupton). +::: + +### Basic Syntax + +List tables use a fenced div with the `.list-table` class. Each list item represents a row, and nested list items within represent cells: + +::: {layout-ncol="2"} + +:::: {} + +``` markdown +::: {.list-table} + +* - Row 1, Col 1 + - Row 1, Col 2 + - Row 1, Col 3 + +* - Row 2, Col 1 + - Row 2, Col 2 + - Row 2, Col 3 + +::: +``` + +:::: + +:::: {} + +::: {.list-table} + +* - Row 1, Col 1 + - Row 1, Col 2 + - Row 1, Col 3 + +* - Row 2, Col 1 + - Row 2, Col 2 + - Row 2, Col 3 + +::: + +:::: + +::: + +### Captions + +To add a caption to your list table, include text at the beginning of the div, before the list: + +::: {layout-ncol="2"} + +:::: {} + +``` markdown +::: {.list-table} + +Sample list table. + +* - Fruit + - Price + +* - Apple + - $1.50 + +* - Orange + - $2.00 + +::: +``` + +:::: + +:::: {} + +::: {.list-table} + +Sample list table. + +* - Fruit + - Price + +* - Apple + - $1.50 + +* - Orange + - $2.00 + +::: + +:::: + +::: + +### Column Configuration + +You can configure column alignment, widths, and headers using attributes: + +#### Column Alignments + +Use the `aligns` attribute to specify alignment for each column. Values are: `l` (left), `c` (center), `r` (right), or `d` (default): + +::: {layout-ncol="2"} + +:::: {} + +``` markdown +::: {.list-table aligns="l,r,c"} + +* - Left + - Right + - Center + +* - Text + - 123 + - More + +::: +``` + +:::: + +:::: {} + +::: {.list-table aligns="l,r,c"} + +* - Left + - Right + - Center + +* - Text + - 123 + - More + +::: + +:::: + +::: + +#### Column Widths + +Use the `widths` attribute to specify relative column widths: + +::: {layout-ncol="2"} + +:::: {} + +``` markdown +::: {.list-table widths="0.7,0.3"} + +* - Wide column + - Narrow + +* - More content here + - Less + +::: +``` + +:::: + +:::: {} + +::: {.list-table widths="0.7,0.3"} + +* - Wide column + - Narrow + +* - More content here + - Less + +::: + +:::: + +::: + +#### Header Rows and Columns + +Use `header-rows` and `header-cols` to specify how many rows/columns should be treated as headers: + +::: {layout-ncol="2"} + +:::: {} + +``` markdown +::: {.list-table header-rows="1"} + +* - Name + - Value + +* - Item 1 + - 100 + +* - Item 2 + - 200 + +::: +``` + +:::: + +:::: {} + +::: {.list-table header-rows="1"} + +* - Name + - Value + +* - Item 1 + - 100 + +* - Item 2 + - 200 + +::: + +:::: + +::: + +### Advanced Features + +List tables support the same advanced features as grid tables: + +#### Multiple Paragraphs and Lists + +Cells can contain multiple paragraphs, lists, and other block elements: + +::: {layout-ncol="2"} + +:::: {} + +::: {.list-table header-rows="1"} + +Example of complex content in cells. + +* - Feature + - Description + +* - Multi-paragraph + + - First paragraph of content. + + Second paragraph of content. + +* - Lists + + - Features: + + - Easy to read + - Easy to maintain + - Flexible syntax + +::: + +:::: + +:::: {} + +````markdown +::: {.list-table header-rows="1"} + +Example of complex content in cells. + +* - Feature + - Description + +* - Multi-paragraph + + - First paragraph of content. + + Second paragraph of content. + +* - Lists + + - Features: + + - Easy to read + - Easy to maintain + - Flexible syntax + +::: +```` + +:::: + +::: + +#### Cell Spanning + +Use `colspan` and `rowspan` attributes on empty list items to merge cells: + +::: {layout-ncol="2"} + +::: {} + +::: {.list-table header-rows="1"} + +* - Name + - Details + - Notes + +* - Product A + - []{colspan="2"} This cell spans two columns + +* - Product B + - Info + - More info + +::: + +::: + +::: {} + +````markdown +::: {.list-table header-rows="1"} + +* - Name + - Details + - Notes + +* - Product A + - []{colspan="2"} This cell spans two columns + +* - Product B + - Info + - More info + +::: +```` + +::: + +::: + ## HTML Tables Quarto 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). diff --git a/docs/prerelease/1.9/_highlights.qmd b/docs/prerelease/1.9/_highlights.qmd index b099f0a68d..1a9ae7a546 100644 --- a/docs/prerelease/1.9/_highlights.qmd +++ b/docs/prerelease/1.9/_highlights.qmd @@ -1,3 +1,5 @@ Quarto 1.9 includes the following new features: +- [List Tables](/docs/authoring/tables.qmd#list-tables): Built-in support for ReStructuredText-style list tables, an easier-to-maintain alternative to grid tables. Originally developed by Martin Fischer with contributions from Albert Krewinkel and William Lupton. + - [`aria-label` for videos](/docs/authoring/videos.qmd#accessibility-label): Improve accessibility of embedded videos by providing custom descriptive labels for screen readers instead of the default "Video Player" label. \ No newline at end of file From daf8c0eee18f9e2849f1e1f037d6f00f905e8f66 Mon Sep 17 00:00:00 2001 From: Carlos Scheidegger Date: Fri, 10 Oct 2025 13:54:58 -0500 Subject: [PATCH 2/3] fenced div syntax for list tables --- docs/authoring/tables.qmd | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/authoring/tables.qmd b/docs/authoring/tables.qmd index d98129858f..90dbac79ae 100644 --- a/docs/authoring/tables.qmd +++ b/docs/authoring/tables.qmd @@ -661,6 +661,33 @@ Use `header-rows` and `header-cols` to specify how many rows/columns should be t ::: +### Crossreferencing + +To reference a list table, use the `tbl-` cross-reference prefix for the table identifier. + +As a Quarto-specific syntax extension, list tables can also provide a caption _after_ the bulleted list, like [fenced divs for cross-referenceable floats](/docs/authoring/cross-references-divs.qmd): + +```` markdown + +::: {#tbl-my-table .list-table header-rows="1"} + +* - Name + - Value + +* - Item 1 + - 100 + +* - Item 2 + - 200 + +This is a caption. + +::: + +See @tbl-my-table. + +```` + ### Advanced Features List tables support the same advanced features as grid tables: From 3b0bf32466c2f4f04fb4ac822bd893355de1f578 Mon Sep 17 00:00:00 2001 From: Carlos Scheidegger Date: Fri, 10 Oct 2025 14:05:15 -0500 Subject: [PATCH 3/3] small tweak --- docs/authoring/tables.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authoring/tables.qmd b/docs/authoring/tables.qmd index 90dbac79ae..f03e30ef6f 100644 --- a/docs/authoring/tables.qmd +++ b/docs/authoring/tables.qmd @@ -663,7 +663,7 @@ Use `header-rows` and `header-cols` to specify how many rows/columns should be t ### Crossreferencing -To reference a list table, use the `tbl-` cross-reference prefix for the table identifier. +To reference a list table, use the `tbl-` cross-reference prefix for the table identifier, same as described above. As a Quarto-specific syntax extension, list tables can also provide a caption _after_ the bulleted list, like [fenced divs for cross-referenceable floats](/docs/authoring/cross-references-divs.qmd):