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 {{}} ``` -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 {{}} ```` +## 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 +{{}} +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 + +``` + ## 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, {{}}. 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, {{}}. 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 "
Configuration parameters
" $caption }} +{{ $table := .Inner | markdownify }} +{{ $html := cond $hasCaption ($table | replaceRE "
%s
" $captionEl) $table | safeHTML }} +{{ $html }} \ No newline at end of file