This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Documentation style overview

The topics in this section provide guidance on writing style, content formatting and organization, and using Hugo customizations specific to Kubernetes documentation.

1 - Documentation Content Guide

This page contains guidelines for Kubernetes documentation.

If you have questions about what's allowed, join the #sig-docs channel in Kubernetes Slack and ask!

You can register for Kubernetes Slack at https://slack.k8s.io/.

For information on creating new content for the Kubernetes docs, follow the style guide.

Overview

Source for the Kubernetes website, including the docs, resides in the kubernetes/website repository.

Located in the kubernetes/website/content/<language_code>/docs folder, the majority of Kubernetes documentation is specific to the Kubernetes project.

What's allowed

Kubernetes docs allow content for third-party projects only when:

  • Content documents software in the Kubernetes project
  • Content documents software that's out of project but necessary for Kubernetes to function
  • Content is canonical on kubernetes.io, or links to canonical content elsewhere

Third party content

Kubernetes documentation includes applied examples of projects in the Kubernetes project—projects that live in the kubernetes and kubernetes-sigs GitHub organizations.

Links to active content in the Kubernetes project are always allowed.

Kubernetes requires some third party content to function. Examples include container runtimes (containerd, CRI-O, Docker), networking policy (CNI plugins), Ingress controllers, and logging.

Docs can link to third-party open source software (OSS) outside the Kubernetes project only if it's necessary for Kubernetes to function.

Dual sourced content

Wherever possible, Kubernetes docs link to canonical sources instead of hosting dual-sourced content.

Dual-sourced content requires double the effort (or more!) to maintain and grows stale more quickly.

More information

If you have questions about allowed content, join the Kubernetes Slack #sig-docs channel and ask!

What's next

2 - Documentation Style Guide

This page gives writing style guidelines for the Kubernetes documentation. These are guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

For additional information on creating new content for the Kubernetes documentation, read the Documentation Content Guide.

Changes to the style guide are made by SIG Docs as a group. To propose a change or addition, add it to the agenda for an upcoming SIG Docs meeting, and attend the meeting to participate in the discussion.

Language

Kubernetes documentation has been translated into multiple languages (see Localization READMEs).

The way of localizing the docs for a different language is described in Localizing Kubernetes Documentation.

The English-language documentation uses U.S. English spelling and grammar.

Documentation formatting standards

Use upper camel case for API objects

When you refer specifically to interacting with an API object, use UpperCamelCase, also known as Pascal case. You may see different capitalization, such as "configMap", in the API Reference. When writing general documentation, it's better to use upper camel case, calling it "ConfigMap" instead.

When you are generally discussing an API object, use sentence-style capitalization.

You may use the word "resource", "API", or "object" to clarify a Kubernetes resource type in a sentence.

Don't split an API object name into separate words. For example, use PodTemplateList, not Pod Template List.

The following examples focus on capitalization. For more information about formatting API object names, review the related guidance on Code Style.

Do and Don't - Use Pascal case for API objects
Do Don't
The HorizontalPodAutoscaler resource is responsible for ... The Horizontal pod autoscaler is responsible for ...
A PodList object is a list of pods. A Pod List object is a list of pods.
The Volume object contains a hostPath field. The volume object contains a hostPath field.
Every ConfigMap object is part of a namespace. Every configMap object is part of a namespace.
For managing confidential data, consider using the Secret API. For managing confidential data, consider using the secret API.

Use angle brackets for placeholders

Use angle brackets for placeholders. Tell the reader what a placeholder represents, for example:

Display information about a pod:

kubectl describe pod <pod-name> -n <namespace>

If the namespace of the pod is default, you can omit the '-n' parameter.

Use bold for user interface elements

Do and Don't - Bold interface elements
Do Don't
Click Fork. Click "Fork".
Select Other. Select "Other".

Use italics to define or introduce new terms

Do and Don't - Use italics for new terms
Do Don't
A cluster is a set of nodes ... A "cluster" is a set of nodes ...
These components form the control plane. These components form the control plane.

Use code style for filenames, directories, and paths

Do and Don't - Use code style for filenames, directories, and paths
Do Don't
Open the envars.yaml file. Open the envars.yaml file.
Go to the /docs/tutorials directory. Go to the /docs/tutorials directory.
Open the /_data/concepts.yaml file. Open the /_data/concepts.yaml file.

Use the international standard for punctuation inside quotes

