kubernetes-sigs · k8s-ci-robot · Dec 23, 2025 · Dec 17, 2025 · Dec 18, 2025 · Dec 18, 2025
diff --git a/.github/workflows/verify-broken-links.yml b/.github/workflows/verify-broken-links.yml
@@ -0,0 +1,21 @@
+name: Verify docs broken links
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+# Remove all permissions from GITHUB_TOKEN except metadata.
+permissions: {}
+
+jobs:
+  verify-docs:
+    name: Build website and run lychee
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # tag=v6.0.1
+        with:
+          persist-credentials: false
+      - name: Run validation
+        run: |
+          make verify-docs
diff --git a/.gitignore b/.gitignore
@@ -62,3 +62,4 @@ site-src/reference/specx.md
 site-src/reference/**/spec.md
 site-src/reference/**/specx.md
 
+.lycheecache
diff --git a/Makefile b/Makefile
@@ -58,6 +58,12 @@ GO_TEST_FLAGS ?=
 CEL_TEST_K8S_VERSION ?= 
 CEL_TEST_CRD_CHANNEL ?= standard
 
+# Flags for docs validation
+# Use this to add extra flags like --offline or --include "github.com/kubernetes"
+# Github is intentionally removed from the checks due to rate limits and because the 
+# anchor validation does not work when pointing to a github code
+VALIDATE_DOCS_EXTRA_FLAGS ?= 
+
 # Compilation flags for binaries
 GOARCH ?= $(shell go env GOARCH)
 GOOS ?= $(shell go env GOOS)
@@ -191,13 +197,18 @@ release-staging: image.multiarch.setup
 # Docs
 
 DOCS_BUILD_CONTAINER_NAME ?= gateway-api-mkdocs
+DOCS_VERIFY_CONTAINER_IMAGE ?= registry.hub.docker.com/lycheeverse/lychee:0.22
 
 .PHONY: build-docs
-build-docs: update-geps
+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
 
+.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
+
 .PHONY: build-docs-netlify
 build-docs-netlify: update-geps api-ref-docs
 	pip install -r hack/mkdocs/image/requirements.txt

diff --git a/geps/gep-1294/index.md b/geps/gep-1294/index.md
@@ -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#gateway.networking.k8s.io%2fv1beta1.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/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`.
 
 ### 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#gateway.networking.k8s.io/v1.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/spec.md#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#gateway.networking.k8s.io/v1.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/spec.md#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,7 +324,7 @@ 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#gateway.networking.k8s.io/v1.ParentReference)
+#### Nested `services` and `hostnames` fields in [`ParentReference`](../../reference/spec.md#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.
 
