Table Shortcode Examples

Table of Contents

Introduction

This shortcode is a replacement for the lackluster table syntax in the default Hugo Markdown renderer.

Features:

• Emits CSS classes for alignment rather than inline style attributes (no more unsafe-inline).
• Table can be defined as 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

Quick Start

To get started:

1. Copy table.html from the hugo-shortcode-table repository to the layouts/shortcodes directory for your site.
2. Add a table definition to your page 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:

tables:
  fruits:
    - ["name", "text"]
    - ["apple", "red"]
    - ["banana", "yellow"]
    - ["grape", "green"]

Here is an example table declaration for your page content:

{{< table "fruits" >}}

This will render the following table:

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:

tables:
  fruits:
    - ["name", "text"] # <-- this row is used as the column headers
    - ["apple", "red"]
    - ["banana", "yellow"]
    - ["grape", "green"]

When defined as a hash, the cols and rows properties are required. Here is the same table defined as a hash:

tables:
  fruits:
    # table columns
    cols: ["name", "text"]

    # table rows
    rows: 
      - ["apple", "red"]
      - ["banana", "yellow"]
      - ["grape", "green"]

Defining a table as a hash allows you to specify several additional table properties. The Table Properties section contains a complete list of available table properties.

Table Data Sources

Table definitions can be stored in two places:

• page front matter in the tables section.
• site data directory 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

---
# ... 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"]
---

Content

{{< table "cols_as_array" >}}

Result

Site Data Tables

Tables can also be defined in the site data directory by using the two-argument form of the table shortcode.

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

{{< table "table_shortcode_examples" "fruits" >}}

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.

---
# table columns (required)
cols: ["name", "text"]

# table rows (required)
rows: 
  - ["apple", "red"]
  - ["banana", "yellow"]
  - ["grape", "green"]

Content

{{< table "table_shortcode_examples" "fruits" >}}

Result

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:

---
# ... 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"]
---

Content

Here is the corresponding table shortcode from the page content:

{{< table "table_caption" >}}

Result

Here is the resulting table:

Table Properties

Here is a complete list of available table properties:

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

---
# ... 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"]
---

Page Content

Here is the corresponding table shortcode reference from the page content for the table defined in the previous section:

{{< table "cols_as_array" >}}

Result

Here is the result:

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

---
# ... 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"
---

Content

{{< table "hashes" >}}

Result

Column Tooltips

Use the tip property of columns to specify the title and aria-lable of columns.

Front Matter

---
# ... 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"
---

Content

{{< table "column_tooltips" >}}

Result

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

---
# ... 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"
---

Content

{{< table "column_alignment" >}}

Result

Column Properties

Here is a complete list of the available column properties:

Row Definitions

Rows are defined as:

• An array of values.
• Hashes. This is required if columns are defined as an array of hashes.

Defining a rows with hashes allows you to specify several additional properties. The Row Properties section 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 for a complete list of HTML attributes.

Row Properties

Here is a complete list of available properties for rows defined as hashes:

Row HTML Attributes

Generated <tr> elements for rows are annotated with the following attributes:

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

---
# ... 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"

Content

Here is the corresponding shortcode in the page content:

{{< table "cells_as_values" >}}

Result

Here is the generated table:

Cells Defined as Hashes

Here is an example of a table with a single cell defined as a hash.

Front Matter

---
# ... 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."

Content

Here is the corresponding shortcode in the page content:

{{< table "cells_as_hashes" >}}

Result

Here is the generated table:

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

---
# ... 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:

{{< table "cell_markup_markdown" >}}

Result

Here is the generated table:

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

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

Content

Here is the corresponding shortcode in the page content:

{{< table "cell_markup_html" >}}

Result

Here is the generated table:

Cell Properties

Here is a complete list of available properties for cells defined as hashes:

Cell HTML Attributes

Generated <td> elements for table cells are annotated with the following attributes:

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:

These classes work out of the box with Bulma. If you’re using another framework, you can change the CSS class configuration on a per-table, per-page, or per-site basis.

See the Table Configuration Properties section 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

---
# ... 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"

Content

Here is the corresponding shortcode in the page content:

{{< table "table_with_config_override" >}}

Result

Here is the generated table:

Page Override

Use the table_config property in the page 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:

---
# ... 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"

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:

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

Table Configuration Properties

Here is a full list of available table configuration properties: