kubernetes-sigs · iromanycheva-eng · Apr 9, 2026 · Apr 15, 2026 · Apr 16, 2026 · Apr 18, 2026
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -17,7 +17,7 @@
 6. If this PR includes a new GEP please make sure you've followed the process
    outlined in our GEP overview, as this will help the community to ensure the
    best chance of positive outcomes for your proposal:
-   https://gateway-api.sigs.k8s.io/geps/overview/#process
+   https://gateway-api.sigs.k8s.io/enhancements/overview/#process
 -->
 
 **What type of PR is this?**

diff --git a/.gitignore b/.gitignore
@@ -49,7 +49,6 @@ Session.vim
 .vscode
 /www/test_out
 .*.timestamp
-/site
 go.work.sum
 /tmp
 /conformance.test
@@ -61,9 +60,12 @@ site-src/reference/spec.md
 site-src/reference/specx.md
 site-src/reference/**/spec.md
 site-src/reference/**/specx.md
-site-src/wizard/main.wasm
-site-src/wizard/wasm_exec.js
-site-src/wizard/data/*
+site/static/wizard/main.wasm
+site/static/wizard/wasm_exec.js
+site/static/wizard/data/*
+
 
 .lycheecache
 
+# Local Netlify folder
+.netlify
diff --git a/Makefile b/Makefile
@@ -46,7 +46,7 @@ export COMMIT ?= $(shell git rev-parse --short HEAD)
 DOCKER ?= docker
 # TOP is the current directory where this Makefile lives.
 TOP := $(dir $(firstword $(MAKEFILE_LIST)))
-# ROOT is the root of the mkdocs tree.
+# ROOT is the root of the documentation tree.
 ROOT := $(abspath $(TOP))
 
 # Command-line flags passed to "go test" for the conformance
@@ -109,7 +109,7 @@ test:
 .PHONY: tidy
 tidy:
 	go work sync
-	find . -name go.mod -execdir sh -c 'go mod tidy' \;
+	find . -name go.mod -not -path "./site/*" -exec sh -c 'cd "$$(dirname "{}")" && go mod tidy' \;
 
 # Run tests for CRDs validation
 .PHONY: test.crds-validation
@@ -152,11 +152,6 @@ uninstall:
 verify:
 	hack/verify-all.sh -v
 
-# Build the documentation.
-.PHONY: docs
-docs:
-	hack/make-docs.sh
-
 .PHONY: update-conformance-image-refs
 update-conformance-image-refs:
 	hack/update-conformance-image-refs.sh
@@ -197,52 +192,60 @@ release-staging: image.multiarch.setup
 
 # Docs
 
-DOCS_BUILD_CONTAINER_NAME ?= gateway-api-mkdocs
+PYTHON ?= $(shell if [ -x .venv/bin/python3 ]; then echo "./.venv/bin/python3"; else echo "python3"; fi)
+
 DOCS_VERIFY_CONTAINER_IMAGE ?= registry.hub.docker.com/lycheeverse/lychee:0.23
 
+# Build the documentation.
+.PHONY: docs
+docs:
+	hack/make-hugo-docs.sh
+
 .PHONY: build-docs
-build-docs: update-geps api-ref-docs
-	docker build --pull -t gaie/mkdocs hack/mkdocs/image
-	docker rm -f $(DOCS_BUILD_CONTAINER_NAME) || true
-	docker run --name $(DOCS_BUILD_CONTAINER_NAME) --rm -v ${PWD}:/docs gaie/mkdocs build
+build-docs: update-geps api-ref-docs wizard-wasm wizard-data conformance-data
+	hugo --source site
 
 .PHONY: verify-docs
 verify-docs: build-docs
-	docker run --init --rm -w /input -v ${PWD}:/input $(DOCS_VERIFY_CONTAINER_IMAGE) --root-dir /input/site --exclude-path "overrides/partials/.*\.html" --exclude ".*" --include "sigs.k8s.io" --accept 200 --max-concurrency 10 --include-fragments --cache $(VALIDATE_DOCS_EXTRA_ARGS) /input/site/**/*.html
+	docker run --init --rm -w /input -v ${PWD}:/input $(DOCS_VERIFY_CONTAINER_IMAGE) --root-dir /input/site/public --include "sigs.k8s.io" --accept 200 --max-concurrency 10 --include-fragments --cache $(VALIDATE_DOCS_EXTRA_ARGS) /input/site/public/**/*.html
 
 .PHONY: build-docs-netlify
