knative/docs: What the Documentation Repository Actually Contains

What knative/docs is, and the problem it solves

Knative is a set of components for running serverless workloads on Kubernetes, and its documentation spans several releases at once. Someone has to keep those pages consistent, review them, and publish them. This repository is that place. The README opens by calling itself "the source file repository for our documentation on https://knative.dev", which is the cleanest statement of scope available: the artifact here is text and sample code, not a binary or a controller.

The audience follows from that. A contributor fixing a broken command in a tutorial, a technical writer restructuring a concept page, a reviewer checking a code sample against a release: these are the people the repository is built for. The README points contributors at the /docs directory and at the pencil icon on each website page, and it links a docs contributor guide, four content templates (concept, procedure, troubleshooting, blog), and a #knative-documentation channel on the CNCF Slack. That is a documentation project with a documentation process, and it behaves accordingly.

The mismatch to flag early: search traffic around Knative is dominated by people who want to install or run it. This repository will not do that. If you arrived expecting manifests, you want the component repositories instead.

How the site is assembled from Markdown and samples

The published site is generated by Material for MkDocs. The README says so directly, and the repository layout confirms it: mkdocs.yml sits at the top level alongside a requirements.txt that pins the plugin set, an overrides/ directory for theme customisation, and netlify.toml for the hosting build. The docs themselves live under docs/, and the README notes that source files for the website are located within that directory.

The toolchain is more elaborate than a plain MkDocs site. requirements.txt lists mkdocs-material below version 10.0, plus mkdocs-exclude, mkdocs-macros-plugin, mkdocs-awesome-nav, mkdocs-git-revision-date-localized-plugin, mkdocs-redirects, mkdocs-rss-plugin, pygithub pinned at 1.55, and semver at 2.13.0. Each of those names implies a build behaviour: redirects for moved pages, revision dates pulled from git history, an RSS feed, and macros for generated content. Version history is a first-class concern here, which matches the release-branch model.

There is a second toolchain. go.mod declares module github.com/knative/docs on Go 1.24.0 and pulls in google/go-github/v32, gopkg.in/yaml.v2, and knative.dev/hack. That is the automation around the docs (link checking, release bookkeeping, repository scripting) rather than anything the reader of the website touches. Two dependency trees in one repository is a real maintenance surface, and it is worth knowing before you volunteer to update something.

Previewing the docs locally and making a first edit

The README does not inline the local preview commands. It defers to contribute-to-docs/getting-started/previewing-docs-locally.md, which is where the actual steps live. What the repository does give you is the dependency list the environment has to satisfy, so a Python environment built from requirements.txt is the starting point the layout implies.

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

That installs Material for MkDocs and the plugin set listed in the file. Expect a large dependency resolution because mkdocs-material, pygithub and the plugin packages all pull their own trees; the pinned pygithub==1.55 and semver==2.13.0 are old enough that a newer Python may complain, so check the contributor guide if the install fails.

Once the environment is ready, the site configuration is mkdocs.yml at the repository root, and the pages you edit are Markdown files under docs/. The contributor guide referenced from the README is the authority on the serve command and any flags; the README itself does not repeat them.

For content, the repository ships templates you are expected to follow. A new procedure page starts from the procedure template:

ls contribute-to-docs/templates/

That directory contains template-concept.md, template-procedure.md, template-troubleshooting.md and template-blog-entry.md. Using the matching template is the cheapest way to pass review, because the structure is what reviewers check first.

Versioned docs and the branch model you have to respect

This is the part that catches newcomers. The README states that each release of the Knative docs is available on the website starting with 0.3, and that their source files are stored in branches of this repository. doc-releases.md exists at the top level to track that mapping. In practice it means main is not the whole story: a fix intended for an older release may need to land on a release branch rather than main, and a page you see on the website may be generated from a branch you are not currently looking at.

The recent release list in the repository metadata is stale by comparison. The most recent tagged entries are v0.21.x, v0.20.x and v0.19.x, dated February 2021, January 2021 and November 2020. Those tags describe documentation snapshots, not the current state of the site, and anyone treating the release list as a signal of how current the docs are will draw the wrong conclusion. The last push to the default branch was on 2026-09-10, which is the more useful indicator of activity.

