If you want to get started contributing to the Kubernetes documentation, this page and its linked topics can help you get started. You don’t need to be a developer or a technical writer to make a big impact on the Kubernetes documentation and user experience! All you need for the topics on this page is a Github account and a web browser.
If you’re looking for information on how to start contributing to Kubernetes code repositories, refer to the Kubernetes community guidelines.
The Kubernetes documentation is written in Markdown and processed and deployed
using Hugo. The source is in Github at
Most of the documentation source is stored in
/content/en/docs/. Some of the
reference documentation is automatically generated from scripts, mostly in the
You can file issues, edit content, and review changes from others, all from the Github website. You can also use Github’s embedded history and search tools.
The Kubernetes documentation is maintained by a special interest group (SIG) called Sig Docs. We communicate using a Slack channel, a mailing list, and weekly video meetings. New participants are welcome. For more information, see Participating in SIG Docs.
We maintain a style guide with information about choices the SIG Docs community has made about grammar, syntax, source formatting, and typographic conventions. Look over the style guide before you make your first contribution, and use it when you have questions.
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. See the advanced contribution topic for more information.
We use page templates to control the presentation of our documentation pages. Be sure to understand how these templates work by reviewing Using page templates.
The Kubernetes documentation is transformed from Markdown to HTML using Hugo. We make use of the standard Hugo shortcodes, as well as a few that are custom to the Kubernetes documentation. See Custom Hugo shortcodes for information about how to use them.
Anyone with a Github account can file an issue (bug report) against the Kubernetes documentation. If you see something wrong, even if you have no idea how to fix it, file an issue. The exception to this rule is a tiny bug like a typo that you intend to fix yourself. In that case, you can instead fix it without filing a bug first.
On an existing page
If you see a problem in an existing page in the Kubernetes docs, go to the bottom of the page and click the Create an Issue button. If you are not currently logged in to Github, log in. A Github issue form appears with some pre-populated content.
Using Markdown, fill in as many details as you can. In places where you see
empty square brackets (
[ ]), put an
x between the set of brackets that
represents the appropriate choice. If you have a proposed solution to fix
the issue, add it.
Request a new page
If you think content should exist, but you aren’t sure where it should go or you don’t think it fits within the pages that currently exist, you can still file an issue. You can either choose an existing page near where you think the new content should go and file the issue from that page, or go straight to https://github.com/kubernetes/website/issues/new/ and file the issue from there.
To ensure that we understand your issue and can act on it, keep these guidelines in mind:
Limit the scope of a given issue to a reasonable unit of work. For problems with a large scope, break them down into smaller issues.
For instance, “Fix the security docs” is not an actionable issue, but “Add details to the ‘Restricting network access’ topic” might be.
If the issue relates to another issue or pull request, you can refer to it
either by its full URL or by the the issue or pull request number prefixed
# character. For instance,
Introduced by #987654.
Be respectful and avoid venting. For instance, “The docs about X suck” is not helpful or actionable feedback. The Code of Conduct also applies to interactions on Kubernetes Github repositories.
The SIG Docs team communicates using the following mechanisms:
#sig-docschannel, where we discuss docs issues in real-time. Be sure to introduce yourself!
kubernetes-sig-docsmailing list, where broader discussions take place and official decisions are recorded.
To improve existing content, you file a pull request (PR) after creating a fork. Those two terms are specific to Github. For the purposes of this topic, you don’t need to know everything about them, because you can do everything using your web browser. When you continue to the intermediate docs contributor guide, you will need more background in Git terminology.
Kubnetes code developers: If you are documenting a new feature for an upcoming Kubernetes release, your process is a bit different. See Document a feature for process guidelines and information about deadlines.
If you see something you want to fix right away, just follow the instructions below. You don’t need to file an issue (although you certainly can).
If you want to start by finding an existing issue to work on, go to
and look for issues with the label
good first issue (you can use
this shortcut). Read through the comments and make sure there is not an open pull
request against the issue and that nobody has left a comment saying they are
working on the issue recently (3 days is a good rule). Leave a comment saying
that you would like to work on the issue.
The most important aspect of submitting pull requests is choosing which branch to base your work on. Use these guidelines to make the decision:
masterfor fixing problems in content that is already published, or making improvements to content that already exists.
release-1.12) to document upcoming features or changes for an upcoming release that is not yet published.
If you’re still not sure which branch to choose, ask in
#sig-docs on Slack or
attend a weekly SIG Docs meeting to get clarity.
Follow these steps to submit a pull request to improve the Kubernetes documentation.
Click the first blue button, which has the text Edit
If you have never created a fork of the Kubernetes documentation
repository, you are prompted to do so. Create the fork under your Github
username, rather than another organization you may be a member of. The
fork usually has a URL such as
unless you already have a repository with a conflicting name.
The reason you are prompted to create a fork is that you do not have access to push a branch directly to the definitive Kubernetes repository.
The Github Markdown editor appears with the source Markdown file loaded. Make your changes. Below the editor, fill in the Propose file change form. The first field is the summary of your commit message and should be no more than 50 characters long. The second field is optional, but can include more detail if appropriate.
Note: Do not include references to other Github issues or pull requests in your commit message. You can add those to the pull request description later.
Click Propose file change. The change is saved as a commit in a
new branch in your fork, which is automatically named something like
The next screen summarizes the changes you made, by comparing your new
branch (the head fork and compare selection boxes) to the current
state of the base fork and base branch (
master on the
kubernetes/website repository by default). You can change any of the
selection boxes, but don’t do that now. Have a look at the difference
viewer on the bottom of the screen, and if everything looks right, click
Create pull request.
Note: If you don’t want to create the pull request now, you can do it later, by browsing to the main URL of the Kubernetes website repository or your fork’s repository. The Github website will prompt you to create the pull request if it detects that you pushed a new branch to your fork.
The Open a pull request screen appears. The subject of the pull request is the same as the commit summary, but you can change it if needed. The body is populated by your extended commit message (if present) and some template text. Read the template text and fill out the details it asks for, then delete the extra template text. Leave the Allow edits from maintainers checkbox selected. Click Create pull request.
Congratulations! Your pull request is available in Pull requests](https://github.com/kubernetes/website/pulls).
After a few minutes, you can preview the website with your PR’s changes
applied. Go to the Conversation tab of your PR and click the Details
link for the
deploy/netlify test, near the bottom of the page. It opens in
the same browser window by default.
Wait for review. Generally, reviewers are suggested by the
If a reviewer asks you to make changes, you can go to the Files changed
tab and click the pencil icon on any files that have been changed by the
pull request. When you save the changed file, a new commit is created in
the branch being monitored by the pull request.
If your change is accepted, a reviewer merges your pull request, and the change is live on the Kubernetes website a few minutes later.
This is only one way to submit a pull request. If you are already a Git and Github advanced user, you can use a local GUI or command-line Git client instead of using the Github UI. Some basics about using the command-line Git client are discussed in the intermediate docs contribution guide.
People who are not yet approvers or reviewers can still review pull requests. The reviews are not considered “binding”, which means that your review alone won’t cause a pull request to be merged. However, it can still be helpful. Even if you don’t leave any review comments, you can get a sense of pull request conventions and etiquette and get used to the workflow.
Go to https://github.com/kubernetes/website/pulls. You see a list of every open pull request against the Kubernetes website and docs.
By default, the only filter that is applied is
open, so you don’t see
pull requests that have already been closed or merged. It’s a good idea to
cncf-cla: yes filter, and for your first review, it’s a good
idea to add
size label is applied automatically
based on how many lines of code the PR modifies. You can apply filters using
the selection boxes at the top of the page, or use
this shortcut for only small PRs. All filters are
ANDed together, so
you can’t search for both
size/S in the same query.
Go to the Files changed tab. Look through the changes introduced in the
PR, and if applicable, also look at any linked issues. If you see a problem
or room for improvement, hover over the line and click the
+ symbol that
You can type a comment, and either choose Add single comment or Start a review. Typically, starting a review is better because it allows you to leave multiple comments and notifies the PR owner only when you have completed the review, rather than a separate notification for each comment.
When finished, click Review changes at the top of the page. You can summarize your review, and you can choose to comment, approve, or request changes. New contributors should always choose Comment.
Thanks for reviewing a pull request! When you are new to the project, it’s a
good idea to ask for feedback on your pull request reviews. The
Slack channel is a great place to do this.
Anyone can write a blog post and submit it for review. Blog posts should not be commercial in nature and should consist of content that will apply broadly to the Kubernetes community.
To submit a blog post, you can either submit it using the Kubernetes blog submission form, or follow the steps below.
Case studies highlight how organizations are using Kubernetes to solve real-world problems. They are written in collaboration with the Kubernetes marketing team, which is handled by the CNCF.
When you are comfortable with all of the tasks discussed in this topic and you want to engage with the Kubernetes docs team in deeper ways, read the intermediate docs contribution guide.