projectcapsule · sandert-k8s · Jul 5, 2026 · Jul 6, 2026
diff --git a/.github/workflows/hugo.yaml b/.github/workflows/hugo.yaml
diff --git a/.hugo_build.lock b/.hugo_build.lock
diff --git a/CNAME b/CNAME
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,28 +1,37 @@
-# How to Contribute
+# Contributing to the Capsule Documentation
 
-We'd love to accept your patches and contributions to this project. There are
-just a few small guidelines you need to follow.
+Thank you for contributing to the Capsule documentation!
 
-## Contributor License Agreement
+## How to Contribute
 
-Contributions to this project must be accompanied by a Contributor License
-Agreement. You (or your employer) retain the copyright to your contribution;
-this simply gives us permission to use and redistribute your contributions as
-part of the project. Head over to <https://cla.developers.google.com/> to see
-your current agreements on file or to sign a new one.
+1. Fork this repository and create a branch for your changes.
+2. Edit or add Markdown files under `content/en/`.
+3. Open a pull request, Netlify will automatically post a **deploy preview** link so you can review the rendered site before it is merged.
+4. Once approved and merged, the site is deployed automatically to [projectcapsule.dev](https://projectcapsule.dev) via CNCF Netlify.
 
-You generally only need to submit a CLA once, so if you've already submitted one
-(even if it was for a different project), you probably don't need to do it
-again.
+No local Hugo setup is needed. All rendering and deployment is handled by Netlify.
 
-## Code reviews
+## Content Guidelines
 
-All submissions, including submissions by project members, require review. We
-use GitHub pull requests for this purpose. Consult
-[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
-information on using pull requests.
+- All documentation is authored in Markdown.
+- Follow the existing directory and heading structure under `content/en/docs/`.
+- YAML examples in code blocks should be valid and tested where possible.
+- Keep language clear and concise.
 
-## Community Guidelines
+## API Reference
 
-This project follows
-[Google's Open Source Community Guidelines](https://opensource.google.com/conduct/).
+The files `content/en/docs/reference.md` and `content/en/docs/proxy/reference.md` are **generated** from CRD YAML files, do not edit them by hand. To regenerate:
+
+```bash
+make apidocs
+```
+
+The `diff` CI workflow will fail on your PR if the committed reference docs have drifted from the generated output.
+
+## Code Reviews
+
+All submissions require a pull request and at least one review from a maintainer.
+
+## Community
+
+This project follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md).
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -1,5 +1,11 @@
 # Development
 
+## Deployment
+
+The site is deployed automatically via **CNCF Netlify** on every merge to `main`. No local Hugo server is required to contribute.
+
+Every pull request receives an automatic **Netlify deploy preview** at a unique URL, check the PR status checks for the preview link.
+
 ## Pre-commit Hooks
 
 This repository uses [prek](https://prek.j178.dev/) to run pre-commit hooks locally. `prek` is a fast, Rust-native drop-in replacement for [pre-commit](https://pre-commit.com/).

diff --git a/Dockerfile b/Dockerfile
diff --git a/README.md b/README.md
@@ -1,184 +1,27 @@
-# Docsy Example
+# Capsule Documentation
 
-[Docsy][] is a [Hugo theme module][] for technical documentation sites, providing easy
-site navigation, structure, and more. This **Docsy Example Project** uses the Docsy
-theme component as a hugo module and provides a skeleton documentation structure for you to use.
-You can clone/copy this project and edit it with your own content, or use it as an example.
+This repository contains the documentation for [Capsule](https://github.com/projectcapsule/capsule), the Kubernetes multi-tenancy operator.
 
-In this project, the Docsy theme is pulled in as a Hugo module, together with
-its dependencies:
+The site is published at **[projectcapsule.dev](https://projectcapsule.dev)** and is automatically deployed via [CNCF Netlify](https://www.netlify.com/) on every merge to `main`.
 
-```console
-$ hugo mod graph
-...
-```
-
-For Docsy documentation, see [Docsy user guide][].
-
-This Docsy Example Project is hosted on [Netlify][] at [example.docsy.dev][].
-You can view deploy logs from the [deploy section of the project's Netlify
-dashboard][deploys], or this [alternate dashboard][].
-
-This is not an officially supported Google product. This project is currently maintained.
-
-## Using the Docsy Example Project as a template
-
-A simple way to get started is to use this project as a template, which gives you a site project that is set up and ready to use. To do this:
-
-1. Use the dropdown for switching branches/tags to change to the **latest** released tag.
-
-2. Click **Use this template**.
-
-3. Select a name for your new project and click **Create repository from template**.
-
-4. Make your own local working copy of your new repo using git clone, replacing https://github.com/me/example.git with your repo’s web URL:
-
-```bash
-git clone --depth 1 https://github.com/me/example.git
-```
-
-You can now edit your own versions of the site’s source files.
-
-If you want to do SCSS edits and want to publish these, you need to install `PostCSS`
-
-```bash
-npm install
-```
-
-## Running the website locally
-
-Building and running the site locally requires a recent `extended` version of [Hugo](https://gohugo.io).
-You can find out more about how to install Hugo for your environment in our
-[Getting started](https://www.docsy.dev/docs/getting-started/#prerequisites-and-installation) guide.
-
-Once you've made your working copy of the site repo, from the repo root folder, run:
-
-```bash
-hugo server
-```
-
-## Running a container locally
-
-You can run docsy-example inside a [Docker](https://docs.docker.com/)
-container, the container runs with a volume bound to the `docsy-example`
-folder. This approach doesn't require you to install any dependencies other
-than [Docker Desktop](https://www.docker.com/products/docker-desktop) on
-Windows and Mac, and [Docker Compose](https://docs.docker.com/compose/install/)
-on Linux.
-
-1. Build the docker image
-
-   ```bash
-   docker-compose build
-   ```
-
-1. Run the built image
-
-   ```bash
-   docker-compose up
-   ```
-
-   > NOTE: You can run both commands at once with `docker-compose up --build`.
+## Contributing
 
-1. Verify that the service is working.
+All documentation lives under `content/en/`. Contributions are welcome, open a pull request with your changes.
 
-   Open your web browser and type `http://localhost:1313` in your navigation bar,
-   This opens a local instance of the docsy-example homepage. You can now make
-   changes to the docsy example and those changes will immediately show up in your
-   browser after you save.
+Netlify automatically generates a **deploy preview** for every pull request, so you can review your changes at a live URL before merging. No local Hugo setup is required.
 
-### Cleanup
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines and [DEVELOPMENT.md](DEVELOPMENT.md) for local tooling setup (pre-commit hooks, link checking, API doc generation).
 
-To stop Docker Compose, on your terminal window, press **Ctrl + C**.
+## API Reference
 
-To remove the produced images run:
+The files `content/en/docs/reference.md` and `content/en/docs/proxy/reference.md` are **generated** from CRD YAML files. Do not edit them by hand. To regenerate:
 
 ```bash
-docker-compose rm
-```
-For more information see the [Docker Compose documentation][].
-
-## Using a local Docsy clone
-
-Make sure your installed go version is `1.18` or higher.
-
-Clone the latest version of the docsy theme into the parent folder of your project. The newly created repo should now reside in a sibling folder of your site's root folder.
-
-```shell
-cd root-of-your-site
-git clone --branch v0.7.2 https://github.com/google/docsy.git ../docsy
-```
-
-Now run:
-
-```shell
-HUGO_MODULE_WORKSPACE=docsy.work hugo server --ignoreVendorPaths "**"
-```
-
-or, when using npm, prepend `local` to the script you want to invoke, e.g.:
-
-```shell
-npm run local serve
-```
-
-By using the `HUGO_MODULE_WORKSPACE` directive (either directly or via prefix `local` when using npm), the server now watches all files and directories inside the sibling directory `../docsy` , too. Any changes inside the local `docsy` theme clone are  now immediately picked up (hot reload), you can instantly see the effect of your local edits.
-
-In the command above, we used the environment variable `HUGO_MODULE_WORKSPACE` to tell hugo about the local workspace file `docsy.work`. Alternatively, you can declare the workspace file inside your settings file `hugo.toml`:
-
-```toml
-[module]
-  workspace = "docsy.work"
-```
-
-Your project's `hugo.toml` file already contains these lines, the directive for workspace assignment is commented out, however. Remove the two trailing comment characters '//' so that this line takes effect.
-
-## Troubleshooting
-
-As you run the website locally, you may run into the following error:
-
-```console
-$ hugo server
-WARN 2023/06/27 16:59:06 Module "project" is not compatible with this Hugo version; run "hugo mod graph" for more information.
-Start building sites …
-hugo v0.101.0-466fa43c16709b4483689930a4f9ac8add5c9f66+extended windows/amd64 BuildDate=2022-06-16T07:09:16Z VendorInfo=gohugoio
-Error: Error building site: "C:\Users\foo\path\to\docsy-example\content\en\_index.md:5:1": failed to extract shortcode: template for shortcode "blocks/cover" not found
-Built in 27 ms
-```
-
-This error occurs if you are running an outdated version of Hugo. As of docsy theme version `v0.7.0`, hugo version `0.110.0` or higher is required.
-See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-hugo) of the user guide for instructions on how to install Hugo.
-
-Or you may be confronted with the following error:
-
-```console
-$ hugo server
-
-INFO 2021/01/21 21:07:55 Using config file:
-Building sites … INFO 2021/01/21 21:07:55 syncing static files to /
-Built in 288 ms
-Error: Error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): resource "scss/scss/main.scss_9fadf33d895a46083cdd64396b57ef68" not found in file cache
-```
-
-This error occurs if you have not installed the extended version of Hugo.
-See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-hugo) of the user guide for instructions on how to install Hugo.
-
-Or you may encounter the following error:
-
-```console
-$ hugo server
-
-Error: failed to download modules: binary with name "go" not found
+make apidocs
 ```
 
-This error occurs if you have not installed the `go` programming language on your system.
-See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-go-language) of the user guide for instructions on how to install `go`.
+These files are checked in CI, the `diff` workflow fails if the generated output has drifted from what is committed.
 
+## License
 
-[alternate dashboard]: https://app.netlify.com/sites/goldydocs/deploys
-[deploys]: https://app.netlify.com/sites/docsy-example/deploys
-[Docsy user guide]: https://docsy.dev/docs
-[Docsy]: https://github.com/google/docsy
-[example.docsy.dev]: https://example.docsy.dev
-[Hugo theme module]: https://gohugo.io/hugo-modules/use-modules/#use-a-module-for-a-theme
-[Netlify]: https://netlify.com
-[Docker Compose documentation]: https://docs.docker.com/compose/gettingstarted/
+[Apache 2.0](LICENSE)
diff --git a/config/_default/hugo.yaml b/config/_default/hugo.yaml
@@ -1,5 +1,4 @@
 baseURL: /
-theme: docsy
 title: Capsule
 contentDir: content/en
 defaultContentLanguage: en

diff --git a/content/en/docs/operating/architecture.md b/content/en/docs/operating/architecture.md
@@ -22,7 +22,7 @@ The answer to this question may be influenced by the following aspects:
   * _You’ll need robust monitoring that enables Tenant Owners to clearly understand and manage what’s happening inside their own tenant._
 
 * **Are your customers technically capable of working directly with the Kubernetes API?**
-  * _If not, you may need to build a more user-friendly platform with better UX — for example, a multi-tenant ArgoCD setup, or UI layers like Headlamp._
+  * _If not, you may need to build a more user-friendly platform with better UX. For example, a multi-tenant ArgoCD setup, or UI layers like Headlamp._
 
 ## Personas
 

diff --git a/content/en/docs/operating/best-practices/_index.md b/content/en/docs/operating/best-practices/_index.md
@@ -10,13 +10,13 @@ This is general advice you should consider before making Kubernetes Distribution
 ### Authentication
 
 User authentication for the platform should be handled via a central OIDC-compatible identity provider system (e.g., Keycloak, Azure AD, Okta, or any other OIDC-compliant provider).
-The rationale is that other central platform components — such as ArgoCD, Grafana, Headlamp, or Harbor — should also integrate with the same authentication mechanism. This enables a unified login experience and reduces administrative complexity in managing users and permissions.
+The rationale is that other central platform components, such as ArgoCD, Grafana, Headlamp, or Harbor, should also integrate with the same authentication mechanism. This enables a unified login experience and reduces administrative complexity in managing users and permissions.
 
 [Capsule relies on native Kubernetes RBAC](/docs/operating/authentication/), so it's important to consider how the Kubernetes API handles user authentication.
 
 ### OCI Pull-Cache
 
-By default, Kubernetes clusters pull images directly from upstream registries like `docker.io`, `quay.io`, `ghcr.io`, or `gcr.io`. In production environments, this can lead to issues — especially because Docker Hub enforces rate limits that may cause image pull failures with just a few nodes or frequent deployments (e.g., when pods are rescheduled).
+By default, Kubernetes clusters pull images directly from upstream registries like `docker.io`, `quay.io`, `ghcr.io`, or `gcr.io`. In production environments, this can lead to issues, especially because Docker Hub enforces rate limits that may cause image pull failures with just a few nodes or frequent deployments (e.g., when pods are rescheduled).
 
 To ensure availability, performance, and control over container images, it's essential to provide an on-premise OCI mirror.
 This mirror should be configured via the CRI (Container Runtime Interface) by defining it as a mirror endpoint in registries.conf for default registries (e.g., `docker.io`).
@@ -25,7 +25,7 @@ This way, all nodes automatically benefit from caching without requiring develop
 ### Secrets Management
 
 In more complex environments with multiple clusters and applications, managing secrets manually via YAML or Helm is no longer practical.
-Instead, a centralized secrets management system should be established — such as Vault, AWS Secrets Manager, Azure Key Vault, or the CNCF project [OpenBao](https://openbao.org/) (formerly the Vault community fork).
+Instead, a centralized secrets management system should be established, such as Vault, AWS Secrets Manager, Azure Key Vault, or the CNCF project [OpenBao](https://openbao.org/) (formerly the Vault community fork).
 
 To integrate these external secret stores with Kubernetes, the [External Secrets Operator (ESO)](https://external-secrets.io/latest/) is a recommended solution. It automatically syncs defined secrets from external sources as Kubernetes secrets, and supports dynamic rotation, access control, and auditing.