feat(shortcodes): add caption argument to table shortcode

config/postcss.config.js

@@ -56,6 +56,8 @@ const purgecss = purgeCSSPlugin({
       // would therefore lose the rule, leaving the wrapped column's cells on `d-none` alone and so
       // hidden at every width.
       /^d-(sm|md|lg|xl|xxl)-table-cell$/,
+      // Applied by assets/table.html only when caption-top=true
+      'caption-top',
       // SimpleDatatables search component
       'search-data-table',
       'search-input',

data/structures/table.yml

@@ -32,6 +32,18 @@ arguments:
   wrap:
   wrapper:
     release: v2.0.0
+  caption:
+    comment: >-
+      Caption rendered as the table's `<caption>` element, describing the
+      table's contents.
+    release: v3.3.0
+  caption-top:
+    type: bool
+    default: false
+    optional: true
+    comment: >-
+      Whether the caption renders above the table (Bootstrap `caption-top`).
+    release: v3.3.0
   # deprecated arguments
   paging:
     type: bool

exampleSite/config/postcss.config.js

@@ -56,6 +56,8 @@ const purgecss = purgeCSSPlugin({
       // would therefore lose the rule, leaving the wrapped column's cells on `d-none` alone and so
       // hidden at every width.
       /^d-(sm|md|lg|xl|xxl)-table-cell$/,
+      // Applied by assets/table.html only when caption-top=true
+      'caption-top',
       // SimpleDatatables search component
       'search-data-table',
       'search-input',

exampleSite/content/en/table-demo.md

@@ -60,3 +60,13 @@ modules: ["simple-datatables"]
 | charlie | widget | The third record. Short.                                           |
 | delta   | gadget | The fourth record, whose description runs on for a little while.   |
 {{< /table >}}
+
+## Table with caption
+
+{{< table caption="Overview of records" class="fixture-caption" >}}
+
+| Name  | Type   | Description        |
+|-------|--------|--------------------|
+| alpha | widget | The first record.  |
+| bravo | gadget | The second record. |
+{{< /table >}}

exampleSite/hugo_stats.json

@@ -6,6 +6,7 @@
       "blockquote",
       "body",
       "button",
+      "caption",
       "code",
       "dialog",
       "div",
@@ -419,6 +420,7 @@
       "file-controls",
       "file-panel",
       "fixed-top",
+      "fixture-caption",
       "fixture-data",
       "fixture-filter",
       "fixture-filter-wrap",
@@ -1255,6 +1257,7 @@
       "mindmap",
       "minimal",
       "minimal-cards",
+      "minimal-nav-no-parent-args-single-item",
       "modal-search",
       "mode-switcher",
       "more-type",
@@ -1490,6 +1493,7 @@
       "tab-list",
       "table",
       "table-demo",
+      "table-with-caption",
       "table-wrapping",
       "tablet-preview",
       "tabs",

layouts/_partials/assets/table.html

@@ -47,6 +47,7 @@
      caller's class list. The template adds it back below when the wrap genuinely applies. */}}
 {{ $class := delimit (complement (slice "table-wrap") (split (or $args.class "") " ")) " " }}
 {{ if $dataTable }}{{ $class = trim (printf "%s data-table" $class) " " }}{{ end }}
+{{ if and $args.caption $args.captionTop }}{{ $class = trim (printf "%s caption-top" $class) " " }}{{ end }}
 
 {{ $attributes := "" }}
 {{ if $args.sortable }}{{ $attributes = printf "%s data-table-sortable=true" $attributes }}{{ end }}
@@ -103,6 +104,13 @@
     {{ $new := printf `<table class="%s" %s` $target (trim $attributes " ") }}
     {{ $input = replaceRE $regex $new $input 1 }}
 
+    {{/* Insert as the table's last child, matching simple-datatables; `replace` keeps a `$` in
+         the caption literal. */}}
+    {{ with $args.caption }}
+        {{ $rendered := . | $args.page.RenderString }}
+        {{ $input = replace $input "</table>" (printf "<caption>%s</caption>\n</table>" $rendered) 1 }}
+    {{ end }}
+
     {{ $wrapper := $args.wrapper | default "" }}
 
     {{ if $filter }}

layouts/_shortcodes/table.html

@@ -73,6 +73,8 @@
         "filter-col"             $args.filterCol
         "wrap"                   $args.wrap
         "wrapper"                $args.wrapper
+        "caption"                $args.caption
+        "caption-top"            $args.captionTop
         "_default"               $args.default
     ) }}
 {{ end }}