Reference Documentation Quickstart

    • You need a machine that is running Linux or macOS.

    • You need to have these tools installed:

    • Your PATH environment variable must include the required build tools, such as the Go binary and python.

    Getting the docs repository

    Make sure your website fork is up-to-date with the kubernetes/website remote on GitHub (main branch), and clone your website fork.

    Determine the base directory of your clone. For example, if you followed the preceding step to get the repository, your base directory is github.com/website. The remaining steps refer to your base directory as <web-base>.

    Note: If you want to change the content of the component tools and API reference, see the .

    Overview of update-imported-docs

    The update-imported-docs.py script is located in the <web-base>/update-imported-docs/ directory.

    The script builds the following references:

    • Component and tool reference pages
    • The kubectl command reference
    • The Kubernetes API reference
    • K8S_RELEASE
    • K8S_ROOT
    • K8S_WEBROOT

    The script requires two arguments to run successfully:

    • A YAML configuration file (reference.yml)
    • A release version, for example:1.17

    The configuration file contains a generate-command field. The generate-command field defines a series of build instructions from kubernetes-sigs/reference-docs/Makefile. The K8S_RELEASE variable determines the version of the release.

    The update-imported-docs.py script performs the following steps:

    1. Clones the related repositories specified in a configuration file. For the purpose of generating reference docs, the repository that is cloned by default is kubernetes-sigs/reference-docs.
    2. Runs commands under the cloned repositories to prepare the docs generator and then generates the HTML and Markdown files.
    3. Copies the generated HTML and Markdown files to a local clone of the <web-base> repository under locations specified in the configuration file.
    4. Updates command links from kubectl.md to the refer to the sections in the kubectl command reference.

    When the generated files are in your local clone of the <web-base> repository, you can submit them in a to <web-base>.

    Each configuration file may contain multiple repos that will be imported together. When necessary, you can customize the configuration file by manually editing it. You may create new config files for importing other groups of documents. The following is an example of the YAML configuration file:

    1. repos:
    2. - name: community
    3.   remote: https://github.com/kubernetes/community.git
    4.   branch: master
    5.   files:
    6.   - src: contributors/devel/README.md
    7.     dst: docs/imported/community/devel.md
    8.   - src: contributors/guide/README.md
    9.     dst: docs/imported/community/guide.md

    Single page Markdown documents, imported by the tool, must adhere to the .

    Customizing reference.yml

    Open <web-base>/update-imported-docs/reference.yml for editing. Do not change the content for the generate-command field unless you understand how the command is used to build the references. You should not need to update reference.yml. At times, changes in the upstream source code, may require changes to the configuration file (for example: golang version dependencies and third-party library changes). If you encounter build issues, contact the SIG-Docs team on the .

    Note: The generate-command is an optional entry, which can be used to run a given command or a short script to generate the docs from within a repository.

    In reference.yml, files contains a list of src and dst fields. The src field contains the location of a generated Markdown file in the cloned kubernetes-sigs/reference-docs build directory, and the dst field specifies where to copy this file in the cloned kubernetes/website repository. For example:

    1. repos:
    2. - name: reference-docs
    3.   remote: https://github.com/kubernetes-sigs/reference-docs.git
    4.   files:
    6.   ...

    Running the update-imported-docs tool

    You can run the update-imported-docs.py tool as follows:

    1. cd <web-base>/update-imported-docs
    2. ./update-imported-docs.py <configuration-file.yml> <release-version>

    For example:

    1. ./update-imported-docs.py reference.yml 1.17

    The release.yml configuration file contains instructions to fix relative links. To fix relative links within your imported files, set thegen-absolute-links property to true. You can find an example of this in release.yml.

    Adding and committing changes in kubernetes/website

    List the files that were generated and copied to <web-base>:

    The output shows the new and modified files. The generated output varies depending upon changes made to the upstream source code.

    1. content/en/docs/reference/command-line-tools-reference/cloud-controller-manager.md
    2. content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
    3. content/en/docs/reference/command-line-tools-reference/kube-controller-manager.md
    4. content/en/docs/reference/command-line-tools-reference/kube-proxy.md
    5. content/en/docs/reference/command-line-tools-reference/kube-scheduler.md
    6. content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm.md
    7. content/en/docs/reference/kubectl/kubectl.md
    1. static/docs/reference/generated/kubectl/kubectl-commands.html
    2. static/docs/reference/generated/kubectl/navData.js
    3. static/docs/reference/generated/kubectl/scroll.js
    4. static/docs/reference/generated/kubectl/stylesheet.css
    5. static/docs/reference/generated/kubectl/tabvisibility.js
    6. static/docs/reference/generated/kubectl/node_modules/bootstrap/dist/css/bootstrap.min.css
    7. static/docs/reference/generated/kubectl/node_modules/highlight.js/styles/default.css
    8. static/docs/reference/generated/kubectl/node_modules/jquery.scrollto/jquery.scrollTo.min.js
    9. static/docs/reference/generated/kubectl/node_modules/jquery/dist/jquery.min.js
    10. static/docs/reference/generated/kubectl/css/font-awesome.min.css

    Run git add and git commit to commit the files.

    Creating a pull request

    Create a pull request to the repository. Monitor your pull request, and respond to review comments as needed. Continue to monitor your pull request until it is merged.

    A few minutes after your pull request is merged, your updated reference topics will be visible in the published documentation.

    To generate the individual reference documentation by manually setting up the required build repositories and running the build targets, see the following guides: