# Documentation Style Guide

Documentation Style GuideThis 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.Note:Kubernetes documentation uses Goldmark Markdown Renderer with some adjustments along with a few Hugo Shortcodes to support glossary entries, tabs, and representing feature state.LanguageKubernetes 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 standardsUse upper camel case for API objectsWhen 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.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 objectsDoDon'tThe 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 placeholdersUse 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 elementsDo and Don't - Bold interface elementsDoDon'tClick Fork.Click "Fork".Select Other.Select "Other".Use italics to define or introduce new termsDo and Don't - Use italics for new termsDoDon'tA 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 pathsDo and Don't - Use code style for filenames, directories, and pathsDoDon'tOpen 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 quotesDo and Don't - Use the international standard for punctuation inside quotesDoDon'tevents 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 formattingUse code style for inline code, commandsFor inline code in an HTML document, use the <code> tag. In a Markdown document, use the backtick (`). However, API kinds such as StatefulSet or ConfigMap are written verbatim (no backticks); this allows using possessive apostrophes.Do and Don't - Use code style for inline code, commands, and API objectsDoDon'tThe 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 PersistentVolume represents durable storage…The CustomResourceDefinition's .spec.group field…The CustomResourceDefinition.spec.group field…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.Note:The website supports syntax highlighting for code samples, but specifying a language is optional. Syntax highlighting in the code block should conform to the contrast guidelines.Use code style for object field names and namespacesDo and Don't - Use code style for object field namesDoDon'tSet 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 namesDo and Don't - Use code style for Kubernetes command tool and component namesDoDon'tThe 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 nameDo and Don't - Starting a sentence with a component tool or component nameDoDon'tThe 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 nameDo and Don't - Use a general descriptor over a component nameDoDon'tThe 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 valuesFor 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 valuesDoDon'tSet 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.However, consider quoting values where there is a risk that readers might confuse the value with an API kind.Referring to Kubernetes API resourcesThis section talks about how we reference API resources in the documentation.Clarification about "resource"Kubernetes uses the word resource to refer to API resources. For example, the URL path /apis/apps/v1/namespaces/default/deployments/my-app represents a Deployment named "my-app" in the "default" namespace. In HTTP jargon, namespace is a resource - the same way that all web URLs identify a resource.Kubernetes documentation also uses "resource" to talk about CPU and memory requests and limits. It's very often a good idea to refer to API resources as "API resources"; that helps to avoid confusion with CPU and memory resources, or with other kinds of resource.If you are using the lowercase plural form of a resource name, such as deployments or configmaps, provide extra written context to help readers understand what you mean. If you are using the term in a context where the UpperCamelCase name could work too, and there is a risk of ambiguity, consider using the API kind in UpperCamelCase.When to use Kubernetes API terminologiesThe different Kubernetes API terminologies are:API kinds: the name used in the API URL (such as pods, namespaces). API kinds are sometimes also called resource types.API resource: a single instance of an API kind (such as pod, secret).Object: a resource that serves as a "record of intent". An object is a desired state for a specific part of your cluster, which the Kubernetes control plane tries to maintain. All objects in the Kubernetes API are also resources.For clarity, you can add "resource" or "object" when referring to an API resource in Kubernetes documentation. An example: write "a Secret object" instead of "a Secret". If it is clear just from the capitalization, you don't need to add the extra word.Consider rephrasing when that change helps avoid misunderstandings. A common situation is when you want to start a sentence with an API kind, such as “Secret”; because English and other languages capitalize at the start of sentences, readers cannot tell whether you mean the API kind or the general concept. Rewording can help.API resource namesAlways format API resource names using UpperCamelCase, also known as PascalCase. Do not write API kinds with code formatting.Don't split an API object name into separate words. For example, use PodTemplateList, not Pod Template List.For more information about PascalCase and code formatting, review the related guidance on Use upper camel case for API objects and Use code style for inline code, commands, and API objects.For more information about Kubernetes API terminologies, review the related guidance on Kubernetes API terminology.Code snippet formattingDon't include the command promptDo and Don't - Don't include the command promptDoDon'tkubectl get pods$ kubectl get podsSeparate commands from outputVerify 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 examplesCode 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 ... Formulae and equationsYou can use the Docsy support for diagrams and formulae.For example: \\(\frac{7}{9} \sqrt{K^8 s}\\), which renders as \(\frac{7}{9} \sqrt{K^8 s}\).Prefer inline formulae where reasonable, but you can use a math block if that's likely to help readers.Read the Docsy guide to find out what you need to change in your page to activate support; if you have problems, add math: true to the page front matter (you can do this even if you think the automatic activation should be enough).Kubernetes.io word listA list of Kubernetes-specific terms and words to be used consistently across the site.Kubernetes.io word listTermUsageKubernetesKubernetes should always be capitalized.DockerDocker should always be capitalized.SIG DocsSIG Docs rather than SIG-DOCS or other variations.On-premisesOn-premises or On-prem rather than On-premise or other variations.cloud nativeCloud native or cloud native as appropriate for sentence structure rather than cloud-native or Cloud Native.open sourceOpen source or open source as appropriate for sentence structure rather than open-source or Open Source.ShortcodesHugo Shortcodes help create different rhetorical appeal levels. Our documentation supports three different shortcodes in this category: Note {{< note >}}, Caution {{< caution >}}, and Warning {{< warning >}}.Surround the text with an opening and closing shortcode.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:The prefix you choose is the same text for the tag.NoteUse {{< 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:Note:You can still use Markdown inside these callouts.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:Use the note shortcode in a listA second item with an embedded noteNote:Warning, Caution, and Note shortcodes, embedded in lists, need to be indented four spaces. See [Common Shortcode Issues](#common-shortcode-issues). A third item in a listA fourth item in a listCautionUse {{< 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:Caution:The callout style only applies to the line directly above the tag.WarningUse {{< warning >}} to indicate danger or a piece of information that is crucial to follow.For example:{{< warning >}} Beware. {{< /warning >}} The output is:Warning:Beware.Common Shortcode IssuesOrdered ListsShortcodes 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:Preheat oven to 350˚FPrepare the batter, and pour into springform pan.Note:Grease the pan for best results.Bake for 20-25 minutes or until set.Include StatementsShortcodes 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 elementsLine breaksUse 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.Manually wrap paragraphs in the Markdown source when appropriate. Since the git tool and the GitHub website generate file diffs on a line-by-line basis, manually wrapping long lines helps the reviewers to easily find out the changes made in a PR and provide