whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Wrap long lines for hugo-shortcodes page

Browse Source
This commit is contained in:
Qiming Teng
2022-02-05 14:57:39 +08:00
parent 517ec927bf
commit 6ea009fa04
1 changed files with 59 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/contribute/style/hugo-shortcodes/index.md
+59 -24
View File
@@ -12,11 +12,13 @@ Read more about shortcodes in the [Hugo documentation](https://gohugo.io/content
## Feature state ## 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 ### 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.
``` ```
{{</* feature-state state="stable" */>}} {{</* feature-state state="stable" */>}}
@@ -50,16 +52,22 @@ Renders to:
There are two glossary shortcodes: `glossary_tooltip` and `glossary_definition`. 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 As well as inclusions with tooltips, you can reuse the definitions from the glossary in
page content. 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 ### 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:
``` ```
{{</* glossary_tooltip text="cluster" term_id="cluster" */>}} {{</* glossary_tooltip text="cluster" term_id="cluster" */>}}
@@ -85,7 +93,9 @@ which renders as:
## Links to API Reference ## 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:
``` ```
{{</* api-reference page="workload-resources/pod-v1" */>}} {{</* api-reference page="workload-resources/pod-v1" */>}}
@@ -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. 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:
``` ```
{{</* api-reference page="workload-resources/pod-v1" anchor="PodSpec" */>}} {{</* api-reference page="workload-resources/pod-v1" anchor="PodSpec" */>}}
@@ -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:
``` ```
{{</* api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="Environment Variable" */>}} {{</* api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="Environment Variable" */>}}
``` ```
## Table captions ## 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 >}} {{< note >}}
Table captions are visible to screen readers but invisible when viewed in standard HTML. 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` `logLevel` | The log level for log output | `INFO`
{{< /table >}} {{< /table >}}
If you inspect the HTML for the table, you should see this element immediately after the opening `<table>` element: If you inspect the HTML for the table, you should see this element immediately
after the opening `<table>` element:
```html ```html
<caption style="display: none;">Configuration parameters</caption> <caption style="display: none;">Configuration parameters</caption>
@@ -146,14 +163,25 @@ If you inspect the HTML for the table, you should see this element immediately a
## Tabs ## 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: The `tabs` shortcode takes these parameters:
* `name`: The name as shown on the tab. * `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. * `codelang`: If you provide inner content to the `tab` shortcode, you can tell Hugo
* `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. what code language to use for highlighting.
* 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 */%}}` * `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. * You can combine the variations mentioned above inside a tab set.
Below is a demo of the tabs shortcode. Below is a demo of the tabs shortcode.
@@ -288,13 +316,17 @@ The two most commonly used version parameters are `latest` and `version`.
### `{{</* param "version" */>}}` ### `{{</* param "version" */>}}`
The `{{</* param "version" */>}}` shortcode generates the value of the current version of The `{{</* param "version" */>}}` shortcode generates the value of the current
the Kubernetes documentation from the `version` site parameter. The `param` shortcode accepts the name of one site parameter, in this case: `version`. 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 >}} {{< note >}}
In previously released documentation, `latest` and `version` parameter values are not equivalent. In previously released documentation, `latest` and `version` parameter values
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 are not equivalent. After a new version is released, `latest` is incremented
`v1.19` and `latest` as `v1.20`. 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 >}} {{< /note >}}
Renders to: Renders to:
@@ -313,7 +345,8 @@ Renders to:
### `{{</* latest-semver */>}}` ### `{{</* latest-semver */>}}`
The `{{</* latest-semver */>}}` shortcode generates the value of `latest` without the "v" prefix. The `{{</* latest-semver */>}}` shortcode generates the value of `latest`
without the "v" prefix.
Renders to: Renders to:
@@ -330,8 +363,9 @@ Renders to:
### `{{</* latest-release-notes */>}}` ### `{{</* latest-release-notes */>}}`
The `{{</* latest-release-notes */>}}` shortcode generates a version string from `latest` and removes The `{{</* latest-release-notes */>}}` shortcode generates a version string
the "v" prefix. The shortcode prints a new URL for the release note CHANGELOG page with the modified 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: Renders to:
@@ -344,3 +378,4 @@ Renders to:
* Learn about [page content types](/docs/contribute/style/page-content-types/). * 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 [opening a pull request](/docs/contribute/new-content/open-a-pr/).
* Learn about [advanced contributing](/docs/contribute/advanced/). * Learn about [advanced contributing](/docs/contribute/advanced/).