Do and Don't - Use the international standard for punctuation inside quotes
Do Don't
events are recorded with an associated "stage". events are recorded with an associated "stage."
The copy is called a "fork". The copy is called a "fork."

Inline code formatting

Use code style for inline code, commands, and API objects

For inline code in an HTML document, use the <code> tag. In a Markdown document, use the backtick (`).

Do and Don't - Use code style for inline code, commands, and API objects
Do Don't
The kubectl run command creates a Pod. The "kubectl run" command creates a pod.
The kubelet on each node acquires a Lease The kubelet on each node acquires a lease…
A PersistentVolume represents durable storage… A Persistent Volume represents durable storage…
For declarative management, use kubectl apply. For declarative management, use "kubectl apply".
Enclose code samples with triple backticks. (```) Enclose code samples with any other syntax.
Use single backticks to enclose inline code. For example, var example = true. Use two asterisks (**) or an underscore (_) to enclose inline code. For example, var example = true.
Use triple backticks before and after a multi-line block of code for fenced code blocks. Use multi-line blocks of code to create diagrams, flowcharts, or other illustrations.
Use meaningful variable names that have a context. Use variable names such as 'foo','bar', and 'baz' that are not meaningful and lack context.
Remove trailing spaces in the code. Add trailing spaces in the code, where these are important, because the screen reader will read out the spaces as well.

Use code style for object field names and namespaces

Do and Don't - Use code style for object field names
Do Don't
Set the value of the replicas field in the configuration file. Set the value of the "replicas" field in the configuration file.
The value of the exec field is an ExecAction object. The value of the "exec" field is an ExecAction object.
Run the process as a DaemonSet in the kube-system namespace. Run the process as a DaemonSet in the kube-system namespace.

Use code style for Kubernetes command tool and component names

Do and Don't - Use code style for Kubernetes command tool and component names
Do Don't
The kubelet preserves node stability. The kubelet preserves node stability.
The kubectl handles locating and authenticating to the API server. The kubectl handles locating and authenticating to the apiserver.
Run the process with the certificate, kube-apiserver --client-ca-file=FILENAME. Run the process with the certificate, kube-apiserver --client-ca-file=FILENAME.

Starting a sentence with a component tool or component name

Do and Don't - Starting a sentence with a component tool or component name
Do Don't
The kubeadm tool bootstraps and provisions machines in a cluster. kubeadm tool bootstraps and provisions machines in a cluster.
The kube-scheduler is the default scheduler for Kubernetes. kube-scheduler is the default scheduler for Kubernetes.

Use a general descriptor over a component name

Do and Don't - Use a general descriptor over a component name
Do Don't
The Kubernetes API server offers an OpenAPI spec. The apiserver offers an OpenAPI spec.
Aggregated APIs are subordinate API servers. Aggregated APIs are subordinate APIServers.

Use normal style for string and integer field values

For field values of type string or integer, use normal style without quotation marks.

Do and Don't - Use normal style for string and integer field values
Do Don't
Set the value of imagePullPolicy to Always. Set the value of imagePullPolicy to "Always".
Set the value of image to nginx:1.16. Set the value of image to nginx:1.16.
Set the value of the replicas field to 2. Set the value of the replicas field to 2.

Code snippet formatting

Don't include the command prompt

Do and Don't - Don't include the command prompt
Do Don't
kubectl get pods $ kubectl get pods

Separate commands from output

Verify that the pod is running on your chosen node:

kubectl get pods --output=wide

The output is similar to this:

NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0

Versioning Kubernetes examples

Code examples and configuration examples that include version information should be consistent with the accompanying text.

If the information is version specific, the Kubernetes version needs to be defined in the prerequisites section of the Task template or the Tutorial template. Once the page is saved, the prerequisites section is shown as Before you begin.

To specify the Kubernetes version for a task or tutorial page, include min-kubernetes-server-version in the front matter of the page.

If the example YAML is in a standalone file, find and review the topics that include it as a reference. Verify that any topics using the standalone YAML have the appropriate version information defined. If a stand-alone YAML file is not referenced from any topics, consider deleting it instead of updating it.

For example, if you are writing a tutorial that is relevant to Kubernetes version 1.8, the front-matter of your markdown file should look something like:

---
title: <your tutorial title here>
min-kubernetes-server-version: v1.8
---

In code and configuration examples, do not include comments about alternative versions. Be careful to not include incorrect statements in your examples as comments, such as:

