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

add docs for version shortcodes

Browse Source
This commit is contained in:
Karen Bradshaw
2021-01-12 17:20:33 -05:00
parent 28b393032b
commit 0166a0b08e
6 changed files with 83 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/contribute/style/hugo-shortcodes/example1.md
+1 -1
View File
@@ -6,4 +6,4 @@ This is an **example** content file inside the **includes** leaf bundle.
{{< note >}}
Included content files can also contain shortcodes.
{{< /note >}}
{{< /note >}}
content/en/docs/contribute/style/hugo-shortcodes/index.md
+71 -56
View File
@@ -1,33 +1,30 @@
---
approvers:
- chenopis
title: Custom Hugo Shortcodes
content_type: concept
---
<!-- overview -->
This page explains the custom Hugo shortcodes that can be used in Kubernetes markdown documentation.
This page explains the custom Hugo shortcodes that can be used in Kubernetes Markdown documentation.
Read more about shortcodes in the [Hugo documentation](https://gohugo.io/content-management/shortcodes).
<!-- body -->
## 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 Kubernetes version 1.10.
Below is a demo of the feature state snippet, which displays the feature as stable in the latest Kubernetes version.
```
{{</* feature-state for_k8s_version="v1.10" state="stable" */>}}
{{</* feature-state state="stable" */>}}
```
Renders to:
{{< feature-state for_k8s_version="v1.10" state="stable" >}}
{{< feature-state state="stable" >}}
The valid values for `state` are:
@@ -38,62 +35,22 @@ The valid values for `state` are:
### Feature state code
The displayed Kubernetes version defaults to that of the page or the site. This can be changed by passing the <code>for_k8s_version</code> shortcode parameter.
The displayed Kubernetes version defaults to that of the page or the site. You can change the
feature state version by passing the `for_k8s_version` shortcode parameter. For example:
```
{{</* feature-state for_k8s_version="v1.10" state="stable" */>}}
{{</* feature-state for_k8s_version="v1.10" state="beta" */>}}
```
Renders to:
{{< feature-state for_k8s_version="v1.10" state="stable" >}}
#### Alpha feature
```
{{</* feature-state state="alpha" */>}}
```
Renders to:
{{< feature-state state="alpha" >}}
#### Beta feature
```
{{</* feature-state state="beta" */>}}
```
Renders to:
{{< feature-state state="beta" >}}
#### Stable feature
```
{{</* feature-state state="stable" */>}}
```
Renders to:
{{< feature-state state="stable" >}}
#### Deprecated feature
```
{{</* feature-state state="deprecated" */>}}
```
Renders to:
{{< feature-state state="deprecated" >}}
{{< feature-state for_k8s_version="v1.10" state="beta" >}}
## Glossary
There are two glossary tooltips.
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 term is moused-over by someone
using the online documentation, the glossary entry displays a tooltip.
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.
@@ -102,7 +59,7 @@ The raw data for glossary terms is stored at [https://github.com/kubernetes/webs
### 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" */>}}
@@ -113,13 +70,16 @@ Here's a short glossary definition:
```
{{</* glossary_definition prepend="A cluster is" term_id="cluster" length="short" */>}}
```
which renders as:
{{< glossary_definition prepend="A cluster is" term_id="cluster" length="short" >}}
You can also include a full definition:
```
{{</* glossary_definition term_id="cluster" length="all" */>}}
```
which renders as:
{{< glossary_definition term_id="cluster" length="all" >}}
@@ -255,7 +215,63 @@ Renders to:
{{< tab name="JSON File" include="podtemplate.json" />}}
{{< /tabs >}}
## Version strings
To generate a version string for inclusion in the documentation, you can choose from
several version shortcodes. Each version shortcode displays a version string derived from
the value of a version parameter found in the site configuration file, `config.toml`.
The two most commonly used version parameters are `latest` and `version`.
### `{{</* param "version" */>}}`
The `{{</* param "version" */>}}` 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`.
{{< /note >}}
Renders to:
{{< param "version" >}}
### `{{</* latest-version */>}}`
The `{{</* latest-version */>}}` shortcode returns the value of the `latest` site parameter.
The `latest` site parameter is updated when a new version of the documentation is released.
This parameter does not always match the value of `version` in a documentation set.
Renders to:
{{< latest-version >}}
### `{{</* latest-semver */>}}`
The `{{</* latest-semver */>}}` shortcode generates the value of `latest` without the "v" prefix.
Renders to:
{{< latest-semver >}}
### `{{</* version-check */>}}`
The `{{</* version-check */>}}` shortcode checks if the `min-kubernetes-server-version`
page parameter is present and then uses this value to compare to `version`.
Renders to:
{{< version-check >}}
### `{{</* latest-release-notes */>}}`
The `{{</* latest-release-notes */>}}` 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:
{{< latest-release-notes >}}
## {{% heading "whatsnext" %}}
@@ -264,4 +280,3 @@ 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/).