-build-docs-netlify: update-geps api-ref-docs wizard-wasm
-	pip install -r hack/mkdocs/image/requirements.txt
-	python -m mkdocs build
+build-docs-netlify: update-geps api-ref-docs wizard-wasm wizard-data conformance-data
+	hugo --source site
 
 .PHONY: live-docs
-live-docs: update-geps
-	docker build -t gw/mkdocs hack/mkdocs/image
-	docker run --rm -it -p 3000:3000 -v ${PWD}:/docs gw/mkdocs
+live-docs: update-geps api-ref-docs
+	hugo server --source site
 
 .PHONY: update-geps
 update-geps:
 	hack/update-geps.sh
 
 .PHONY: api-ref-docs
 api-ref-docs:
-	hack/mkdocs/generate.sh
+	hack/docsy/generate.sh
 
 .PHONY: wizard-wasm
 wizard-wasm:
+	@mkdir -p site/static/wizard
 	@GOROOT=$$(go env GOROOT); \
-	if [ -f "$$GOROOT/misc/wasm/wasm_exec.js" ]; then cp -f "$$GOROOT/misc/wasm/wasm_exec.js" site-src/wizard/; \
-	elif [ -f "$$GOROOT/lib/wasm/wasm_exec.js" ]; then cp -f "$$GOROOT/lib/wasm/wasm_exec.js" site-src/wizard/; \
+	if [ -f "$$GOROOT/misc/wasm/wasm_exec.js" ]; then cp -f "$$GOROOT/misc/wasm/wasm_exec.js" site/static/wizard/; \
+	elif [ -f "$$GOROOT/lib/wasm/wasm_exec.js" ]; then cp -f "$$GOROOT/lib/wasm/wasm_exec.js" site/static/wizard/; \
 	else echo "ERROR: wasm_exec.js not found in GOROOT"; exit 1; fi
-	GOOS=js GOARCH=wasm go build -o site-src/wizard/main.wasm ./wasm/
+	GOOS=js GOARCH=wasm go build -o site/static/wizard/main.wasm ./wasm/
 
 # Generate controller wizard data (multi-version). Requires conformance/reports/ with version dirs.
 # Run manually if make serve is used without conformance reports.
 .PHONY: wizard-data
 wizard-data:
-	python3 hack/mkdocs-generate-controller-wizard-data.py --all -o site-src/wizard/data/controller-wizard-data.json
+	@mkdir -p site/static/wizard/data
+	$(PYTHON) hack/docsy-generate-controller-wizard-data.py --all -o site/static/wizard/data/controller-wizard-data.json
+
+.PHONY: conformance-data
+conformance-data:
+	$(PYTHON) hack/docsy-generate-conformance.py
 
 .PHONY: serve
-serve: wizard-wasm
+serve: wizard-wasm update-geps api-ref-docs
 	@echo "Tip: Run 'make wizard-data' first if you have conformance/reports/ to load implementation data."
