diff --git a/content/en/docs/contribute/style/hugo-shortcodes/index.md b/content/en/docs/contribute/style/hugo-shortcodes/index.md
index 3161588996..986af55e87 100644
--- a/content/en/docs/contribute/style/hugo-shortcodes/index.md
+++ b/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 `
` element:
+
+```html
+Configuration parameters
+```
+
## 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, {{* tab name="Content File #1" include="example1" /*/>}}. 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, {{* tab name="Content File #1" include="example1" /*/>}}. 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" >}}
diff --git a/layouts/shortcodes/table.html b/layouts/shortcodes/table.html
new file mode 100644
index 0000000000..d92bc17a9c
--- /dev/null
+++ b/layouts/shortcodes/table.html
@@ -0,0 +1,6 @@
+{{ $hasCaption := isset .Params "caption" }}
+{{ $caption := .Get "caption" }}
+{{ $captionEl := printf "%s" $caption }}
+{{ $table := .Inner | markdownify }}
+{{ $html := cond $hasCaption ($table | replaceRE "" $captionEl) $table | safeHTML }}
+{{ $html }}
\ No newline at end of file