This repository contains the assets required to build the Kubernetes website and documentation. We're glad that you want to contribute!
You can run the website locally using Hugo (Extended version), or you can run it in a container runtime. We strongly recommend using the container runtime, as it gives deployment consistency with the live website.
To use this repository, you need the following installed locally:
- npm
- Go
- Hugo (Extended version)
- A container runtime, like Docker.
Note
Make sure to install the Hugo extended version specified by the HUGO_VERSION environment variable in the netlify.toml file.
Before you start, install the dependencies. Clone the repository and navigate to the directory:
git clone https://github.com/kubernetes/website.git
cd websiteThe Kubernetes website uses the Docsy Hugo theme, which can be installed via npm. You can also download a pre-configured development container image that includes Hugo and Docsy. Additionally, a Git submodule is used for tools that generate the reference documentation.
# fetch submodule dependencies
git submodule update --init --recursive --depth 1# fetch submodule dependencies
make module-initTo build the site in a container, run the following:
# You can set $CONTAINER_ENGINE to the name of any Docker-like container tool
# Render the full website
make container-serve
# Render only a specific language segment (e.g., English)
make container-serve segments=en
# Render multiple languages (e.g., English and Korean)
make container-serve segments=en,ko💡 Tip: Using Hugo segments speeds up local preview builds, by rendering only selected language(s).
If you see errors, it probably means that the Hugo container did not have enough computing resources available. To solve it, increase the amount of allowed CPU and memory usage for Docker on your machine (macOS and Windows).
Open up your browser to http://localhost:1313 to view the website. As you make changes to the source files, Hugo updates the website and forces a browser refresh.
To install dependencies, deploy and test the site locally, run:
-
For macOS and Linux
npm ci # Render the full site (default) make serve # Render only a specific language segment make serve segments=en # Render multiple language segments make serve segments=en,ko
💡 Tip: Hugo segments are defined in hugo.toml and allow faster rendering by limiting the scope to specific language(s).
-
For Windows (PowerShell)
npm ci hugo.exe server --buildFuture --environment development
This will start the local Hugo server on port 1313. Open up your browser to http://localhost:1313 to view the website. As you make changes to the source files, Hugo updates the website and forces a browser refresh.
The API reference pages located in content/en/docs/reference/kubernetes-api are built from the Swagger specification, also known as OpenAPI specification, using https://github.com/kubernetes-sigs/reference-docs/tree/master/gen-resourcesdocs.
To update the reference pages for a new Kubernetes release follow these steps:
-
Pull in the
api-ref-generatorsubmodule:git submodule update --init --recursive --depth 1
-
Update the Swagger specification:
curl 'https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json' > api-ref-assets/api/swagger.json
-
In
api-ref-assets/config/, adapt the filestoc.yamlandfields.yamlto reflect the changes of the new release. -
Next, build the pages:
make api-reference
You can test the results locally by building and serving the site from a container:
make container-serve
In a web browser, go to http://localhost:1313/docs/reference/kubernetes-api/ to view the API reference.
-
When all changes of the new contract are reflected into the configuration files
toc.yamlandfields.yaml, create a Pull Request with the newly generated API reference pages.
error: failed to transform resource: TOCSS: failed to transform "scss/main.scss" (text/x-scss): this feature is not available in your current Hugo version
Hugo is shipped in two set of binaries for technical reasons. The current website runs based on the Hugo Extended version only. In the release page look for archives with extended in the name. To confirm, run hugo version and look for the word extended.
If you run make serve on macOS and receive the following error:
ERROR 2020/08/01 19:09:18 Error: listen tcp 127.0.0.1:1313: socket: too many open files
make: *** [serve] Error 1Try checking the current limit for open files:
launchctl limit maxfiles
Then run the following commands (adapted from https://gist.github.com/tombigel/d503800a282fcadbee14b537735d202c):
< 994B div class="highlight highlight-source-shell notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="#!/bin/sh # These are the original gist links, linking to my gists now. # curl -O https://gist.githubusercontent.com/a2ikm/761c2ab02b7b3935679e55af5d81786a/raw/ab644cb92f216c019a2f032bbf25e258b01d87f9/limit.maxfiles.plist # curl -O https://gist.githubusercontent.com/a2ikm/761c2ab02b7b3935679e55af5d81786a/raw/ab644cb92f216c019a2f032bbf25e258b01d87f9/limit.maxproc.plist curl -O https://gist.githubusercontent.com/tombigel/d503800a282fcadbee14b537735d202c/raw/ed73cacf82906fdde59976a0c8248cce8b44f906/limit.maxfiles.plist curl -O https://gist.githubusercontent.com/tombigel/d503800a282fcadbee14b537735d202c/raw/ed73cacf82906fdde59976a0c8248cce8b44f906/limit.maxproc.plist sudo mv limit.maxfiles.plist /Library/LaunchDaemons sudo mv limit.maxproc.plist /Library/LaunchDaemons sudo chown root:wheel /Library/LaunchDaemons/limit.maxfiles.plist sudo chown root:wheel /Library/LaunchDaemons/limit.maxproc.plist sudo launchctl load -w /Library/LaunchDaemons/limit.maxfiles.plist">#!/bin/sh # These are the original gist links, linking to my gists now. # curl -O https://gist.githubusercontent.com/a2ikm/761c2ab02b7b3935679e55af5d81786a/raw/ab644cb92f216c019a2f032bbf25e258b01d87f9/limit.maxfiles.plist # curl -O https://gist.githubusercontent.com/a2ikm/761c2ab02b7b3935679e55af5d81786a/raw/ab644cb92f216c019a2f032bbf25e258b01d87f9/limit.maxproc.plist curl -O https://gist.githubusercontent.com/tombigel/d503800a282fcadbee14b537735d202c/raw/ed73cacf82906fdde59976a0c8248cce8b44f906/limit.maxfiles.plist curl -O https://gist.githubusercontent.com/tombigel/d503800a282fcadbee14b537735d202c/raw/ed73cacf82906fdde59976a0c8248cce8b44f906/limit.maxproc.plist sudo mv limit.maxfiles.plist /Library/LaunchDaemons sudo mv limit.maxproc.plist /Library/LaunchDaemons sudo chown root:wheel /Library/LaunchDaemons/limit.maxfiles.plist sudo chown root:wheel /Library/LaunchDaemons/limit.maxproc.plist sudo launchctl load -w /Library/LaunchDaemons/limit.maxfiles.plist