-	python3 -m http.server -d site-src/wizard 8080
+	hugo server --source site
diff --git a/RELEASE.md b/RELEASE.md
@@ -140,8 +140,7 @@ The following steps must be done by one of the [Gateway API maintainers][gateway
 - Run the `make build-install-yaml` command which will generate install files in the `release/` directory.
   Attach these files to the GitHub release.
 - Update the `README.md` and `site-src/guides/index.md` files to point links and examples to the new release.
-- Update the implementation table path (`nav.Implementations.Comparison`) in the nav of `mkdocs.yml` to point to the latest release file (for example Implementation Comparison points to `implementation-table-v1.2.0.md`). Add the now past version under `Past Version Comparisons`, and edit the text blurb in `mkdocs-generate-conformance.py` to also reflect the added past version.
-- Update `hack/mkdocs/generate.sh` and add the new `release-x.x` to the array of releases.
+- Edit the text blurb in `hack/docsy-generate-conformance.py` to reflect the added past version if necessary.
 
 #### For an **RC** release:
 - Update `pkg/consts/consts.go` with the new semver tag (like `v1.2.0-rc1`) and any updates to the API review URL.

diff --git a/geps/_index.md b/geps/_index.md
@@ -0,0 +1,12 @@
+---
+title: "GEPs"
+weight: 10
+cascade:
+  type: docs
+  params:
+    ui:
+      breadcrumb_disable: false
+
+build:
+  list: never
+---
diff --git a/geps/gep-1016/index.md b/geps/gep-1016/index.md
@@ -7,7 +7,7 @@
 > our GEP overview as it existed before those rules did, and so it has been
 > explicitly grandfathered in.
 
-[expprob]:../overview.md#probationary-period
+[expprob]:/geps/overview/#probationary-period
 
 ## Goal
 

diff --git a/geps/gep-1294/index.md b/geps/gep-1294/index.md
@@ -11,7 +11,7 @@ This GEP is intended to establish an implementable, but experimental, baseline f
 
 ## Personas
 
-This GEP uses the [roles and personas](../../concepts/security.md#roles-and-personas) defined in the Gateway API security model, and the service "producer" and "consumer" roles defined in [GEP-1324: Service Mesh in Gateway API](../gep-1324/index.md#producer-and-consumer).
+This GEP uses the [roles and personas](/docs/concepts/security/#roles-and-personas) defined in the Gateway API security model, and the service "producer" and "consumer" roles defined in [GEP-1324: Service Mesh in Gateway API](../gep-1324/index.md#producer-and-consumer).
 
 ## Goals
 
@@ -27,7 +27,7 @@ This GEP uses the [roles and personas](../../concepts/security.md#roles-and-pers
     * Redirecting calls from arbitrary custom domains to an in-cluster service.
 * Defining how multiple `Services` or `EndpointSlices` representing instances of a single "logical" service should present an identity for AuthN/AuthZ or be associated with each other beyond routing rules.
 * Defining how AuthZ should be implemented to secure East/West traffic between services.
-* Defining how [Policy Attachment](../../reference/policy-attachment.md) would bind to `xRoute`, services or a mesh.
+* Defining how [Policy Attachment](/reference/policy-attachment) would bind to `xRoute`, services or a mesh.
 * Defining how `Routes` configured for East/West service mesh traffic management might integrate with North/South `Gateways`.
     * This is a bit tricky in that it's effectively a form of delegation as described in [GEP-1058: Route Inclusion and Delegation](https://github.com/kubernetes-sigs/gateway-api/pull/1085), and is planned to be explored in a future GEP.
 * Handling East/West traffic outside the cluster (VMs, etc).
@@ -187,7 +187,7 @@ If `port` is not set, the implementation MUST associate the route with all ports
 
 GAMMA implementations SHOULD NOT infer any functionality from the `hostnames` field on `xRoute`s (currently, `TLSRoute`, `HTTPRoute`, and `GRPCRoute` have this field) due to current under-specification and reserved potential for future usage or API changes.
 
-For the use case of filtering incoming traffic from selected HTTP hostnames, it is recommended to guide users toward configuring [`HTTPHeaderMatch`](../../reference/spec.md#httpheadermatch) rules for the [`Host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Host) header. Functionality to be explored in future GEPs may include supporting concurrent usage of an `xRoute` traffic configuration for multiple North/South `Gateways` and East/West mesh use cases or redirection of egress traffic to an in-cluster `Service`.
+For the use case of filtering incoming traffic from selected HTTP hostnames, it is recommended to guide users toward configuring [`HTTPHeaderMatch`](/reference/api-spec/main/spec/#httpheadermatch) rules for the [`Host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Host) header. Functionality to be explored in future GEPs may include supporting concurrent usage of an `xRoute` traffic configuration for multiple North/South `Gateways` and East/West mesh use cases or redirection of egress traffic to an in-cluster `Service`.
 
 ### Namespace boundaries
 
@@ -245,7 +245,7 @@ A controller could create a matching selector-less `Service` (i.e. no endpoints)
 
 Ownership/trust would remain based on naming pattern: `serviceName.namespace.svc.[USER_DOMAIN]`
 
-Separate `HttpService`, `TlsService` and `TcpService` resources could have the benefit of allowing us to define protocol specific elements to the spec along with an embedded `CommonServiceSpec`, similar to [`CommonRouteSpec`](../../reference/spec.md#commonroutespec), and keep similar patterns as `Service`.
+Separate `HttpService`, `TlsService` and `TcpService` resources could have the benefit of allowing us to define protocol specific elements to the spec along with an embedded `CommonServiceSpec`, similar to [`CommonRouteSpec`](/reference/api-spec/main/spec/#commonroutespec), and keep similar patterns as `Service`.
 
 ##### Drawbacks
 
@@ -303,7 +303,7 @@ spec:
     name: cool-mesh
 ```
 
-It is currently undefined how this approach may interact with either explicitly configured [`hostnames`](../../reference/spec.md#httproutespec) or implicit "transparent proxy" routing for Kubernetes `Services` to determine how traffic should be intercepted and redirected.
+It is currently undefined how this approach may interact with either explicitly configured [`hostnames`](/reference/api-spec/main/spec/#httproutespec) or implicit "transparent proxy" routing for Kubernetes `Services` to determine how traffic should be intercepted and redirected.
 
 This approach is not entirely abandoned, as it could supplement the proposed approach if explicit attachment to a specific mesh is deemed necessary. Additionally, this approach may offer a future option for attaching an `HTTPRoute` to a mesh, but not a specific service (e.g. to implement mesh-wide egress functionality for all requests to a specific hostname).
 
@@ -324,11 +324,11 @@ spec:
 
 * Would require separate `HTTPRoute` resources to explicitly define _different_ traffic routing rules for the same service on different meshes.
 
-#### Nested `services` and `hostnames` fields in [`ParentReference`](../../reference/spec.md#parentreference)
+#### Nested `services` and `hostnames` fields in [`ParentReference`](/reference/api-spec/main/spec/#parentreference)
 
 In core conformance, the `services` would only be valid for `Mesh` types, and `hostnames` field only for `Gateway`. Mesh implementations could still use a `Host` header match if they wanted limit rules to specific hostnames.
 
-```
+```yaml
 parentRefs:
 - kind: Mesh
   name: coolmesh
@@ -364,7 +364,7 @@ This is done by configuring the `parentRef`, to point to the `istio` `Mesh`. Thi
 
 ### New field on `HTTPRoute` for `Service` binding
 
-A new field `serviceBinding` would be added to `HTTPRoute` to attach to the `Service`. Alternatively, this could be a new field in [`HTTPRouteMatch`](../../reference/spec.md#httproutematch). As with the proposed implementation, this approach could be combined with a `Mesh` resource or similar as the `parentRef`, which would just define that the route would be applied to a mesh.
+A new field `serviceBinding` would be added to `HTTPRoute` to attach to the `Service`. Alternatively, this could be a new field in [`HTTPRouteMatch`](/reference/api-spec/main/spec/#httproutematch). As with the proposed implementation, this approach could be combined with a `Mesh` resource or similar as the `parentRef`, which would just define that the route would be applied to a mesh.
 
 ```
 spec:

diff --git a/geps/gep-1323/index.md b/geps/gep-1323/index.md
@@ -7,7 +7,7 @@
 > our GEP overview as it existed before those rules did, and so it has been
 > explicitly grandfathered in.
 
-[expprob]:../overview.md#probationary-period
+[expprob]:/geps/overview/#probationary-period
 
 ## TLDR
 Similar to how we have `RequestHeaderModifier` in `HTTPRouteFilter`, which lets users modify request headers before the request is forwarded to a backend (or a group of backends), it’d be helpful to have a `ResponseHeaderModifier` field which would let users modify response headers before they are returned to the client.
@@ -60,7 +60,7 @@ type HTTPHeaderModifier struct {
 
 Given the fact that this functionality is offered by only a few projects that currently implement Gateway API when using their own traffic routing CRDs, it’s better to support `ResponseHeaderModifier` as an _Extended_ feature, unlike `RequestHeaderModifier` which is a _Core_ feature. This will also not increase the difficulty of implementing Gateway API for any future ingress or service mesh.
 
-This feature can be further extended via [Policy Attachment](../../reference/policy-attachment.md). The mechanism and use cases of this may be explored in a future GEP.
+This feature can be further extended via [Policy Attachment](/reference/policy-attachment/). The mechanism and use cases of this may be explored in a future GEP.
 
 ## Usage
 Adding support for this unlocks a lot of real world use cases. Let’s review a couple of them:

diff --git a/geps/gep-1324/index.md b/geps/gep-1324/index.md
@@ -7,7 +7,7 @@
 > of our GEP overview as it existed before those rules did, and so it has been
 > explicitly grandfathered in.
 
-[expprob]:../overview.md#probationary-period
+[expprob]:/geps/overview/#probationary-period
 
 ## Overview
 
@@ -33,7 +33,7 @@ Gateway API represents the next generation of traffic routing APIs in Kubernetes
 
 ## Versioning
 
-Features or other modifications to the Gateway API spec that fall under this GEP will be subject to the same [versioning guidelines](../../concepts/versioning.md#graduation-criteria) as the rest of the Gateway API. For example, to move changes concerning a beta feature (e.g. HTTPRoute) from experimental to standard, all of the [graduation criteria](../../concepts/versioning.md#graduation-criteria) must be met (e.g. implemented by several implementations).
+Features or other modifications to the Gateway API spec that fall under this GEP will be subject to the same [versioning guidelines](/docs/concepts/versioning/#graduation-criteria) as the rest of the Gateway API. For example, to move changes concerning a beta feature (e.g. HTTPRoute) from experimental to standard, all of the [graduation criteria](/docs/concepts/versioning/#graduation-criteria) must be met (e.g. implemented by several implementations).
 
 ## Use-Cases
 

diff --git a/geps/gep-1364/index.md b/geps/gep-1364/index.md
@@ -449,11 +449,19 @@ if the condition is true.
 needs updating.)
 
 ## References
+
+* [KEP Status][kep-status]
+* [Issue 1111][1111]
+* [Issue 1110][1110]
+* [Issue 1362][1362]
+* [API Conventions: Typical status properties][typstatus]
+* [HTTPRequestRedirect filter][httpreqredirect]
+
 [kep-status]: https://github.com/kubernetes/enhancements/blob/master/keps/NNNN-kep-template/kep.yaml#L9
 
 [1111]: https://github.com/kubernetes-sigs/gateway-api/issues/1111
 [1110]: https://github.com/kubernetes-sigs/gateway-api/issues/1110
 [1362]: https://github.com/kubernetes-sigs/gateway-api/issues/1362
 
 [typstatus]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties
-[httpreqredirect]: ../../reference/spec.md#httprequestredirectfilter
+[httpreqredirect]: /reference/api-spec/main/spec/#httprequestredirectfilter
diff --git a/geps/gep-1494/index.md b/geps/gep-1494/index.md
@@ -3,7 +3,7 @@
 * Issue: [#1494](https://github.com/kubernetes-sigs/gateway-api/issues/1494)
 * Status: Experimental
 
-(See [status definitions](../overview.md#gep-states).)
+(See [status definitions](/geps/overview/#gep-states).)
 
 
 ## TLDR
@@ -13,7 +13,7 @@ Provide a method for configuring **Gateway API implementations** to add HTTP Aut
 
 ## Goals
 
-(Using the [Gateway API Personas](../../concepts/roles-and-personas.md))
+(Using the [Gateway API Personas](/docs/concepts/roles-and-personas.md))
 
 * A way for Ana the Application Developer to configure a Gateway API implementation to perform Authentication (at least), with optional Authorization.