apiVersion: v1 # earlier versions use...
kind: Pod
...

Kubernetes.io word list

A list of Kubernetes-specific terms and words to be used consistently across the site.

Kubernetes.io word list
Term Usage
Kubernetes Kubernetes should always be capitalized.
Docker Docker should always be capitalized.
SIG Docs SIG Docs rather than SIG-DOCS or other variations.
On-premises On-premises or On-prem rather than On-premise or other variations.

Shortcodes

Hugo Shortcodes help create different rhetorical appeal levels. Our documentation supports three different shortcodes in this category: Note {{< note >}}, Caution {{< caution >}}, and Warning {{< warning >}}.

  1. Surround the text with an opening and closing shortcode.

  2. Use the following syntax to apply a style:

    {{< note >}}
    No need to include a prefix; the shortcode automatically provides one. (Note:, Caution:, etc.)
    {{< /note >}}
    

    The output is:

Note

Use {{< note >}} to highlight a tip or a piece of information that may be helpful to know.

For example:

{{< note >}}
You can _still_ use Markdown inside these callouts.
{{< /note >}}

The output is:

You can use a {{< note >}} in a list:

1. Use the note shortcode in a list

1. A second item with an embedded note

   {{< note >}}
   Warning, Caution, and Note shortcodes, embedded in lists, need to be indented four spaces. See [Common Shortcode Issues](#common-shortcode-issues).
   {{< /note >}}

1. A third item in a list

1. A fourth item in a list

The output is:

  1. Use the note shortcode in a list

  2. A second item with an embedded note

  3. A third item in a list

  4. A fourth item in a list

Caution

Use {{< caution >}} to call attention to an important piece of information to avoid pitfalls.

For example:

{{< caution >}}
The callout style only applies to the line directly above the tag.
{{< /caution >}}

The output is:

Warning

Use {{< warning >}} to indicate danger or a piece of information that is crucial to follow.

For example:

{{< warning >}}
Beware.
{{< /warning >}}

The output is:

Katacoda Embedded Live Environment

This button lets users run Minikube in their browser using the Katacoda Terminal. It lowers the barrier of entry by allowing users to use Minikube with one click instead of going through the complete Minikube and Kubectl installation process locally.

The Embedded Live Environment is configured to run minikube start and lets users complete tutorials in the same window as the documentation.

For example:

{{< kat-button >}}

The output is:

Common Shortcode Issues

Ordered Lists

Shortcodes will interrupt numbered lists unless you indent four spaces before the notice and the tag.

For example:

1. Preheat oven to 350˚F

1. Prepare the batter, and pour into springform pan.
   `{{< note >}}Grease the pan for best results.{{< /note >}}`

1. Bake for 20-25 minutes or until set.

The output is:

  1. Preheat oven to 350˚F

  2. Prepare the batter, and pour into springform pan.

  3. Bake for 20-25 minutes or until set.

Include Statements

Shortcodes inside include statements will break the build. You must insert them in the parent document, before and after you call the include. For example:

{{< note >}}
{{< include "task-tutorial-prereqs.md" >}}
{{< /note >}}

Markdown elements

Line breaks

Use a single newline to separate block-level content like headings, lists, images, code blocks, and others. The exception is second-level headings, where it should be two newlines. Second-level headings follow the first-level (or the title) without any preceding paragraphs or texts. A two line spacing helps visualize the overall structure of content in a code editor better.

Headings

People accessing this documentation may use a screen reader or other assistive technology (AT). Screen readers are linear output devices, they output items on a page one at a time. If there is a lot of content on a page, you can use headings to give the page an internal structure. A good page structure helps all readers to easily navigate the page or filter topics of interest.

Do and Don't - Headings
Do Don't
Update the title in the front matter of the page or blog post. Use first level heading, as Hugo automatically converts the title in the front matter of the page into a first-level heading.
Use ordered headings to provide a meaningful high-level outline of your content. Use headings level 4 through 6, unless it is absolutely necessary. If your content is that detailed, it may need to be broken into separate articles.
Use pound or hash signs (#) for non-blog post content. Use underlines (--- or ===) to designate first-level headings.
Use sentence case for headings. For example, Extend kubectl with plugins Use title case for headings. For example, Extend Kubectl With Plugins

Paragraphs

Do and Don't - Paragraphs
Do Don't
Try to keep paragraphs under 6 sentences. Indent the first paragraph with space characters. For example, ⋅⋅⋅Three spaces before a paragraph will indent it.
Use three hyphens (---) to create a horizontal rule. Use horizontal rules for breaks in paragraph content. For example, a change of scene in a story, or a shift of topic within a section. Use horizontal rules for decoration.
Do and Don't - Links
Do Don't
Write hyperlinks that give you context for the content they link to. For example: Certain ports are open on your machines. See Check required ports for more details. Use ambiguous terms such as "click here". For example: Certain ports are open on your machines. See here for more details.
Write Markdown-style links: [link text](URL). For example: [Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/#table-captions) and the output is Hugo shortcodes. Write HTML-style links: <a href="/media/examples/link-element-example.css" target="_blank">Visit our tutorial!</a>, or create links that open in new tabs or windows. For example: [example website](https://example.com){target="_blank"}

Lists

Group items in a list that are related to each other and need to appear in a specific order or to indicate a correlation between multiple items. When a screen reader comes across a list—whether it is an ordered or unordered list—it will be announced to the user that there is a group of list items. The user can then use the arrow keys to move up and down between the various items in the list. Website navigation links can also be marked up as list items; after all they are nothing but a group of related links.

  • End each item in a list with a period if one or more items in the list are complete sentences. For the sake of consistency, normally either all items or none should be complete sentences.

  • Use the number one (1.) for ordered lists.

  • Use (+), (*), or (-) for unordered lists.

  • Leave a blank line after each list.

  • Indent nested lists with four spaces (for example, ⋅⋅⋅⋅).

  • List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either four spaces or one tab.

Tables

The semantic purpose of a data table is to present tabular data. Sighted users can quickly scan the table but a screen reader goes through line by line. A table caption is used to create a descriptive title for a data table. Assistive technologies (AT) use the HTML table caption element to identify the table contents to the user within the page structure.

Content best practices

This section contains suggested best practices for clear, concise, and consistent content.

Use present tense

Do and Don't - Use present tense
Do Don't
This command starts a proxy. This command will start a proxy.

Exception: Use future or past tense if it is required to convey the correct meaning.

Use active voice

Do and Don't - Use active voice
Do Don't
You can explore the API using a browser. The API can be explored using a browser.
The YAML file specifies the replica count. The replica count is specified in the YAML file.

Exception: Use passive voice if active voice leads to an awkward construction.

Use simple and direct language

Use simple and direct language. Avoid using unnecessary phrases, such as saying "please."

Do and Don't - Use simple and direct language
Do Don't
To create a ReplicaSet, ... In order to create a ReplicaSet, ...
See the configuration file. Please see the configuration file.
View the pods. With this next command, we'll view the pods.

Address the reader as "you"

Do and Don't - Addressing the reader
Do Don't
You can create a Deployment by ... We'll create a Deployment by ...
In the preceding output, you can see... In the preceding output, we can see ...

Avoid Latin phrases

Prefer English terms over Latin abbreviations.

Do and Don't - Avoid Latin phrases
Do Don't
For example, ... e.g., ...
That is, ... i.e., ...

Exception: Use "etc." for et cetera.

Patterns to avoid

Avoid using "we"

Using "we" in a sentence can be confusing, because the reader might not know whether they're part of the "we" you're describing.

Do and Don't - Patterns to avoid
Do Don't
Version 1.4 includes ... In version 1.4, we have added ...
Kubernetes provides a new feature for ... We provide a new feature ...
This page teaches you how to use pods. In this page, we are going to learn about pods.

Avoid jargon and idioms

Some readers speak English as a second language. Avoid jargon and idioms to help them understand better.

Do and Don't - Avoid jargon and idioms
Do Don't
Internally, ... Under the hood, ...
Create a new cluster. Turn up a new cluster.

Avoid statements about the future

Avoid making promises or giving hints about the future. If you need to talk about an alpha feature, put the text under a heading that identifies it as alpha information.

An exception to this rule is documentation about announced deprecations targeting removal in future versions. One example of documentation like this is the Deprecated API migration guide.

Avoid statements that will soon be out of date

Avoid words like "currently" and "new." A feature that is new today might not be considered new in a few months.

Do and Don't - Avoid statements that will soon be out of date
Do Don't
In version 1.4, ... In the current version, ...
The Federation feature provides ... The new Federation feature provides ...

Avoid words that assume a specific level of understanding

Avoid words such as "just", "simply", "easy", "easily", or "simple". These words do not add value.

Do and Don't - Avoid insensitive words
Do Don't
Include one command in ... Include just one command in ...
Run the container ... Simply run the container ...
You can remove ... You can easily remove ...
These steps ... These simple steps ...

What's next

3 - Writing a new topic

This page shows how to create a new topic for the Kubernetes docs.

Before you begin

Create a fork of the Kubernetes documentation repository as described in Open a PR.

Choosing a page type

As you prepare to write a new topic, think about the page type that would fit your content the best:

Guidelines for choosing a page type
Type Description
Concept A concept page explains some aspect of Kubernetes. For example, a concept page might describe the Kubernetes Deployment object and explain the role it plays as an application while it is deployed, scaled, and updated. Typically, concept pages don't include sequences of steps, but instead provide links to tasks or tutorials. For an example of a concept topic, see Nodes.
Task A task page shows how to do a single thing. The idea is to give readers a sequence of steps that they can actually do as they read the page. A task page can be short or long, provided it stays focused on one area. In a task page, it is OK to blend brief explanations with the steps to be performed, but if you need to provide a lengthy explanation, you should do that in a concept topic. Related task and concept topics should link to each other. For an example of a short task page, see Configure a Pod to Use a Volume for Storage. For an example of a longer task page, see Configure Liveness and Readiness Probes
Tutorial A tutorial page shows how to accomplish a goal that ties together several Kubernetes features. A tutorial might provide several sequences of steps that readers can actually do as they read the page. Or it might provide explanations of related pieces of code. For example, a tutorial could provide a walkthrough of a code sample. A tutorial can include brief explanations of the Kubernetes features that are being tied together, but should link to related concept topics for deep explanations of individual features.

Creating a new page

Use a content type for each new page that you write. The docs site provides templates or Hugo archetypes to create new content pages. To create a new type of page, run hugo new with the path to the file you want to create. For example:

hugo new docs/concepts/my-first-concept.md

Choosing a title and filename

Choose a title that has the keywords you want search engines to find. Create a filename that uses the words in your title separated by hyphens. For example, the topic with title Using an HTTP Proxy to Access the Kubernetes API has filename http-proxy-access-api.md. You don't need to put "kubernetes" in the filename, because "kubernetes" is already in the URL for the topic, for example:

   /docs/tasks/extend-kubernetes/http-proxy-access-api/

Adding the topic title to the front matter

In your topic, put a title field in the front matter. The front matter is the YAML block that is between the triple-dashed lines at the top of the page. Here's an example:

---
title: Using an HTTP Proxy to Access the Kubernetes API
---

Choosing a directory

Depending on your page type, put your new file in a subdirectory of one of these:

  • /content/en/docs/tasks/
  • /content/en/docs/tutorials/
  • /content/en/docs/concepts/

You can put your file in an existing subdirectory, or you can create a new subdirectory.

Placing your topic in the table of contents

The table of contents is built dynamically using the directory structure of the documentation source. The top-level directories under /content/en/docs/ create top-level navigation, and subdirectories each have entries in the table of contents.

Each subdirectory has a file _index.md, which represents the "home" page for a given subdirectory's content. The _index.md does not need a template. It can contain overview content about the topics in the subdirectory.

Other files in a directory are sorted alphabetically by default. This is almost never the best order. To control the relative sorting of topics in a subdirectory, set the weight: front-matter key to an integer. Typically, we use multiples of 10, to account for adding topics later. For instance, a topic with weight 10 will come before one with weight 20.

Embedding code in your topic

If you want to include some code in your topic, you can embed the code in your file directly using the markdown code block syntax. This is recommended for the following cases (not an exhaustive list):

  • The code shows the output from a command such as kubectl get deploy mydeployment -o json | jq '.status'.
  • The code is not generic enough for users to try out. As an example, you can embed the YAML file for creating a Pod which depends on a specific FlexVolume implementation.
  • The code is an incomplete example because its purpose is to highlight a portion of a larger file. For example, when describing ways to customize the PodSecurityPolicy for some reasons, you can provide a short snippet directly in your topic file.
  • The code is not meant for users to try out due to other reasons. For example, when describing how a new attribute should be added to a resource using the kubectl edit command, you can provide a short example that includes only the attribute to add.

Including code from another file

Another way to include code in your topic is to create a new, complete sample file (or group of sample files) and then reference the sample from your topic. Use this method to include sample YAML files when the sample is generic and reusable, and you want the reader to try it out themselves.

When adding a new standalone sample file, such as a YAML file, place the code in one of the <LANG>/examples/ subdirectories where <LANG> is the language for the topic. In your topic file, use the codenew shortcode:

{{< codenew file="<RELPATH>/my-example-yaml>" >}}

where <RELPATH> is the path to the file to include, relative to the examples directory. The following Hugo shortcode references a YAML file located at /content/en/examples/pods/storage/gce-volume.yaml.

{{< codenew file="pods/storage/gce-volume.yaml" >}}

Showing how to create an API object from a configuration file

If you need to demonstrate how to create an API object based on a configuration file, place the configuration file in one of the subdirectories under <LANG>/examples.

In your topic, show this command:

kubectl create -f https://k8s.io/examples/pods/storage/gce-volume.yaml

For an example of a topic that uses this technique, see Running a Single-Instance Stateful Application.

Adding images to a topic

Put image files in the /images directory. The preferred image format is SVG.

What's next

4 - Page content types

The Kubernetes documentation follows several types of page content:

  • Concept
  • Task
  • Tutorial
  • Reference

Content sections

Each page content type contains a number of sections defined by Markdown comments and HTML headings. You can add content headings to your page with the heading shortcode. The comments and headings help maintain the structure of the page content types.

Examples of Markdown comments defining page content sections:

<!-- overview -->
<!-- body -->

To create common headings in your content pages, use the heading shortcode with a heading string.

Examples of heading strings:

  • whatsnext
  • prerequisites
  • objectives
  • cleanup
  • synopsis
  • seealso
  • options

For example, to create a whatsnext heading, add the heading shortcode with the "whatsnext" string:

## {{% heading "whatsnext" %}}

You can declare a prerequisites heading as follows:

## {{% heading "prerequisites" %}}

The heading shortcode expects one string parameter. The heading string parameter matches the prefix of a variable in the i18n/<lang>.toml files. For example:

i18n/en.toml:

[whatsnext_heading]
other = "What's next"

i18n/ko.toml:

[whatsnext_heading]
other = "다음 내용"

Content types

Each content type informally defines its expected page structure. Create page content with the suggested page sections.

Concept

A concept page explains some aspect of Kubernetes. For example, a concept page might describe the Kubernetes Deployment object and explain the role it plays as an application once it is deployed, scaled, and updated. Typically, concept pages don't include sequences of steps, but instead provide links to tasks or tutorials.

To write a new concept page, create a Markdown file in a subdirectory of the /content/en/docs/concepts directory, with the following characteristics:

Concept pages are divided into three sections:

Page section
overview
body
whatsnext

The overview and body sections appear as comments in the concept page. You can add the whatsnext section to your page with the heading shortcode.

Fill each section with content. Follow these guidelines:

  • Organize content with H2 and H3 headings.
  • For overview, set the topic's context with a single paragraph.
  • For body, explain the concept.
  • For whatsnext, provide a bulleted list of topics (5 maximum) to learn more about the concept.

Annotations is a published example of a concept page.

Task

A task page shows how to do a single thing, typically by giving a short sequence of steps. Task pages have minimal explanation, but often provide links to conceptual topics that provide related background and knowledge.

To write a new task page, create a Markdown file in a subdirectory of the /content/en/docs/tasks directory, with the following characteristics:

Page section
overview
prerequisites
steps
discussion
whatsnext

The overview, steps, and discussion sections appear as comments in the task page. You can add the prerequisites and whatsnext sections to your page with the heading shortcode.

Within each section, write your content. Use the following guidelines:

  • Use a minimum of H2 headings (with two leading # characters). The sections themselves are titled automatically by the template.
  • For overview, use a paragraph to set context for the entire topic.
  • For prerequisites, use bullet lists when possible. Start adding additional prerequisites below the include. The default prerequisites include a running Kubernetes cluster.
  • For steps, use numbered lists.
  • For discussion, use normal content to expand upon the information covered in steps.
  • For whatsnext, give a bullet list of up to 5 topics the reader might be interested in reading next.

An example of a published task topic is Using an HTTP proxy to access the Kubernetes API.

Tutorial

A tutorial page shows how to accomplish a goal that is larger than a single task. Typically a tutorial page has several sections, each of which has a sequence of steps. For example, a tutorial might provide a walkthrough of a code sample that illustrates a certain feature of Kubernetes. Tutorials can include surface-level explanations, but should link to related concept topics for deep explanations.

To write a new tutorial page, create a Markdown file in a subdirectory of the /content/en/docs/tutorials directory, with the following characteristics:

Page section
overview
prerequisites
objectives
lessoncontent
cleanup
whatsnext

The overview, objectives, and lessoncontent sections appear as comments in the tutorial page. You can add the prerequisites, cleanup, and whatsnext sections to your page with the heading shortcode.

Within each section, write your content. Use the following guidelines:

  • Use a minimum of H2 headings (with two leading # characters). The sections themselves are titled automatically by the template.
  • For overview, use a paragraph to set context for the entire topic.
  • For prerequisites, use bullet lists when possible. Add additional prerequisites below the ones included by default.
  • For objectives, use bullet lists.
  • For lessoncontent, use a mix of numbered lists and narrative content as appropriate.
  • For cleanup, use numbered lists to describe the steps to clean up the state of the cluster after finishing the task.
  • For whatsnext, give a bullet list of up to 5 topics the reader might be interested in reading next.

An example of a published tutorial topic is Running a Stateless Application Using a Deployment.

Reference

A component tool reference page shows the description and flag options output for a Kubernetes component tool. Each page generates from scripts using the component tool commands.

A tool reference page has several possible sections:

Page section
synopsis
options
options from parent commands
examples
seealso

Examples of published tool reference pages are:

What's next

5 - Content organization

This site uses Hugo. In Hugo, content organization is a core concept.

Page Lists

Page Order

The documentation side menu, the documentation page browser etc. are listed using Hugo's default sort order, which sorts by weight (from 1), date (newest first), and finally by the link title.

Given that, if you want to move a page or a section up, set a weight in the page's front matter:

title: My Page
weight: 10

Documentation Main Menu

The Documentation main menu is built from the sections below docs/ with the main_menu flag set in front matter of the _index.md section content file:

main_menu: true

Note that the link title is fetched from the page's linkTitle, so if you want it to be something different than the title, change it in the content file:

main_menu: true
title: Page Title
linkTitle: Title used in links

Documentation Side Menu

The documentation side-bar menu is built from the current section tree starting below docs/.

It will show all sections and their pages.

If you don't want to list a section or page, set the toc_hide flag to true in front matter:

toc_hide: true

When you navigate to a section that has content, the specific section or page (e.g. _index.md) is shown. Else, the first page inside that section is shown.

Documentation Browser

The page browser on the documentation home page is built using all the sections and pages that are directly below the docs section.

If you don't want to list a section or page, set the toc_hide flag to true in front matter:

toc_hide: true

The Main Menu

The site links in the top-right menu -- and also in the footer -- are built by page-lookups. This is to make sure that the page actually exists. So, if the case-studies section does not exist in a site (language), it will not be linked to.

Page Bundles

In addition to standalone content pages (Markdown files), Hugo supports Page Bundles.

One example is Custom Hugo Shortcodes. It is considered a leaf bundle. Everything below the directory, including the index.md, will be part of the bundle. This also includes page-relative links, images that can be processed etc.:

en/docs/home/contribute/includes
├── example1.md
├── example2.md
├── index.md
└── podtemplate.json

Another widely used example is the includes bundle. It sets headless: true in front matter, which means that it does not get its own URL. It is only used in other pages.

en/includes
├── default-storage-class-prereqs.md
├── index.md
├── partner-script.js
├── partner-style.css
├── task-tutorial-prereqs.md
├── user-guide-content-moved.md
└── user-guide-migration-notice.md

Some important notes to the files in the bundles:

  • For translated bundles, any missing non-content files will be inherited from languages above. This avoids duplication.
  • All the files in a bundle are what Hugo calls Resources and you can provide metadata per language, such as parameters and title, even if it does not supports front matter (YAML files etc.). See Page Resources Metadata.
  • The value you get from .RelPermalink of a Resource is page-relative. See Permalinks.

Styles

The SASS source of the stylesheets for this site is stored in assets/sass and is automatically built by Hugo.

What's next

6 - Custom Hugo Shortcodes

This page explains the custom Hugo shortcodes that can be used in Kubernetes Markdown documentation.

Read more about shortcodes in the Hugo documentation.

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.

Feature state demo

Below is a demo of the feature state snippet, which displays the feature as stable in the latest Kubernetes version.

{{< feature-state state="stable" >}}

Renders to:

FEATURE STATE: Kubernetes v1.22 [stable]

The valid values for state are:

  • alpha
  • beta
  • deprecated
  • stable

Feature state code

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="beta" >}}

Renders to:

FEATURE STATE: Kubernetes v1.10 [beta]

Glossary

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. 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, with a content file for each glossary term.

Glossary demo

For example, the following include within the Markdown renders to cluster with a tooltip:

{{< glossary_tooltip text="cluster" term_id="cluster" >}}

Here's a short glossary definition:

{{< glossary_definition prepend="A cluster is" term_id="cluster" length="short" >}}

which renders as:

A cluster is a set of worker machines, called nodes, that run containerized applications. Every cluster has at least one worker node.

You can also include a full definition:

{{< glossary_definition term_id="cluster" length="all" >}}

which renders as:

A set of worker machines, called nodes, that run containerized applications. Every cluster has at least one worker node.

The worker node(s) host the Pods that are the components of the application workload. The control plane manages the worker nodes and the Pods in the cluster. In production environments, the control plane usually runs across multiple computers and a cluster usually runs multiple nodes, providing fault-tolerance and high availability.

You can link to a page of the Kubernetes API reference using the api-reference shortcode, for example to the Pod reference:

{{< api-reference page="workload-resources/pod-v1" >}}

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 PodSpec reference or the environment-variables section of the page:

{{< api-reference page="workload-resources/pod-v1" anchor="PodSpec" >}}
{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" >}}

You can change the text of the link by specifying a text parameter, for example by linking to the Environment Variables section of the page:

{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="Environment Variable" >}}

Table captions

You can make tables more accessible to screen readers by adding a table caption. To add a caption to a table, enclose the table with a table shortcode and specify the caption with the caption parameter.

Here's an example:

{{< table caption="Configuration parameters" >}}
Parameter | Description | Default
:---------|:------------|:-------
`timeout` | The timeout for requests | `30s`
`logLevel` | The log level for log output | `INFO`
{{< /table >}}

The rendered table looks like this:

Configuration parameters
Parameter Description Default
timeout The timeout for requests 30s
logLevel The log level for log output INFO

If you inspect the HTML for the table, you should see this element immediately after the opening <table> element:

<caption style="display: none;">Configuration parameters</caption>

Tabs

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, 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.

Below is a demo of the tabs shortcode.

Tabs demo: Code highlighting

{{< tabs name="tab_with_code" >}}
{{{< tab name="Tab 1" codelang="bash" >}}
echo "This is tab 1."
{{< /tab >}}
{{< tab name="Tab 2" codelang="go" >}}
println "This is tab 2."
{{< /tab >}}}
{{< /tabs >}}

Renders to:


echo "This is tab 1."


println "This is tab 2."

Tabs demo: Inline Markdown and HTML

{{< tabs name="tab_with_md" >}}
{{% tab name="Markdown" %}}
This is **some markdown.**
{{< note >}}
It can even contain shortcodes.
{{< /note >}}
{{% /tab %}}
{{< tab name="HTML" >}}
<div>
	<h3>Plain HTML</h3>
	<p>This is some <i>plain</i> HTML.</p>
</div>
{{< /tab >}}
{{< /tabs >}}

Renders to:

This is some markdown.

Plain HTML

This is some plain HTML.

Tabs demo: File include

{{< tabs name="tab_with_file_include" >}}
{{< tab name="Content File #1" include="example1" />}}
{{< tab name="Content File #2" include="example2" />}}
{{< tab name="JSON File" include="podtemplate" />}}
{{< /tabs >}}

Renders to:

This is an example content file inside the includes leaf bundle.

This is another example content file inside the includes leaf bundle.

  {
    "apiVersion": "v1",
    "kind": "PodTemplate",
    "metadata": {
      "name": "nginx"
    },
    "template": {
      "metadata": {
        "labels": {
          "name": "nginx"
        },
        "generateName": "nginx-"
      },
      "spec": {
         "containers": [{
           "name": "nginx",
           "image": "dockerfile/nginx",
           "ports": [{"containerPort": 80}]
         }]
      }
    }
  }

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.

Renders to:

v1.22

{{< 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:

v1.22

{{< latest-semver >}}

The {{< latest-semver >}} shortcode generates the value of latest without the "v" prefix.

Renders to:

1.22

{{< 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:

To check the version, enter kubectl version.

{{< 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:

https://git.k8s.io/kubernetes/CHANGELOG/CHANGELOG-1.22.md

What's next