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

@@ -24,7 +24,7 @@ Below is a demo of the feature state snippet, which displays the feature as stab
 {{</* feature-state for_k8s_version="v1.10" state="stable" */>}}
 ```
 
-Renders to: 
+Renders to:
 
 {{< feature-state for_k8s_version="v1.10" state="stable" >}}
 
@@ -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.
@@ -111,7 +145,7 @@ The `tabs` shortcode takes these parameters:
 
 * `name`: The name as shown on the tab.
 * `codelang`: If you provide inner content to the `tab` shortcode, you can tell Hugo what code language to use for highlighting.
-* `include`: The file to include in the tab. If the tab lives in a Hugo [leaf bundle](https://gohugo.io/content-management/page-bundles/#leaf-bundles), the file -- which can be any MIME type supported by Hugo -- is looked up in the bundle itself. If not, the content page that needs to be included is looked up relative to the current page. Note that with the `include`, you do not have any shortcode inner content and must use the self-closing syntax. For example, <code>{{</* tab name="Content File #1" include="example1" /*/>}}</code>. The language needs to be specified under `codelang` or the language is taken based on the file name. Non-content files are code-highlighted by default. 
+* `include`: The file to include in the tab. If the tab lives in a Hugo [leaf bundle](https://gohugo.io/content-management/page-bundles/#leaf-bundles), the file -- which can be any MIME type supported by Hugo -- is looked up in the bundle itself. If not, the content page that needs to be included is looked up relative to the current page. Note that with the `include`, you do not have any shortcode inner content and must use the self-closing syntax. For example, <code>{{</* tab name="Content File #1" include="example1" /*/>}}</code>. The language needs to be specified under `codelang` or the language is taken based on the file name. Non-content files are code-highlighted by default.
 * If your inner content is markdown, you must use the `%`-delimiter to surround the tab. For example, `{{%/* tab name="Tab 1" %}}This is **markdown**{{% /tab */%}}`
 * You can combine the variations mentioned above inside a tab set.
 
@@ -134,7 +168,7 @@ println "This is tab 2."
 {{< /tabs */>}}
 ```
 
-Renders to: 
+Renders to:
 
 {{< tabs name="tab_with_code" >}}
 {{< tab name="Tab 1" codelang="bash" >}}

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