diff --git a/content/en/docs/contribute/style/hugo-shortcodes/index.md b/content/en/docs/contribute/style/hugo-shortcodes/index.md index a5807216a4..5463019ac0 100644 --- a/content/en/docs/contribute/style/hugo-shortcodes/index.md +++ b/content/en/docs/contribute/style/hugo-shortcodes/index.md @@ -12,11 +12,13 @@ Read more about shortcodes in the [Hugo documentation](https://gohugo.io/content ## Feature state -In a Markdown page (`.md` file) on this site, you can add a shortcode to display version and state of the documented feature. +In a Markdown page (`.md` file) on this site, you can add a shortcode to +display version and state of the documented feature. ### Feature state demo -Below is a demo of the feature state snippet, which displays the feature as stable in the latest Kubernetes version. +Below is a demo of the feature state snippet, which displays the feature as +stable in the latest Kubernetes version. ``` {{}} @@ -50,16 +52,22 @@ Renders to: There are two glossary shortcodes: `glossary_tooltip` and `glossary_definition`. -You can reference glossary terms with an inclusion that automatically updates and replaces content with the relevant links from [our glossary](/docs/reference/glossary/). When the glossary term is moused-over, the glossary entry displays a tooltip. The glossary term also displays as a link. +You can reference glossary terms with an inclusion that automatically updates +and replaces content with the relevant links from [our glossary](/docs/reference/glossary/). +When the glossary term is moused-over, the glossary entry displays a tooltip. +The glossary term also displays as a link. As well as inclusions with tooltips, you can reuse the definitions from the glossary in page content. -The raw data for glossary terms is stored at [https://github.com/kubernetes/website/tree/main/content/en/docs/reference/glossary](https://github.com/kubernetes/website/tree/main/content/en/docs/reference/glossary), with a content file for each glossary term. +The raw data for glossary terms is stored at +[the glossary directory](https://github.com/kubernetes/website/tree/main/content/en/docs/reference/glossary), +with a content file for each glossary term. ### Glossary demo -For example, the following include within the Markdown renders to {{< glossary_tooltip text="cluster" term_id="cluster" >}} with a tooltip: +For example, the following include within the Markdown renders to +{{< glossary_tooltip text="cluster" term_id="cluster" >}} with a tooltip: ``` {{}} @@ -85,7 +93,9 @@ which renders as: ## Links to API Reference -You can link to a page of the Kubernetes API reference using the `api-reference` shortcode, for example to the {{< api-reference page="workload-resources/pod-v1" >}} reference: +You can link to a page of the Kubernetes API reference using the +`api-reference` shortcode, for example to the +{{< api-reference page="workload-resources/pod-v1" >}} reference: ``` {{}} @@ -94,7 +104,10 @@ You can link to a page of the Kubernetes API reference using the `api-reference` The content of the `page` parameter is the suffix of the URL of the API reference page. -You can link to a specific place into a page by specifying an `anchor` parameter, for example to the {{< api-reference page="workload-resources/pod-v1" anchor="PodSpec" >}} reference or the {{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" >}} section of the page: +You can link to a specific place into a page by specifying an `anchor` +parameter, for example to the {{< api-reference page="workload-resources/pod-v1" anchor="PodSpec" >}} +reference or the {{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" >}} +section of the page: ``` {{}} @@ -102,17 +115,20 @@ You can link to a specific place into a page by specifying an `anchor` parameter ``` -You can change the text of the link by specifying a `text` parameter, for example by linking to the {{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="Environment Variables">}} section of the page: +You can change the text of the link by specifying a `text` parameter, for +example by linking to the +{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="Environment Variables">}} +section of the page: ``` {{}} ``` - - ## 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. +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. @@ -138,7 +154,8 @@ Parameter | Description | Default `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: +If you inspect the HTML for the table, you should see this element immediately +after the opening `
` element: ```html @@ -146,14 +163,25 @@ If you inspect the HTML for the table, you should see this element immediately a ## Tabs -In a markdown page (`.md` file) on this site, you can add a tab set to display multiple flavors of a given solution. +In a markdown page (`.md` file) on this site, you can add a tab set to display +multiple flavors of a given solution. 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. -* 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 */%}}` +* `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. +* 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. Below is a demo of the tabs shortcode. @@ -288,13 +316,17 @@ The two most commonly used version parameters are `latest` and `version`. ### `{{}}` -The `{{}}` shortcode generates the value of the current version of -the Kubernetes documentation from the `version` site parameter. The `param` shortcode accepts the name of one site parameter, in this case: `version`. +The `{{}}` shortcode generates the value of the current +version of the Kubernetes documentation from the `version` site parameter. The +`param` shortcode accepts the name of one site parameter, in this case: +`version`. {{< note >}} -In previously released documentation, `latest` and `version` parameter values are not equivalent. -After a new version is released, `latest` is incremented and the value of `version` for the documentation set remains unchanged. For example, a previously released version of the documentation displays `version` as -`v1.19` and `latest` as `v1.20`. +In previously released documentation, `latest` and `version` parameter values +are not equivalent. After a new version is released, `latest` is incremented +and the value of `version` for the documentation set remains unchanged. For +example, a previously released version of the documentation displays `version` +as `v1.19` and `latest` as `v1.20`. {{< /note >}} Renders to: @@ -313,7 +345,8 @@ Renders to: ### `{{}}` -The `{{}}` shortcode generates the value of `latest` without the "v" prefix. +The `{{}}` shortcode generates the value of `latest` +without the "v" prefix. Renders to: @@ -330,8 +363,9 @@ Renders to: ### `{{}}` -The `{{}}` shortcode generates a version string from `latest` and removes -the "v" prefix. The shortcode prints a new URL for the release note CHANGELOG page with the modified version string. +The `{{}}` shortcode generates a version string +from `latest` and removes the "v" prefix. The shortcode prints a new URL for +the release note CHANGELOG page with the modified version string. Renders to: @@ -344,3 +378,4 @@ Renders to: * Learn about [page content types](/docs/contribute/style/page-content-types/). * Learn about [opening a pull request](/docs/contribute/new-content/open-a-pr/). * Learn about [advanced contributing](/docs/contribute/advanced/). +
Configuration parameters