add articles/table-shortcode-examples

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"