path: root/content/articles/table-shortcode-examples.md

---
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

# table data
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 \"Cascading Style Sheets\") 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 \"Cascading Style Sheets\")."
        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 \"Cascading Style Sheets\") 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 \"Cascading Style Sheets\")."
        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 \"Cascading Style Sheets\") 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 \"Cascading Style Sheets\") 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][].

[GitHub Repository][git]

## Quick Start

To get started:

1. Copy `table.html` from the [hugo-shortcode-table repository][git] 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-props]
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 form of the `table` [shortcode][].

Here is an example of the two argument form of of the `table`
shortcode:

```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 [shortcode][] 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][col-props] 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][cols-as-hashes].

Defining a rows with hashes allows you to specify several additional
properties.  The [Row Properties section][row-props] 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-attrs] 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-props] 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-attrs] 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)

## Table Configuration Overrides

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-config-props]
for a full list of available table configuration properties.

### Table Override

Use the `config` table property to override the 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"
[shortcode]: https://gohugo.io/content-management/shortcodes/
  "Hugo shortcode"
[git]: https://github.com/pablotron/hugo-shortcode-table
  "hugo-shortcode-table github repository"
[table-props]: #table-properties
  "Table Properties section"
[col-props]: #column-properties
  "Column Properties section"
[cols-as-hashes]: #columns-defined-as-an-array-of-hashes
  "Columns Defined as an Array of Hashes"
[row-props]: #row-properties
  "Row Properties section"
[row-attrs]: #row-html-attributes
  "Row HTML Attributes section"
[cell-props]: #cell-properties
  "Cell Properties section"
[cell-attrs]: #cell-html-attributes
  "Cell HTML Attributes section"
[table-config-props]: #table-configuration-properties
  "Table Configuration Properties section"