Custom Jekyll Include Snippets
This page explains the custom Jekyll include snippets that can be used in Kubernetes documentation markdown.
Read more about includes in the Jekyll documentation.
Feature state
In a markdown page (.md file) on this site, you can add a tag to display version and state of the documented feature.
Feature state demo
Below is a demo of the feature state snippet. Here it is used to display the feature as stable in Kubernetes version 1.6.
FEATURE STATE: Kubernetes 1.6 stable
This feature is stable, meaning:
- The version name is vX where X is an integer.
- Stable versions of features will appear in released software for many subsequent versions.
Feature state code
Below is the template code for each available feature state.
The displayed Kubernetes version defaults to that of the page. This can be
changed by setting the for_k8s_version variable.
{% assign for_k8s_version = "1.6" %}
{% include feature-state-stable.md %}
Alpha feature
{% include feature-state-alpha.md %}
Beta feature
{% include feature-state-beta.md %}
Stable feature
{% include feature-state-stable.md %}
Deprecated feature
{% include feature-state-deprecated.md %}
Glossary
You can reference glossary terms with an inclusion that will automatically update and replace content with the relevant links from our glossary. When the term is moused-over by someone using the online documentation, the glossary entry will display a tooltip.
The raw data for glossary terms is stored at https://github.com/kubernetes/website/tree/master/_data/glossary, with a YAML file for each glossary term.
Glossary Demo
For example, the following include within the markdown will render to clusterA set of machines, called nodes, that run containerized applications managed by Kubernetes. with a tooltip:
{% glossary_tooltip text="cluster" term_id="cluster" %}
Tabs
In a markdown page (.md file) on this site, you can add a tab set to display multiple flavors of a given solution.
Tabs demo
Below is a demo of the tabs snippet. Here it is used to display each of the installation commands for the various Kubernetes network solutions.
Select one of the tabs.
kubectl apply -f "http://docs.projectcalico.org/v2.4/getting-started/kubernetes/installation/hosted/kubeadm/calico.yaml"
kubectl apply -f "https://github.com/coreos/flannel/blob/master/Documentation/kube-flannel.yml?raw=true"
kubectl apply -f "https://raw.githubusercontent.com/romana/romana/master/containerize/specs/romana-kubeadm.yml"
kubectl apply -f "https://git.io/weave-kube"
Example Liquid template code for tabs
Below is the Liquid template code for the tabs demo above to illustrate how to specify the contents of each tab. The /_includes/tabs.md file included at the end then uses those elements to render the actual tab set.
The following sections break down each of the individual features used.
{% capture default_tab %}
Select one of the tabs.
{% endcapture %}
{% capture calico %}
```shell
kubectl apply -f "http://docs.projectcalico.org/v2.4/getting-started/kubernetes/installation/hosted/kubeadm/calico.yaml"
```
{% endcapture %}
{% capture flannel %}
```shell
kubectl apply -f "https://github.com/coreos/flannel/blob/master/Documentation/kube-flannel.yml?raw=true"
```
{% endcapture %}
{% capture romana %}
```shell
kubectl apply -f "https://raw.githubusercontent.com/romana/romana/master/containerize/specs/romana-kubeadm.yml"
```
{% endcapture %}
{% capture weave_net %}
```shell
kubectl apply -f "https://git.io/weave-kube"
```
{% endcapture %}
{% assign tab_names = 'Default,Calico,Flannel,Romana,Weave Net' | split: ',' | compact %}
{% assign tab_contents = site.emptyArray | push: default_tab | push: calico | push: flannel | push: romana | push: weave_net %}
{% include tabs.md %}
Capturing tab content
{% capture calico %}
```shell
kubectl apply -f "http://docs.projectcalico.org/v2.4/getting-started/kubernetes/installation/hosted/kubeadm/calico.yaml"
```
{% endcapture %}
The capture [variable_name] tags store text or markdown content and assign them to the specified variable.
Assigning tab names
{% assign tab_names = 'Default,Calico,Flannel,Romana,Weave Net' | split: ',' | compact %}
The assign tab_names tag takes a list of labels to use for the tabs. Label text can include spaces. The given comma delimited string is split into an array and assigned to the tab_names variable.
Assigning tab contents
{% assign tab_contents = site.emptyArray | push: default_tab | push: calico | push: flannel | push: romana | push: weave_net %}
The assign tab_contents tag adds the contents of each tab pane, captured above, as elements to the tab_contents array.
Including the tabs.md template
{% include tabs.md %}
{% include tabs.md %} pulls in the tabs template code, which uses the tab_names and tab_contents variables to render the tab set.
What’s next
- Learn about Jekyll.
- Learn about writing a new topic.
- Learn about using page templates.
- Learn about staging your changes
- Learn about creating a pull request.