aboutsummaryrefslogtreecommitdiff
path: root/content
diff options
context:
space:
mode:
authorPaul Duncan <pabs@pablotron.org>2021-10-25 18:24:22 -0400
committerPaul Duncan <pabs@pablotron.org>2021-10-25 18:24:22 -0400
commit69495671b51915d94c54e0cfaac474664ccb8e81 (patch)
treeaf4d103813fd5e48d178f3abcbe74c5a7214eaf4 /content
parente502749cfcd805110c49f02bae03fe8171801d5c (diff)
downloadpablotron.org-69495671b51915d94c54e0cfaac474664ccb8e81.tar.bz2
pablotron.org-69495671b51915d94c54e0cfaac474664ccb8e81.zip
add articles/table-shortcode-examples
Diffstat (limited to 'content')
-rw-r--r--content/articles/table-shortcode-examples.md1375
1 files changed, 1375 insertions, 0 deletions
diff --git a/content/articles/table-shortcode-examples.md b/content/articles/table-shortcode-examples.md
new file mode 100644
index 0000000..093ef1c
--- /dev/null
+++ b/content/articles/table-shortcode-examples.md
@@ -0,0 +1,1375 @@
+---
+slug: "table-shortcode-examples"
+title: "Table Shortcode Examples"
+
+# date (optional for articles)
+date: "2021-10-22T23:11:04-04:00"
+
+# show on articles page
+# show: true
+
+# uncomment to show table of contents
+toc: true
+
+# custom table config for all tables on this page
+table_config:
+ table_class: "table"
+ align_left: "has-text-left"
+ align_center: "has-text-centered"
+ align_justify: "has-text-weight-bold"
+ align_right: "has-text-right"
+
+tables:
+ # available table properties
+ table_props:
+ name: "Table Properties"
+
+ cols:
+ - id: "id"
+ name: "Property"
+ tip: "Property ID."
+ - id: "required"
+ name: "Required?"
+ tip: "Is this property required?"
+ - id: "text"
+ name: "Description"
+ tip: "Property description."
+ - id: "notes"
+ name: "Notes"
+ tip: "Property notes."
+
+ rows:
+ - id: "`id`"
+ required: "No"
+ text: "Table ID."
+ notes: "Used as the `id` attribute of the `<table>` element."
+ - id: "`css`"
+ required: "No"
+ text: "Table [CSS](https://en.wikipedia.org/wiki/CSS) class."
+ notes: "Appended to the `class` attribute of the `<table>` element."
+ - id: "`name`"
+ required: "No"
+ text: "Table name."
+ notes: "Used as the value of the `title` attribute and `aria-label` attribute of the `<table>` element if the `tip` property is not specified."
+ - id: "`tip`"
+ required: "No"
+ text: "Table tooltip."
+ notes: "Used as the value of the `title` attribute and `aria-label` attribute of the `<table>`."
+ - id: "`config`"
+ required: "No"
+ text: "Table config."
+ notes: "Used to override the configuration for this table."
+ - id: "`caption`"
+ required: "No"
+ text: "Table caption."
+ notes: "Value of `<caption>` element for this table."
+ - id: "`cols`"
+ required: "**Yes**"
+ text: "Table columns."
+ notes: "Array of column definitions."
+ - id: "`rows`"
+ required: "**Yes**"
+ text: "Table rows."
+ notes: "Array of rows."
+
+ # available column properties
+ col_props:
+ name: "Column Properties"
+
+ cols:
+ - id: "id"
+ name: "Property"
+ tip: "Property ID."
+ - id: "required"
+ name: "Required?"
+ tip: "Is this property required?"
+ - id: "text"
+ name: "Description"
+ tip: "Property description."
+ - id: "notes"
+ name: "Notes"
+ tip: "Property notes."
+
+ rows:
+ - id: "`id`"
+ required: "**Yes**"
+ text: "Row property which contains the cell value."
+ notes: "n/a"
+ - id: "`name`"
+ required: "**Yes**"
+ text: "Column name."
+ notes: "Used as the content of `<th>` elements and as the tooltip for `<th>` and `<td>` elements if the `tip` column property is not defined."
+ - id: "`tip`"
+ required: "No"
+ text: "Column tooltip."
+ notes: "Used for the `title` and `aria-lable` attributes of `<th>` and `<td>` elements."
+ - id: "`align`"
+ required: "No"
+ text: "Column alignment."
+ notes: "One of `left`, `center`, `justify`, or `right`."
+
+ # available row properties
+ row_props:
+ name: "Row Properties"
+
+ cols:
+ - id: "id"
+ name: "Property"
+ tip: "Property ID."
+ - id: "required"
+ name: "Required?"
+ tip: "Is this property required?"
+ - id: "text"
+ name: "Description"
+ tip: "Property description."
+ - id: "notes"
+ name: "Notes"
+ tip: "Property notes."
+
+ rows:
+ - id: "`_id`"
+ required: "No"
+ text: "Row ID."
+ notes: "Used as the `id` attribute of the generated `<tr>` element."
+ - id: "`_css`"
+ required: "No"
+ text: "Row [CSS class](https://en.wikipedia.org/wiki/CSS)."
+ notes: "Used as value of the `class` attribute of the generated `<tr>` element."
+ - id: "`_tip`"
+ required: "No"
+ text: "Row tooltip."
+ notes: "Used as value of the `title` attribute and the `aria-label` attribute of the generated `<tr>` element."
+
+ row_attrs:
+ name: "Row Attributes"
+
+ cols:
+ - id: "id"
+ name: "Attribute"
+ tip: "Attribute name."
+ - id: "text"
+ name: "Description"
+ tip: "Attribute description."
+ - id: "notes"
+ name: "Notes"
+ tip: "Attribute notes."
+
+ rows:
+ - id: "`id`"
+ text: "n/a"
+ notes: "Generated if the `_id` row property is specified."
+ - id: "`title`"
+ text: "Row tooltip."
+ notes: "Generated if the `_tip` row property is specified."
+ - id: "`aria-label`"
+ text: "Row tooltip."
+ notes: "Generated if the `_tip` row property is specified."
+ - id: "`class`"
+ text: "Row tooltip."
+ notes: "Generated if the `_css` row property is specified."
+ - id: "`data-tr_y`"
+ text: "Zero-indexed Y offset of row position in table."
+ notes: "Can be used to match specific rows using [CSS](https://en.wikipedia.org/wiki/CSS) selectors. Example `#some-table tr[data-tr_y='2']`."
+
+ # available cell properties
+ cell_props:
+ name: "Cell Properties"
+
+ cols:
+ - id: "id"
+ name: "Property"
+ tip: "Property ID."
+ - id: "required"
+ name: "Required?"
+ tip: "Is this property required?"
+ - id: "text"
+ name: "Description"
+ tip: "Property description."
+ - id: "notes"
+ name: "Notes"
+ tip: "Property notes."
+
+ rows:
+ - id: "`id`"
+ required: "No"
+ text: "Cell ID."
+ notes: "Used as the `id` attribute of the generated `<td>` element."
+ - id: "`tip`"
+ required: "No"
+ text: "Cell tooltip."
+ notes: "Used as value of the `title` attribute and the `aria-label` attribute of the generated `<td>` element."
+ - id: "`align`"
+ required: "No"
+ text: "Cell alignment."
+ notes: "One of `left`, `center`, `justify`, or `right`."
+ - id: "`html`"
+ required: "No"
+ text: "Render cell value as HTML?"
+ notes: "One of `true` or `false`. Defaults to `false`."
+ - id: "`css`"
+ required: "No"
+ text: "Cell [CSS class](https://en.wikipedia.org/wiki/CSS \"Cascading Style Sheets\")."
+ notes: "Overrides the `align` property if specified."
+ - id: "`val`"
+ required: "No"
+ text: "Cell value."
+ notes: "Rendered as [HTML](https://en.wikipedia.org/wiki/HTML \"HyperText Markup Language\") if the `html` property is true, and [Markdown](https://en.wikipedia.org/wiki/Markdown \"Markdown markup language\") otherwise."
+
+ cell_attrs:
+ name: "Cell Attributes"
+
+ cols:
+ - id: "id"
+ name: "Attribute"
+ tip: "Attribute name."
+ - id: "text"
+ name: "Description"
+ tip: "Attribute description."
+ - id: "notes"
+ name: "Notes"
+ tip: "Attribute notes."
+
+ rows:
+ - id: "`id`"
+ text: "n/a"
+ notes: "Generated if the `id` cell property is specified."
+ - id: "`title`"
+ text: "Row tooltip."
+ notes: "Set to the value of `tip` cell property is specified, or followed by the value of the `tip` column property. Defaults to the name of the column otherwise."
+ - id: "`aria-label`"
+ text: "Row tooltip."
+ notes: "Set to the value of `tip` cell property is specified, or followed by the value of the `tip` column property. Defaults to the name of the column otherwise."
+ - id: "`class`"
+ text: "Cell [CSS class](https://en.wikipedia.org/wiki/CSS)."
+ notes: "Generated if the `css` cell property is specified, if
+ the cell `align` property is specified, or if the column `align` property is specified."
+ - id: "`data-td_x`"
+ text: "Zero-indexed X offset of cell position in table."
+ notes: "Can be used to match specific columns using [CSS](https://en.wikipedia.org/wiki/CSS) selectors. Example `#some-table td[data-td_x='3']`."
+ - id: "`data-td_id`"
+ text: "Cell column ID."
+ notes: "Can be used to match specific columns using [CSS](https://en.wikipedia.org/wiki/CSS) selectors. Example `#some-table td[data-td_id='text']`."
+
+ # available column alignments
+ align_classes:
+ cols:
+ - id: "align"
+ name: "align"
+ tip: "Value of column `align` property."
+ - id: "class"
+ name: "class"
+ tip: "Generated class attribute for <th> and <td> elements."
+
+ rows:
+ - align: "`left`"
+ class: "`has-text-left`"
+ - align: "`center`"
+ class: "`has-text-centered`"
+ - align: "`justify`"
+ class: "`has-text-justified`"
+ - align: "`right`"
+ class: "`has-text-right`"
+
+ # available table configuration properties
+ table_config_props:
+ cols:
+ - id: "id"
+ name: "Property ID"
+ tip: "Property ID."
+ - id: "text"
+ name: "Description"
+ tip: "Property description."
+ - id: "notes"
+ name: "Notes"
+ tip: "Property notes."
+ - id: "default"
+ name: "Default Value"
+ tip: "Default value."
+
+ rows:
+ - id: "`data_prefix`"
+ text: "Prefix used for all `data-` attributes."
+ notes: "Used to prevent data attribute clashes. For example, if `data_prefix` is set to `zz_`, then the `data-td_x` attribute will be generated as `data-zz_td_z`."
+ default: "(empty)"
+ - id: "`table_class`"
+ text: "Base table [CSS](https://en.wikipedia.org/wiki/CSS \"Cascading Style Sheets\") class."
+ notes: "The `css` property of tables is appended to this class to form the class list. For example, if a table has a `css` property of of `foobar`, then the `<table>` element will be generated with a `class` attribute of `class='table foobar'`."
+ default: "`table`"
+ - id: "`align_left`"
+ text: "Class for left-aligned `<th>` and `<td>` elements."
+ notes: "n/a"
+ default: "`has-text-left`"
+ - id: "`align_center`"
+ text: "Class for center-aligned `<th>` and `<td>` elements."
+ notes: "n/a"
+ default: "`has-text-centered`"
+ - id: "`align_justify`"
+ text: "Class for justified `<th>` and `<td>` elements."
+ notes: "n/a"
+ default: "`has-text-justified`"
+ - id: "`align_right`"
+ text: "Class for right-aligned `<th>` and `<td>` elements."
+ notes: "n/a"
+ default: "`has-text-right`"
+
+ # example of simple array table
+ fruits:
+ - ["name", "text"]
+ - ["apple", "red"]
+ - ["banana", "yellow"]
+ - ["grape", "green"]
+
+ # example of columns defined as arrays
+ cols_as_array:
+ cols: ["name", "text"]
+ rows:
+ - ["apple", "red"]
+ - ["banana", "yellow"]
+ - ["grape", "green"]
+
+ # example of columns and rows defined as hashes
+ hashes:
+ cols:
+ - id: "name"
+ name: "Name"
+ - id: "text"
+ name: "Text"
+
+ rows:
+ - name: "apple"
+ text: "red"
+ - name: "banana"
+ text: "yellow"
+ - name: "grape"
+ text: "green"
+
+ # example of table with caption
+ table_caption:
+ caption: "an example caption"
+ cols: ["name", "text"]
+ rows:
+ - ["apple", "red"]
+ - ["banana", "yellow"]
+ - ["grape", "green"]
+
+ # example of column tooltips
+ column_tooltips:
+ cols:
+ - id: "name"
+ name: "Name"
+ tip: "The name of the fruit."
+ - id: "text"
+ name: "Text"
+ tip: "A brief description of the fruit."
+
+ rows:
+ - name: "apple"
+ text: "red"
+ - name: "banana"
+ text: "yellow"
+ - name: "grape"
+ text: "green"
+
+ # example of column alignment
+ column_alignment:
+ cols:
+ - id: "name"
+ name: "Name"
+ align: "left"
+ - id: "text"
+ name: "Text"
+ align: "right"
+
+ rows:
+ - name: "apple"
+ text: "red"
+ - name: "banana"
+ text: "yellow"
+ - name: "grape"
+ text: "green"
+
+ # example of table with cells as values
+ cells_as_values:
+ cols:
+ - id: "name"
+ name: "Name"
+ - id: "text"
+ name: "Text"
+
+ rows:
+ - name: "apple"
+ text: "red"
+ - name: "banana"
+ text: "yellow"
+ - name: "grape"
+ text: "green"
+
+ # example of table a single cell defined cells as a hash
+ cells_as_hashes:
+ cols:
+ - id: "name"
+ name: "Name"
+ - id: "text"
+ name: "Text"
+ align: "right"
+
+ rows:
+ - name: "apple"
+ text: "red"
+ - name: "banana"
+ text: "yellow"
+ - name: "grape"
+ text:
+ # cell with custom alignment and tooltip
+ val: "green"
+ align: "left"
+ tip: "This cell has a custom tooltip."
+
+ # example of table with cells using markdown markup
+ cell_markup_markdown:
+ cols:
+ - id: "name"
+ name: "Name"
+ - id: "text"
+ name: "Text"
+
+ rows:
+ - name: "apple"
+ text: "*red*" # italics
+ - name: "banana"
+ text: "**yellow**" # bold
+ - name: "grape"
+ text: "[green](https://pablotron.org/ \"my favorite site\")" # link
+
+ # example of table with cells using html markup
+ cell_markup_html:
+ cols:
+ - id: "name"
+ name: "Name"
+ - id: "text"
+ name: "Text"
+
+ rows:
+ - name: "apple"
+ # cell value using HTML markup for italics
+ text:
+ val: "<i>red</i>"
+ html: true
+ - name: "banana"
+ # cell value using HTML markup for bold
+ text:
+ val: "<b>yellow</b>" # bold
+ html: true
+ - name: "grape"
+ # cell value using HTML markup for a link
+ text:
+ val: "<a href='https://pablotron.org/' title='my favorite site'>green</a>"
+ html: true
+
+ table_with_config_override:
+ # table config override that renders right-aligned text as bold
+ config:
+ table_class: "table"
+ align_left: "has-text-left"
+ align_center: "has-text-centered"
+ align_justify: "has-text-justified"
+ align_right: "has-text-weight-bold"
+
+ cols:
+ - id: "name"
+ name: "Name"
+ - id: "text"
+ name: "Text"
+ align: "right"
+
+ rows:
+ - name: "apple"
+ text: "red"
+ - name: "banana"
+ text: "yellow"
+ - name: "grape"
+ text: "green"
+
+---
+
+## Introduction
+
+This shortcode is a replacement for the lackluster table syntax in the
+default [Hugo Markdown renderer][goldmark].
+
+Features:
+* Emits [CSS][] classes for alignment rather than inline `style`
+ attributes (no more `unsafe-inline`).
+* Table can be defined as [front matter][front matter] or [site data][].
+* Column tooltips.
+* Cell-specific overrides (alignment, tooltip, etc).
+* [HTML][] and [Markdown][] markup support.
+* Easy to configure emitted [CSS][] classes for a variety of frameworks,
+ including [Bulma][] and [Bootstrap][].
+
+## Quick Start
+
+To get started:
+
+1. Copy `table.html` from the [hugo-shortcode-table
+ repository][hugo-shortcode-table] to the `layouts/shortcodes`
+ directory for your site.
+2. Add a table definition to your [page front matter][front matter] (see
+ below).
+3. Add a `table` shortcode to your page content which references the
+ table definition from the previous step (see below).
+
+Here is an example table definition for [YAML][] [front matter][]:
+
+```yaml
+tables:
+ fruits:
+ - ["name", "text"]
+ - ["apple", "red"]
+ - ["banana", "yellow"]
+ - ["grape", "green"]
+```
+&nbsp;
+
+Here is an example table declaration for your page content:
+
+```md
+{{</* table "fruits" */>}}
+```
+&nbsp;
+
+This will render the following table:
+
+{{< table "fruits" >}}
+
+## Table Definitions
+
+Tables can be defined as:
+
+* An array of rows.
+* A hash with `cols` and `rows` properties.
+
+When defined as an array, the first row is used as the column headers.
+Example:
+
+```yaml
+tables:
+ fruits:
+ - ["name", "text"] # <-- this row is used as the column headers
+ - ["apple", "red"]
+ - ["banana", "yellow"]
+ - ["grape", "green"]
+```
+&nbsp;
+
+When defined as a hash, the `cols` and `rows` properties are required.
+Here is the same table defined as a hash:
+
+```yaml
+tables:
+ fruits:
+ # table columns
+ cols: ["name", "text"]
+
+ # table rows
+ rows:
+ - ["apple", "red"]
+ - ["banana", "yellow"]
+ - ["grape", "green"]
+```
+&nbsp;
+
+Defining a table as a hash allows you to specify several additional
+table properties. The [Table Properties section](#table-properties)
+contains a complete list of available table properties.
+
+### Table Data Sources
+
+Table definitions can be stored in two places:
+
+* [page front matter][front matter] in the `tables` section.
+* [site `data` directory][site data] as [JSON][], [TOML][], or [YAML][]
+ files.
+
+**Note:** I will use [YAML][] front matter for the examples below.
+
+#### Front Matter Tables
+
+Here is an example of a table defined in the page [front matter][]:
+
+##### Front Matter
+```yaml
+---
+# ... other front matter omitted ...
+
+tables:
+ # example of table defined as arrays
+ cols_as_array:
+ # table columns (required)
+ cols: ["name", "text"]
+
+ # table rows (required)
+ rows:
+ - ["apple", "red"]
+ - ["banana", "yellow"]
+ - ["grape", "green"]
+---
+```
+&nbsp;
+
+##### Content
+
+```md
+{{</* table "cols_as_array" */>}}
+```
+&nbsp;
+
+##### Result
+
+{{< table "cols_as_array" >}}
+
+#### Site Data Tables
+
+Tables can also be defined in the [site `data` directory][site data] by
+using the two-argument version of the `table` shortcode.
+
+Here is an example of the two argument version of of the `table`
+shortcode: For example:
+
+```md
+{{</* table "table_shortcode_examples" "fruits" */>}}
+```
+&nbsp;
+
+In the example above, the `table` shortcode will look for the table data
+in the file `data/tables/table_shortcode_examples/fruits.yaml`.
+
+##### Data File
+
+Contents of `data/tables/table_shortcode_examples/fruits.yaml`.
+
+```yaml
+---
+# table columns (required)
+cols: ["name", "text"]
+
+# table rows (required)
+rows:
+ - ["apple", "red"]
+ - ["banana", "yellow"]
+ - ["grape", "green"]
+```
+
+##### Content
+
+```md
+{{</* table "table_shortcode_examples" "fruits" */>}}
+```
+&nbsp;
+
+##### Result
+
+{{< table "table_shortcode_examples" "fruits" >}}
+&nbsp;
+
+### Table Captions
+
+This section contains an example of specifying a table with a `caption`
+property.
+
+#### Front Matter
+
+Here is an example table definition with a `caption` property:
+
+```yaml
+---
+# ... other front matter omitted ...
+
+tables:
+ table_caption:
+ # table caption
+ caption: "an example caption"
+
+ # table columns
+ cols: ["name", "text"]
+
+ # table rows
+ rows:
+ - ["apple", "red"]
+ - ["banana", "yellow"]
+ - ["grape", "green"]
+---
+```
+&nbsp;
+
+#### Content
+
+Here is the corresponding table short code from the page content:
+
+```md
+{{</* table "table_caption" */>}}
+```
+&nbsp;
+
+#### Result
+
+Here is the resulting table:
+
+{{< table "table_caption" >}}
+
+### Table Properties
+
+Here is a complete list of available table properties:
+
+{{< table "table_props" >}}
+
+## Column Definitions
+
+Table columns can be defined in two ways:
+
+* As an array of values.
+* As an array of hashes.
+
+Defining columns as an array of hashes allows you to specify several
+additional properties for each column. The [Column
+Properties section](#column-properties) contains a complete list of
+available column properties.
+
+### Columns Defined as an Array of Values
+
+Here is an example of a table where the columns are defined as an array
+of values.
+
+#### Front Matter
+
+Front matter for table with columns are defined with an array of values.
+
+```yaml
+---
+# ... other front matter omitted ...
+
+tables:
+ # example of table with columns defined as an array of values
+ cols_as_array:
+ # table columns (required)
+ cols: ["name", "text"]
+
+ # table rows (required)
+ rows:
+ - ["apple", "red"]
+ - ["banana", "yellow"]
+ - ["grape", "green"]
+---
+```
+&nbsp;
+
+#### Page Content
+
+Here is the corresponding table shortcode reference from the page
+content for the table defined in the previous section:
+
+```md
+{{</* table "cols_as_array" */>}}
+```
+&nbsp;
+
+#### Result
+
+Here is the result:
+
+{{< table "cols_as_array" >}}
+
+### Columns Defined as an Array of Hashes
+
+Here is an example of a table where the columns are defined as an array
+of hashes.
+
+#### Front Matter
+
+```yaml
+---
+# ... other front matter omitted ...
+
+tables:
+ # example where columns are defined as hashes
+ hashes:
+ # table columns
+ # the `id` property
+ cols:
+ - id: "name"
+ name: "Name"
+ - id: "text"
+ name: "Text"
+
+ # table rows (required)
+ rows:
+ - name: "apple"
+ text: "red"
+ - name: "banana"
+ text: "yellow"
+ - name: "grape"
+ text: "green"
+---
+```
+&nbsp;
+
+#### Content
+
+```md
+{{</* table "hashes" */>}}
+```
+&nbsp;
+
+#### Result
+
+{{< table "hashes" >}}
+
+### Column Tooltips
+
+Use the `tip` property of columns to specify the `title` and
+`aria-lable` of columns.
+
+#### Front Matter
+
+```yaml
+---
+# ... other front matter omitted ...
+
+tables:
+ column_tooltips:
+ # table columns (required)
+ cols:
+ - id: "name"
+ name: "Name"
+ tip: "The name of the fruit."
+ - id: "text"
+ name: "Text"
+ tip: "A brief description of the fruit."
+
+ # table rows (required)
+ rows:
+ - name: "apple"
+ text: "red"
+ - name: "banana"
+ text: "yellow"
+ - name: "grape"
+ text: "green"
+---
+```
+&nbsp;
+
+#### Content
+
+```md
+{{</* table "column_tooltips" */>}}
+```
+&nbsp;
+
+#### Result
+
+{{< table "column_tooltips" >}}
+
+**Hint:** Hover over the column headers and table cells to show the
+custom tooltip.
+
+### Column Alignment
+
+Use the `align` property of columns to specify column alignment.
+
+Valid values of the `align` property are:
+* `left`
+* `center`
+* `justify`
+* `right`
+
+The rest of this section contains an example of a table with a
+right-aligned second column.
+
+#### Front Matter
+
+```yaml
+---
+# ... other front matter omitted ...
+
+tables:
+ # table
+ column_alignment:
+ # table columns (required)
+ cols:
+ - id: "name"
+ name: "Name"
+ align: "left"
+ - id: "text"
+ name: "Text"
+ align: "right"
+
+ # table rows (required)
+ rows:
+ - name: "apple"
+ text: "red"
+ - name: "banana"
+ text: "yellow"
+ - name: "grape"
+ text: "green"
+---
+```
+&nbsp;
+
+#### Content
+
+```md
+{{</* table "column_alignment" */>}}
+```
+&nbsp;
+
+#### Result
+
+{{< table "column_alignment" >}}
+
+### Column Properties
+
+Here is a complete list of the available column properties:
+
+{{< table "col_props" >}}
+
+## Row Definitions
+
+Rows are defined as:
+
+* An array of values.
+* Hashes. This is **required** if columns are [defined as an
+ array of hashes](#columns-defined-as-an-array-of-hashes).
+
+Defining a rows with hashes allows you to specify several additional
+properties. The [Row Properties section](#row-properties) contains a
+complete list of available properties.
+
+The `<tr>` elements generated by this shortcode are annotated with
+several additional [HTML][] attributes. See the [Row HTML Attributes
+section](#row-html-attributes) for a complete list of [HTML][]
+attributes.
+
+### Row Properties
+
+Here is a complete list of available properties for rows defined as
+hashes:
+
+{{< table "row_props" >}}
+
+### Row HTML Attributes
+
+Generated `<tr>` elements for rows are annotated with the following
+attributes:
+
+{{< table "row_attrs" >}}
+
+**Note:** For rows defined as an array of values, only the `data-tr_y`
+attribute is generated.
+
+## Cell Definitions
+
+Row cells can be specified as:
+
+* a value
+* a hash
+
+Defining cells with hashes allows you to specify several additional
+properties. The [Cell Properties section](#cell-properties) contains a
+complete list of available properties.
+
+The `<td>` elements generated by this shortcode for table cells are
+annotated with several additional [HTML][] attributes. See the [Cell
+HTML Attributes section](#cell-html-attributes) for a complete list of
+[HTML][] attributes.
+
+### Cells Defined as Values
+
+Here is an example of a table with the cells defined as values.
+
+#### Front Matter
+
+```yaml
+---
+# ... other front matter omitted ...
+
+tables:
+ # example of table with cells as values
+ cells_as_values:
+ cols:
+ - id: "name"
+ name: "Name"
+ - id: "text"
+ name: "Text"
+ align: "right"
+
+ rows:
+ - name: "apple"
+ text: "red"
+ - name: "banana"
+ text: "yellow"
+ - name: "grape"
+ text: "green"
+```
+&nbsp;
+
+#### Content
+
+Here is the corresponding shortcode in the page content:
+
+```md
+{{</* table "cells_as_values" */>}}
+```
+&nbsp;
+
+#### Result
+
+Here is the generated table:
+
+{{< table "cells_as_values" >}}
+
+### Cells Defined as Hashes
+
+Here is an example of a table with a single cell defined as a hash.
+
+#### Front Matter
+
+```yaml
+---
+# ... other front matter omitted ...
+
+tables:
+ # example of table a single cell defined cells as a hash
+ cells_as_hashes:
+ cols:
+ - id: "name"
+ name: "Name"
+ - id: "text"
+ name: "Text"
+ align: "right"
+
+ rows:
+ - name: "apple"
+ text: "red"
+ - name: "banana"
+ text: "yellow"
+ - name: "grape"
+ text:
+ # cell with custom alignment and tooltip
+ val: "green"
+ align: "left"
+ tip: "This cell has a custom tooltip."
+```
+&nbsp;
+
+#### Content
+
+Here is the corresponding shortcode in the page content:
+
+```md
+{{</* table "cells_as_hashes" */>}}
+```
+&nbsp;
+
+#### Result
+
+Here is the generated table:
+
+{{< table "cells_as_hashes" >}}
+
+**Hint:** Hover over the word `green` to see the custom tooltip.
+
+### Cell Markup
+
+Cell values can use the following markup:
+
+* [Markdown][] (default)
+* [HTML][], by specifying the cell as a hash and setting the `html`
+ property to `true`.
+
+#### Markdown
+
+This section contains is an example table with a cell that uses
+[Markdown][] markup.
+
+**Note:** [Markdown][] links in cell values **cannot be specified**
+using `[name][code]` syntax; instead they must use one of the following
+[Markdown][] link syntaxes:
+
+* `[name](full_url)`
+* `[name](full_url "tooltip")`
+
+##### Front Matter
+
+```yaml
+---
+# ... other front matter omitted ...
+
+tables:
+ # example of table with cells using markdown markup
+ cell_markup_markdown:
+ cols:
+ - id: "name"
+ name: "Name"
+ - id: "text"
+ name: "Text"
+
+ rows:
+ - name: "apple"
+ text: "*red*" # italics
+ - name: "banana"
+ text: "**yellow**" # bold
+ - name: "grape"
+ text: "[green](https://pablotron.org/ \"my favorite site\")" # link
+```
+
+##### Content
+
+Here is the corresponding shortcode in the page content:
+
+```md
+{{</* table "cell_markup_markdown" */>}}
+```
+&nbsp;
+
+##### Result
+
+Here is the generated table:
+
+{{< table "cell_markup_markdown" >}}
+
+#### HTML
+
+You can render cell values using [HTML][] markup by specifying the cell
+as a hash and then setting the `html` property of the cell to `true`.
+
+This section contains an example table containing cells using [HTML][]
+markup.
+
+##### Front Matter
+
+```yaml
+---
+# ... other front matter omitted ...
+
+tables:
+ # example of table with cells using html markup
+ cell_markup_html:
+ cols:
+ - id: "name"
+ name: "Name"
+ - id: "text"
+ name: "Text"
+
+ rows:
+ - name: "apple"
+ # cell value using HTML markup for italics
+ text:
+ val: "<i>red</i>"
+ html: true
+ - name: "banana"
+ # cell value using HTML markup for bold
+ text:
+ val: "<b>yellow</b>" # bold
+ html: true
+ - name: "grape"
+ # cell value using HTML markup for a link
+ text:
+ val: "<a href='https://pablotron.org/' title='my favorite site'>green</a>"
+ html: true
+```
+&nbsp;
+
+##### Content
+
+Here is the corresponding shortcode in the page content:
+
+```md
+{{</* table "cell_markup_html" */>}}
+```
+&nbsp;
+
+##### Result
+
+Here is the generated table:
+
+{{< table "cell_markup_html" >}}
+
+### Cell Properties
+
+Here is a complete list of available properties for cells defined as
+hashes:
+
+{{< table "cell_props" >}}
+
+### Cell HTML Attributes
+
+Generated `<td>` elements for table cells are annotated with the
+following attributes:
+
+{{< table "cell_attrs" >}}
+
+**Note:** For cells defined as a value rather than a hash, only
+following attributes are generated for `<td>` elements:
+
+* `data-td_x`
+* `title` (set to the column name)
+* `aria-label` (set to the column name)
+
+## Overwriding Table Configuration
+
+Column and cell alignment is rendered using [CSS][] classes rather than
+inline `style` attributes.
+
+The default `align` to [CSS][] `class` mapping is as follows:
+
+{{< table "align_classes" >}}
+
+These classes work out of the box with [Bulma][]. If you're using
+another framework, you can change the [CSS class][css]
+configuration on a per-table, per-page, or per-site basis.
+
+See the [Table Configuration Properties
+section](#table-configuration-properties "Table Configuration Properties")
+for a full list of available table configuration properties.
+
+### Table Override
+
+Use the `config` property to override the table configuration for a
+specific table.
+
+#### Front Matter
+
+```yaml
+---
+# ... other front matter omitted ...
+
+tables:
+ # table with custom config that renders right-aligned text as bold
+ table_with_config_override:
+ # table config override that renders right-aligned text as bold
+ config:
+ table_class: "table"
+ align_left: "has-text-left"
+ align_center: "has-text-centered"
+ align_justify: "has-text-justified"
+ align_right: "has-text-weight-bold"
+
+ cols:
+ - id: "name"
+ name: "Name"
+ - id: "text"
+ name: "Text"
+ align: "right"
+
+ rows:
+ - name: "apple"
+ text: "red"
+ - name: "banana"
+ text: "yellow"
+ - name: "grape"
+ text: "green"
+```
+&nbsp;
+
+#### Content
+
+Here is the corresponding shortcode in the page content:
+
+```md
+{{</* table "table_with_config_override" */>}}
+```
+&nbsp;
+
+#### Result
+
+Here is the generated table:
+
+{{< table "table_with_config_override" >}}
+
+### Page Override
+
+Use the `table_config` property in the [page front matter][front matter]
+to override the configuration for all tables on a page that are
+generated with the table shortcode.
+
+Here is an example page-level table configuration override which
+emits a `has-text-weight-bold` class for all table cells with an
+alignment set to `justify`:
+
+```yaml
+---
+# ... other front matter omitted ...
+
+# override config for all tables generated with table shortcode on this
+# page so that right-aligned cell values are rendered as bold
+table_config:
+ table_class: "table"
+ align_left: "has-text-left"
+ align_center: "has-text-centered"
+ align_justify: "has-text-weight-bold"
+ align_right: "has-text-right"
+```
+&nbsp;
+
+### Site Override
+
+Use the `table_config` parameter in the root `config.toml` to override
+the table configuration for all tables across all pages on a site that
+are generated with the table shortcode.
+
+Here is an example overide for [Bootstrap][]:
+
+```toml
+# table shortcode bootstrap override
+[params.table_config]
+ # class to assign to all generated tables
+ table_class = "table"
+
+ # class for left-aligned column headers and cells
+ align_left = "text-start"
+
+ # class for centered column headers and cells
+ align_center = "text-center"
+
+ # class for justified column headers and cells
+ # (note: doesn't provide a justify alignment class so you
+ # would need to provide your own)
+ align_justify = "my-custom-justify-class"
+
+ # class for right-aligned column headers and cells
+ align_right = "text-right"
+```
+&nbsp;
+
+### Table Configuration Properties
+
+Here is a full list of available table configuration properties:
+
+{{< table "table_config_props" >}}
+
+[site data]: https://gohugo.io/templates/data-templates/#the-data-folder
+ "Site data directory."
+[front matter]: https://gohugo.io/content-management/front-matter/
+ "Hugo page metadata."
+[css]: https://en.wikipedia.org/wiki/CSS
+ "Cascading Style Sheets"
+[bulma]: https://bulma.io/
+ "Bulma CSS framework."
+[bootstrap]: https://getbootstrap.com/
+ "Bootstrap CSS framework."
+[json]: https://json.org/
+ "JavaScript Object Notation"
+[yaml]: https://yaml.org/
+ "YAML Ain't a Markup Language"
+[toml]: https://github.com/toml-lang/toml
+ "Tom's Obvious Markup Language"
+[hugo]: https://gohugo.io/
+ "Hugo static site generator"
+[goldmark]: https://github.com/yuin/goldmark/
+ "Goldmark Markdown renderer."
+[html]: https://en.wikipedia.org/wiki/HTML
+ "HyperText Markup Language"
+[markdown]: https://en.wikipedia.org/wiki/Markdown
+ "Markdown markup language"
+[hugo-shortcode-table]: https://github.com/pablotron
+ "hugo-shortcode-table github repository"