kubernetes/website: what the Kubernetes docs repo actually is, and how to build it locally

What kubernetes/website is for, and who should clone it

This repository contains the assets required to build the Kubernetes website and documentation at kubernetes.io. That sentence from the README defines the audience narrowly. If you maintain a product site, a blog, or a docs portal for something else, this is not a starter kit; it is the source of truth for one specific site. The people who clone it are documentation contributors, localization teams working in the content directories, and engineers who need to regenerate the API reference pages after a Kubernetes release. The repository is licensed CC-BY-4.0, which is a content licence rather than a code licence, and that distinction matters for anyone thinking about reuse. The top level mixes prose, layouts, i18n bundles, a Go module, and a generator submodule, so it behaves like a docs platform rather than a static site. The README also points contributors at SIG Docs for meetings, Slack and the mailing list, which tells you the project expects review by a group, not a solo merge.

How the site is assembled: Hugo, Docsy, segments and a submodule

The rendering engine is Hugo in its extended version, which is required because the site uses SCSS pipelines. The theme is Docsy, declared in package.json as a GitHub dependency pinned to semver 0.11.0, alongside postcss-cli, autoprefixer and rtlcss for right-to-left locales. A Go module named k8s.io/website pulls in k8s.io/apimachinery and k8s.io/kubernetes, which is how reference material and Kubernetes types reach the build. A Git submodule supplies the tools that generate reference documentation, and the README is explicit that it must be initialized before the site is complete. The Makefile derives the Hugo version by grepping netlify.toml, so the version used locally, in the container image, and on the deployment target all come from one line in that file. Rendering is segmented by language: the segments variable defaults to all, and hugo.toml defines the segments, so make serve segments=en renders English only and make serve segments=en,ko renders English and Korean. On a full checkout that segment flag is the difference between a preview that comes up quickly and one that spends its time on locales you are not editing.

Install and first run: container path versus local Hugo

Prerequisites listed in the README are npm, Go, Hugo Extended, and a container runtime such as Docker. The README recommends the container runtime because it gives deployment consistency with the live website, and the Makefile honours that by defaulting CONTAINER_ENGINE to docker while allowing an override, for example CONTAINER_ENGINE=podman make container-image. Start by cloning and entering the directory.

git clone https://github.com/kubernetes/website.git
cd website

On Linux and other Unix systems, fetch the submodule dependencies through the Make target rather than by hand.

make module-init

On Windows the README gives the equivalent as a PowerShell command, git submodule update --init --recursive --depth 1. Then build and serve in the container. The segments argument keeps the preview limited to the languages you care about.

make container-serve segments=en

Open http://localhost:1313 in a browser. As you edit source files, Hugo rebuilds and forces a browser refresh. The README notes that errors during this step usually mean the Hugo container did not get enough CPU or memory, and points to the Docker desktop settings pages for macOS and Windows as the fix. If you prefer to run Hugo directly, install the Node dependencies first.

npm ci
make serve segments=en

On Windows the equivalent is hugo.exe server --config hugo.toml,hugo.server.toml --buildFuture --environment development, which also serves on port 1313.

Regenerating the API reference is a separate, manual pipeline

The pages under content/en/docs/reference/kubernetes-api are not hand-written. They are generated from the Swagger, or OpenAPI, specification using the gen-resourcesdocs tool from kubernetes-sigs/reference-docs, pulled in as the api-ref-generator submodule. Updating them for a new release is a five-step sequence in the README. You initialize the submodule, fetch a fresh specification, adapt two configuration files, build, and then open a pull request with the generated pages.

git submodule update --init --recursive --depth 1
curl 'https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json' > api-ref-assets/api/swagger.json
make api-reference

The configuration files are api-ref-assets/config/toc.yaml and api-ref-assets/config/fields.yaml, and the README states they must be adapted to reflect the changes of the new release before the pages are built. That is the part no command automates. The table of contents and the field descriptions are editorial decisions, so a release bump is a review task as much as a build task. You can verify the result at http://localhost:1313/docs/reference/kubernetes-api/ after make container-serve. The release history shows snapshot tags for 1.37, 1.36 and 1.35, which gives a rough sense of how often this pipeline is exercised.

Where this repository is the wrong tool

The clearest limitation is scope. Nothing here is designed to be lifted into another project. The layouts, the i18n bundles, the Docsy pin, and the api-ref-assets configuration all assume Kubernetes documentation, and the README never presents the repository as a template. The second limitation is weight. A working local build needs npm, Go, Hugo Extended and a container runtime, and the README warns that under-resourced containers fail during the build rather than degrading gracefully. On a laptop with limited Docker memory, the container path that the README recommends may be the one that breaks first. The third limitation is that the reference pipeline depends on a moving external input: the curl command fetches swagger.json from the master branch of kubernetes/kubernetes, so the generated output tracks that source rather than a pinned tag. Anyone expecting a reproducible API reference build from a fixed input will not find one documented here. Finally, the README does not document rollback for a bad generation run, so recovering from a mistaken regeneration means reverting the generated files in Git yourself.

How it differs from a plain Hugo site or a docs platform

A conventional Hugo site is a theme plus content, and you choose a version of each. Here the theme is a GitHub dependency pinned in package.json, the Hugo version is read out of netlify.toml by the Makefile, and the container image is tagged with a hash of the Dockerfile, Makefile, netlify.toml, .dockerignore, cloudbuild.yaml, package.json and package-lock.json. That hash-based image tag is the real difference from a generic Hugo setup: the build environment is versioned as a unit, so the same inputs produce the same image name. A hosted docs platform takes the opposite approach, managing rendering and dependencies for you and leaving you with an editor and a URL. This repository sits between the two. You get the control of a self-hosted Hugo build, at the cost of maintaining the toolchain, and you get none of the convenience of a managed editor. If your team has no one who wants to own a Makefile, a Go module and a submodule, a hosted docs product will cost less over a year, even though it gives you less control over the generated API pages.

Maintenance, licensing and what a fork costs

The repository is not archived, and the last push was on 2026-09-21, so it is being worked on. That is a statement about activity, not about the stability of any interface you might build against. The maintenance cost for a contributor is mostly review latency: the README states that a Kubernetes reviewer takes responsibility for feedback, that more than one reviewer may comment, and that a reviewer may request a technical review from a Kubernetes tech reviewer, with response times varying by circumstance. The maintenance cost for a fork is heavier, because you inherit the submodule, the Go module and the netlify.toml version pin. On licensing, the repository is CC-BY-4.0, which is a content licence suited to documentation rather than a software licence suited to code; if you intend to reuse layouts, scripts or the Dockerfile, check whether that licence covers your intended use with your own legal counsel, since nothing in the README addresses reuse outside the project. The Go module dependencies listed in go.mod carry their own licences, and those are separate from the repository licence.

Editorial conclusion

Adopt kubernetes/website if you are contributing documentation, localization, or API reference pages to kubernetes.io; the container path via make container-serve is the one the README recommends for deployment consistency. Do not adopt it as a starting point for a general website or a Hugo theme you plan to reuse, because the layouts, i18n and reference-generation tooling are specific to Kubernetes docs. Before your first pull request, verify the Hugo version pinned in netlify.toml, run make module-init so the reference-docs submodule is present, and read the troubleshooting page the README points to when the container build fails.

Frequently asked questions

Official sources

1. kubernetes/website on GitHub
2. License: CC-BY-4.0
3. Project website
4. README
5. Releases