Writing a new topic

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

    Choosing a page type

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

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

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

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

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

    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/

    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 will come before one with weight 20.

    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 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 a RoleBinding, 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:

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

    Note: To show raw Hugo shortcodes as in the above example and prevent Hugo from interpreting them, use C-style comments directly after the < and before the > characters. View the code for this page for an example.

    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:

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

    Note: When adding new YAML files to the <LANG>/examples directory, make sure the file is also included into the file. The Travis CI for the Website automatically runs this test case when PRs are submitted to ensure all examples pass the tests.

    For an example of a topic that uses this technique, see .

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

    What’s next