So the practical rule: before editing, confirm which branch carries the version of the page you mean to change. The README does not document a rollback procedure for a bad docs merge, and it does not describe how a release branch is cut. If you need that, the contributor guide and the community working group are the places to ask, not this README.

Where knative/docs is the wrong tool

It is not an installation source. Nothing in the repository description, README, or top-level layout provides a Knative Serving or Eventing manifest, a Helm chart, or an operator. The topics list on the repository mentions istio, kubernetes and serverless, but those describe the subject matter of the documentation, not artifacts you can apply. If your task is to get Knative running, this repository is a detour.

It is also not a place to file runtime bugs. The README is explicit that issues can be opened here, and that Create Issue links appear on website pages, but the surrounding text frames those as documentation issues and questions. A controller crash or a routing failure belongs with the component that owns it. Opening it here routes your report to people who write pages.

There is a build fragility worth naming. The dependency list mixes a version-capped mkdocs-material (<10.0) with a set of plugins that each track their own MkDocs compatibility, plus two pinned Python packages from an older era. Any one of those moving can break a local preview even when the content is fine. That is a normal cost of a plugin-heavy docs build, but it means "the site will not build" is often an environment problem rather than a content problem, and the README does not offer a troubleshooting path for it.

Alternatives and how their approach differs

The obvious comparison is the component repositories themselves. knative/serving and knative/eventing carry their own READMEs and, in places, their own reference material. The difference is one of audience and depth: those repositories document an API surface for people operating the software, while knative/docs carries the task-oriented narrative, the tutorials, and the code samples that tie components together. If you need the field-by-field meaning of a resource, the component repository is closer to the source; if you need a walkthrough, this one is.

A second comparison is the generated API reference. Tools that extract documentation from Go source or from CRD schemas produce reference pages mechanically, and they stay in sync because a build regenerates them. knative/docs is hand-written Markdown assembled by MkDocs. That gives writers control over structure and prose, and it costs accuracy: a sample can drift from the code without any build failing. The templates under contribute-to-docs/templates/ are the project's answer to consistency, but they cannot detect a stale command.

Against a generic static-site setup, the difference is the plugin set. Redirects, revision dates, RSS and macros are configured here rather than assembled by each author, which is why requirements.txt is pinned at all. A plain MkDocs site would be simpler to build and would lose versioned history and redirect handling.

Licence and the cost of keeping a docs repository current

The repository metadata reports the licence as NOASSERTION, and the top-level listing contains two licence files: LICENSE and LICENSE-docs. Two files rather than one suggests the documentation content and the surrounding code are licensed differently, which is common for repositories that mix prose with scripts and Go tooling. The metadata alone does not tell you which terms apply to which directory, and the README does not explain the split. Read both files and check the directory you intend to reuse before copying content. That is a description of what the repository contains, not legal advice.

Upgrade cost is concentrated in the Python environment. requirements.txt caps mkdocs-material below 10.0 and pins pygithub==1.55 and semver==2.13.0, so a future Material release will not be picked up without an edit, and the two pinned packages will age. The Go side is lighter: go.mod requires knative.dev/hack at a pseudo-version and two direct libraries, with go.opencensus.io replaced by a specific older version. Neither file is large, but both need attention when the surrounding ecosystem moves.

The content itself is the larger ongoing cost. Every Knative release adds a branch and a set of pages, and the release list in the metadata shows how quickly those snapshots accumulate. Keeping several versions coherent is the work this repository exists to absorb.

Editorial conclusion

Adopt knative/docs if you are contributing documentation, translating pages, or need to preview a change to the site before it merges; the contributor guide is the entry point and the Material for MkDocs setup is the toolchain. Do not adopt it if you want to install Knative on a cluster, because the repository holds prose and samples rather than the serving or eventing components. Before you open a pull request, verify which branch carries the release you are editing, since the README states that each release's source files live in separate branches, and check whether the page you plan to change already exists under a versioned branch.

Frequently asked questions

Official sources

1. Issues
2. knative/docs on GitHub
3. Project website
4. README
5. Releases