@@ -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#gateway.networking.k8s.io/v1.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/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.
 
 ```
 spec:

diff --git a/geps/gep-1364/index.md b/geps/gep-1364/index.md
@@ -456,4 +456,4 @@ needs updating.)
 [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#gateway.networking.k8s.io%2fv1beta1.HTTPRequestRedirectFilter
+[httpreqredirect]: ../../reference/spec.md#httprequestredirectfilter
diff --git a/geps/gep-1619/index.md b/geps/gep-1619/index.md
@@ -678,7 +678,7 @@ route in any given implementation.
 
 The new `BackendLBPolicy` metaresource only supports attaching to a backend. A backend can be a Service,
 ServiceImport (see [GEP-1748](../gep-1748/index.md)), or any implementation-specific backends that are a valid
-[`BackendObjectReference`](../../reference/spec.md#gateway.networking.k8s.io%2fv1.BackendObjectReference). Enabling session
+[`BackendObjectReference`](../../reference/spec.md#backendobjectreference). Enabling session
 persistence for a backend enables subsequently enables it for any route directing traffic to this backend. To learn more
 about the process of attaching a policy to a backend, please refer to [GEP-713](../gep-713/index.md).
 

diff --git a/geps/gep-1731/index.md b/geps/gep-1731/index.md
@@ -417,9 +417,9 @@ This may be a reasonable approach for configuring broad default retry policies,
 
 ### HTTPRoute filter
 
-Implementing a `requestRetryPolicy` [HTTPRouteFilter](../../reference/spec.md#gateway.networking.k8s.io/v1.HTTPRouteFilter) type is likely a reasonable alternative implementation (with the downside of slightly deeping nesting and more complex structural configuration) that was not fully explored.
+Implementing a `requestRetryPolicy` [HTTPRouteFilter](../../reference/spec.md#httproutefilter) type is likely a reasonable alternative implementation (with the downside of slightly deeping nesting and more complex structural configuration) that was not fully explored.
 
-Adding a new field to HTTPRouteRule instead is proposed for parity with the similar and intersecting configuration of [HTTPRouteTimeouts](../../reference/spec.md#gateway.networking.k8s.io/v1.HTTPRouteTimeouts).
+Adding a new field to HTTPRouteRule instead is proposed for parity with the similar and intersecting configuration of [HTTPRouteTimeouts](../../reference/spec.md#httproutetimeouts).
 
 ## Other considerations
 

diff --git a/geps/gep-1897/index.md b/geps/gep-1897/index.md
@@ -31,7 +31,7 @@ Gateway to backend**, such as server name indication and trusted CA certificates
 
 These are worthy goals, but deserve a different GEP for proper attention.  This GEP is concerned entirely with the
 hop between gateway client and backend.
-1. [TCPRoute](../../apis/v1alpha2/tcproute_types.go) use cases are not addressed here, because at this point in time
+1. [TCPRoute](https://github.com/kubernetes-sigs/gateway-api/blob/main/apis/v1alpha2/tcproute_types.go) use cases are not addressed here, because at this point in time
 TCPRoute is not graduated to beta.
 2. Mutual TLS (mTLS) use cases are intentionally out of scope for this GEP for two reasons.  First, the design of Gateway
 API is backend-attached and does not currently support mutual authentication, and also because this GEP does not
@@ -606,7 +606,7 @@ i.e. Service, in the cluster based on backendRefs rules of the HTTPRoute **and t
 
 In order to scope this GEP, some changes are deferred to a near-future GEP.
 This GEP intends to add the ability for additional control by gateway clients to override TLS settings, following previously
-established patterns of [consumer and producer policies]([glossary](https://gateway-api.sigs.k8s.io/concepts/glossary/?h=gloss#producer-route)).
+established patterns of [consumer and producer policies](../../concepts/glossary.md#producer-route).
 Additionally, more contextual control over when to apply the policies will be explored, to enable use cases like "apply
 TLS only from this route" ([issue](https://github.com/kubernetes-sigs/gateway-api/issues/3856)).
 

diff --git a/geps/gep-2162/index.md b/geps/gep-2162/index.md
@@ -28,7 +28,7 @@ This GEP proposes to enhance the [GatewayClassStatus](https://github.com/kuberne
 
 The current [GatewayClassStatus](https://github.com/kubernetes-sigs/gateway-api/blob/f2cd9bb92b4ff392416c40d6148ff7f76b30e649/apis/v1beta1/gatewayclass_types.go#L185) is only used to store conditions the controller publishes.
 
-Partnered with the [Conformance Profiles](https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-1709.md) work, we want to:
+Partnered with the [Conformance Profiles](/geps/gep-1709/) work, we want to:
 
 1. Improve UX by enabling users to easily see what features the implementation(GatewayClass) support.
 1. Standardize features and conformance tests names.
@@ -162,15 +162,15 @@ Before we make the changes we need to;
 
 ### Re-using ConformanceProfiles structs
 
-We could use the same structs as we do in conformance profile object, more specifically, the [ProfileReport](https://github.com/kubernetes-sigs/gateway-api/blob/main/conformance/apis/v1alpha1/profilereport.go#LL24C6-L24C19) struct.
+We could use the same structs as we do in conformance profile object, more specifically, the [ProfileReport](https://github.com/kubernetes-sigs/gateway-api/blob/main/conformance/apis/v1/conformancereport.go#LL28C6-L28C19) struct.
 
 Though it would be nice to have only one place to update, these structs seems to include much more data relevant to the conformance report but not for our use case.
 
 That said, conformance profiles are still at experimental stage, we could explore the option to create a shared struct that will be used both for the conformance reports and for the GatewayClass status.
 
 ### Instruct users to read from the future conformance profiles report
 
-The current plan for conformance profiles is to also include centralized reporting. (more info in [gep-1709](https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-1709.md))
+The current plan for conformance profiles is to also include centralized reporting. (more info in [gep-1709](/geps/gep-1709/))
 We could wait for this to be implemented and instruct users to read from that source to determine what features their installed GatewayClass support.
 
 However, having the supported features published in the GatewayClass Status adds the following values:

diff --git a/geps/gep-3567/index.md b/geps/gep-3567/index.md
@@ -99,10 +99,10 @@ negotiated with the other Listener’s certificate.
 
 Mapping a request to a Listener matters if the Gateway configuration has
 different
-[HTTPRoutes](../../reference/spec.md#gateway.networking.k8s.io/v1.HTTPRoute)
+[HTTPRoutes](../../reference/spec.md#httproute)
 bound to the different Listeners. It also matters if the Listeners have
 different
-[GatewayTlsConfigs](../../reference/spec.md#gateway.networking.k8s.io/v1.GatewayTLSConfig)
+[GatewayTlsConfigs](../../reference/spec.md#gatewaytlsconfig)
 attached, for example if one Listener uses mutual TLS and the other does not.
 
 

diff --git a/geps/gep-3792/index.md b/geps/gep-3792/index.md
@@ -19,8 +19,8 @@ cluster, for various reasons which are out of the scope of this GEP. Chihiro
 and Ian want to be able to use these out-of-cluster proxies effectively and
 safely, though they recognize that this may require additional configuration.
 
-[Chihiro]: https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#chihiro
-[Ian]: https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#ian
+[Chihiro]: ../../concepts/roles-and-personas.md#chihiro
+[Ian]: ../../concepts/roles-and-personas/#ian
 
 ### Nomenclature and Background
 
@@ -241,7 +241,7 @@ or Mesh resources.
 ## Graduation Criteria
 
 In addition to the [general graduation
-criteria](../concepts/versioning.md#graduation-criteria), this GEP must also
+criteria](/concepts/versioning#graduation-criteria), this GEP must also
 guarantee that **all four** of the problems listed above need resolutions, and
 must have implementation from at least two different Gateways and two
 different meshes.

diff --git a/geps/gep-3793/index.md b/geps/gep-3793/index.md
@@ -216,9 +216,9 @@ Ana has easy access to this information, and that it's clear enough for her to
 understand, is clearly important for many more reasons than just default
 Gateways.
 
-[Ana]: https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#ana
-[Chihiro]: https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#chihiro
-[Ian]: https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#ian
+[Ana]: ../../concepts/roles-and-personas/#ana
+[Chihiro]: ../../concepts/roles-and-personas/#chihiro
+[Ian]: ../../concepts/roles-and-personas/#ian
 
 ## API
 

diff --git a/geps/gep-3949/index.md b/geps/gep-3949/index.md
@@ -5,9 +5,9 @@
 
 (See [status definitions](../overview.md#gep-states).)
 
-[Chihiro]: https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#chihiro
-[Ian]: https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#ian
-[Ana]: https//gateway-api.sigs.k8s.io/concepts/roles-and-personas/#ana
+[Chihiro]: ../../concepts/roles-and-personas/#chihiro
+[Ian]: ../../concepts/roles-and-personas/#ian
+[Ana]: ../../concepts/roles-and-personas/#ana
 
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
 "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this

diff --git a/geps/gep-713/index.md b/geps/gep-713/index.md
@@ -51,7 +51,7 @@ After multiple iterations of Gateway API experimenting with policies—whether t
 
 ### User stories
 
-- [Ana](../../concepts/roles-and-personas.md#ana) or [Chihiro](../../concepts/roles-and-personas.md#Chihiro) would like to specify some new behavior for a standard Kubernetes resource, but that resource doesn't have a way to specify the behavior and neither Ana nor Chihiro can modify it.
+- [Ana](../../concepts/roles-and-personas.md#ana) or [Chihiro](../../concepts/roles-and-personas.md#chihiro) would like to specify some new behavior for a standard Kubernetes resource, but that resource doesn't have a way to specify the behavior and neither Ana nor Chihiro can modify it.
   E.g., Ana may want to add a rate limit to a Kubernetes Service. The Service object itself doesn't have a field for rate limiting, and Ana can't modify the Service object's definition.
 
 - A Gateway API implementer would like to define some implementation-specific behaviors for Gateway API objects that are already standard.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -62,3 +62,4 @@ site-src/reference/specx.md
		site-src/reference/**/spec.md
		site-src/reference/**/specx.md

		.lycheecache