Create table shortcode that allows for table captions (#13117)

* Create table shortcode for captions

* Allow for tables without captions

* Add table documentation in shortcodes guide

* Docs cleanup

content/en/docs/contribute/style/hugo-shortcodes/index.md

@@ -103,6 +103,40 @@ For example, the following include within the markdown renders to {{< glossary_t
 {{</* glossary_tooltip text="cluster" term_id="cluster" */>}}
 ````
 
+## Table captions
+
+You can make tables more accessible to screen readers by adding a table caption. To add a [caption](https://www.w3schools.com/tags/tag_caption.asp) to a table, enclose the table with a `table` shortcode and specify the caption with the `caption` parameter.
+
+{{< note >}}
+Table captions are visible to screen readers but invisible when viewed in standard HTML.
+{{< /note >}}
+
+Here's an example:
+
+```go-html-template
+{{</* table caption="Configuration parameters" >}}
+Parameter | Description | Default
+:---------|:------------|:-------
+`timeout` | The timeout for requests | `30s`
+`logLevel` | The log level for log output | `INFO`
+{{< /table */>}}
+```
+
+The rendered table looks like this:
+
+{{< table caption="Configuration parameters" >}}
+Parameter | Description | Default
+:---------|:------------|:-------
+`timeout` | The timeout for requests | `30s`
+`logLevel` | The log level for log output | `INFO`
+{{< /table >}}
+
+If you inspect the HTML for the table, you should see this element immediately after the opening `<table>` element:
+
+```html
+<caption style="display: none;">Configuration parameters</caption>
+```
+
 ## Tabs
 
 In a markdown page (`.md` file) on this site, you can add a tab set to display multiple flavors of a given solution.

layouts/shortcodes/table.html

@@ -0,0 +1,6 @@
+{{ $hasCaption := isset .Params "caption" }}
+{{ $caption    := .Get "caption" }}
+{{ $captionEl  := printf "<table><caption style=\"display: none;\">%s</caption>" $caption }}
+{{ $table      := .Inner | markdownify }}
+{{ $html       := cond $hasCaption ($table | replaceRE "<table>" $captionEl) $table | safeHTML }}
+{{ $html }}