kubernetes-sigs · k8s-ci-robot · Apr 1, 2026 · Mar 30, 2026 · camilamacedo86 · Mar 31, 2026
diff --git a/.github/workflows/docs-accessibility.yml b/.github/workflows/docs-accessibility.yml
@@ -0,0 +1,21 @@
+name: Docs Accessibility
+
+on:
+  push:
+    paths:
+      - '**/*.md'
+  pull_request:
+    paths:
+      - '**/*.md'
+
+jobs:
+  lint:
+    name: "Check Docs Accessibility"
+    runs-on: ubuntu-latest
+    # Pull requests from the same repository won't trigger this checks as they were already triggered by the push
+    if: (github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository)
+    steps:
+      - name: Clone the code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Run check
+        run: make test-docs-accessibility
diff --git a/Makefile b/Makefile
@@ -234,6 +234,10 @@ test-external-plugin: install  ## Run tests for external plugin
 test-spaces:  ## Run the trailing spaces check
 	./test/check_spaces.sh
 
+.PHONY: test-docs-accessibility
+test-docs-accessibility:  ## Run the documentation accessibility check
+	./test/check_docs_accessibility.sh
+
 ## TODO: Remove me when go/v4 plugin be removed
 ## Deprecated
 .PHONY: test-legacy

diff --git a/docs/book/src/cronjob-tutorial/cronjob-tutorial.md b/docs/book/src/cronjob-tutorial/cronjob-tutorial.md
@@ -19,9 +19,9 @@ once, seeing them to completion.
 Instead of trying to tackle rewriting the Job controller as well, we'll
 use this as an opportunity to see how to interact with external types.
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>Following Along vs Jumping Ahead</h1>
+<p class="note-title">Following Along vs Jumping Ahead</p>
 
 Note that most of this tutorial is generated from literate Go files that
 live in the book source directory:
@@ -52,7 +52,7 @@ cd project
 kubebuilder init --domain tutorial.kubebuilder.io --repo tutorial.kubebuilder.io/project
 ```
 
-<aside class="note">
+<aside class="note" role="note">
 
 Your project's name defaults to that of your current working directory.
 You can pass `--project-name=<dns1123-label-string>` to set a different project name.
@@ -62,9 +62,9 @@ You can pass `--project-name=<dns1123-label-string>` to set a different project
 Now that we've got a project in place, let's take a look at what
 Kubebuilder has scaffolded for us so far...
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>Developing in <code>$GOPATH</code></h1>
+<p class="note-title">Developing in <code>$GOPATH</code></p>
 
 If your project is initialized within [`GOPATH`][GOPATH-golang-docs], the implicitly called `go mod init` will interpolate the module path for you.
 Otherwise `--repo=<module path>` must be set.

diff --git a/docs/book/src/cronjob-tutorial/running-webhook.md b/docs/book/src/cronjob-tutorial/running-webhook.md
@@ -12,8 +12,8 @@ Run the following command to build your image locally.
 make docker-build docker-push IMG=<some-registry>/<project-name>:tag
 ```
 
-<aside class="note">
-<h1> Using Kind </h1>
+<aside class="note" role="note">
+<p class="note-title"> Using Kind </p>
 
 Consider incorporating Kind into your workflow for a faster, more efficient local development and CI experience.
 Note that, if you're using a Kind cluster, there's no need to push your image to a remote container registry.
@@ -73,8 +73,8 @@ kubectl create -f config/samples/batch_v1_cronjob.yaml
 You can also try to create an invalid CronJob (e.g. use an ill-formatted
 schedule field). You should see a creation failure with a validation error.
 
-<aside class="warning">
-<h3>The Bootstrapping Problem</h3>
+<aside class="warning" role="note">
+<p class="note-title">The Bootstrapping Problem</p>
 
 When you deploy a webhook into the same cluster that it will validate, you can run into a *bootstrapping issue*:
 the webhook may try to validate the creation of its own Pod before it’s actually running.

diff --git a/docs/book/src/cronjob-tutorial/running.md b/docs/book/src/cronjob-tutorial/running.md
@@ -16,9 +16,9 @@ manifests using controller-tools, if needed:
 make install
 ```
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>Too long annotations error</h1>
+<p class="note-title">Too long annotations error</p>
 
 If you encounter errors when applying the CRDs, due to `metadata.annotations` exceeding the
 262144 bytes limit, please refer to the specific entry in the [FAQ section](/faq#the-error-too-long-must-have-at-most-262144-bytes-is-faced-when-i-run-make-install-to-apply-the-crd-manifests-how-to-solve-it-why-this-error-is-faced).
@@ -29,9 +29,9 @@ Now that we've installed our CRDs, we can run the controller against our
 cluster.  This will use whatever credentials that we connect to the
 cluster with, so we don't need to worry about RBAC just yet.
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>Running webhooks locally</h1>
+<p class="note-title">Running webhooks locally</p>
 
 If you want to run the webhooks locally, you'll have to generate
 certificates for serving the webhooks, and place them in the right
@@ -82,8 +82,8 @@ make docker-build docker-push IMG=<some-registry>/<project-name>:tag
 make deploy IMG=<some-registry>/<project-name>:tag
 ```
 
-<aside class="note">
-<h1>Registry Permission</h1>
+<aside class="note" role="note">
+<p class="note-title">Registry Permission</p>
 
 This image ought to be published in the personal registry you specified. And it is required to have access to pull the image from the working environment.
 Make sure you have the proper permission to the registry if the above commands don't work.
@@ -98,7 +98,7 @@ kind load docker-image <your-image-name>:tag --name <your-kind-cluster-name>
 
 To know more, see: [Using Kind For Development Purposes and CI](./../reference/kind.md)
 
-<h1>RBAC errors</h1>
+<p class="note-title">RBAC errors</p>
 
 If you encounter RBAC errors, you may need to grant yourself cluster-admin
 privileges or be logged in as admin. See [Prerequisites for using Kubernetes RBAC on GKE cluster v1.11.x and older][pre-rbc-gke] which may be your case.

diff --git a/docs/book/src/cronjob-tutorial/webhook-implementation.md b/docs/book/src/cronjob-tutorial/webhook-implementation.md
@@ -37,8 +37,8 @@ kubebuilder create webhook --group batch --version v1 --kind CronJob --defaultin
 
 This changes the path in the webhook marker annotation but does not change where the webhook files are scaffolded. The webhook files will still be created in `internal/webhook/v1/`.
 
-<aside class="note">
-<h1>Version Requirements</h1>
+<aside class="note" role="note">
+<p class="note-title">Version Requirements</p>
 
 Custom webhook paths require **controller-runtime v0.21+**. In earlier versions (< `v0.21`), the webhook path must follow a specific pattern and cannot be customized. The path is automatically generated based on the resource's group, version, and kind (e.g., `/mutate-batch-v1-cronjob`).
 

diff --git a/docs/book/src/cronjob-tutorial/writing-tests.md b/docs/book/src/cronjob-tutorial/writing-tests.md
@@ -9,8 +9,8 @@ The basic approach is that, in your generated `suite_test.go` file, you will use
 
 If you want to tinker with how your envtest cluster is configured, see section [Configuring envtest for integration tests](../reference/envtest.md) as well as the [`envtest docs`](https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/envtest?tab=doc).
 
-<aside class="note">
-<h1>Other Examples</h1>
+<aside class="note" role="note">
+<p class="note-title">Other Examples</p>
 
 If you would like to see additional examples of controller tests generated by Kubebuilder, take a look at the <a href="../plugins/available/deploy-image-plugin-v1-alpha.md">Deploy Image plugin (deploy-image/v1-alpha)</a>.
 This plugin scaffolds APIs and controllers for managing an Operand (container image) on a cluster, following recommended patterns.

diff --git a/docs/book/src/faq.md b/docs/book/src/faq.md
@@ -1,8 +1,8 @@
 
 # FAQ
 
-<aside class="note">
-<h1> Controller-Runtime FAQ </h1>
+<aside class="note" role="note">
+<p class="note-title"> Controller-Runtime FAQ </p>
 
 Kubebuilder is developed on top of the [controller-runtime](https://github.com/kubernetes-sigs/controller-runtime)
 and [controller-tools](https://github.com/kubernetes-sigs/controller-tools) libraries. We recommend you also check

diff --git a/docs/book/src/getting-started.md b/docs/book/src/getting-started.md
@@ -7,8 +7,8 @@ We will create a sample project to let you know how it works. This sample will:
 - Not allow more instances than the size defined in the CR which will be applied
 - Update the Memcached CR status
 
-<aside class="note">
-<h1>Why Operators?</h1>
+<aside class="note" role="note">
+<p class="note-title">Why Operators?</p>
 
 By following the [Operator Pattern][k8s-operator-pattern], it’s possible not only to provide all expected resources
 but also to manage them dynamically, programmatically, and at execution time. To illustrate this idea, imagine if
@@ -17,8 +17,8 @@ without any human intervention.
 
 </aside>
 
-<aside class="note">
-<h1>Following Along vs Jumping Ahead</h1>
+<aside class="note" role="note">
+<p class="note-title">Following Along vs Jumping Ahead</p>
 
 Note that most of this tutorial is generated from literate Go files that
 form a runnable project, and live in the book source directory:
@@ -38,8 +38,8 @@ cd $GOPATH/memcached-operator
 kubebuilder init --domain=example.com
 ```
 
-<aside class="note">
-<h1>Developing in $GOPATH</h1>
+<aside class="note" role="note">
+<p class="note-title">Developing in $GOPATH</p>
 
 If your project is initialized within [`GOPATH`][GOPATH-golang-docs], the implicitly called `go mod init` will interpolate the module path for you.
 Otherwise `--repo=<module path>` must be set.
@@ -66,8 +66,8 @@ By leveraging the Kubebuilder tool, we can define our APIs and objects represent
 While we've added only one Kind of resource in this example, we can have as many `Groups` and `Kinds` as necessary.
 To make it easier to understand, think of CRDs as the definition of our custom Objects, while CRs are instances of them.
 
-<aside class="note">
-<h1> Please ensure that you check </h1>
+<aside class="note" role="note">
+<p class="note-title"> Please ensure that you check </p>
 
 [Groups and Versions and Kinds, oh my!][group-kind-oh-my].
 
@@ -106,8 +106,8 @@ type MemcachedStatus struct {
 }
 ```
 
-<aside class="note">
-<h1> Status Conditions </h1>
+<aside class="note" role="note">
+<p class="note-title"> Status Conditions </p>
 
 Kubernetes has established conventions, and because of this, we use
 Status Conditions here. We want our custom APIs and controllers to behave
@@ -197,8 +197,8 @@ reconcile App {
 }
 ```
 
-<aside class="note">
-<h1> Return Options </h1>
+<aside class="note" role="note">
+<p class="note-title"> Return Options </p>
 
 The following are a few possible return options to restart the Reconcile:
 
@@ -356,9 +356,9 @@ if err := ctrl.SetControllerReference(memcached, dep, r.Scheme); err != nil {
 }
 ```
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1><code>ownerRef</code> and Cascading Events</h1>
+<p class="note-title"><code>ownerRef</code> and Cascading Events</p>
 
 The ownerRef is crucial not only for allowing us to observe changes on the specific resource but also because,
 if we delete the Memcached Custom Resource (CR) from the cluster, we want all resources owned by it to be automatically
@@ -435,8 +435,8 @@ see: [Run It On the Cluster](./quick-start#run-it-on-the-cluster)
 - To delve deeper into developing your solution, consider going through the [CronJob Tutorial][cronjob-tutorial]
 - For insights on optimizing your approach, refer to the [Best Practices][best-practices] documentation.
 
-<aside class="note">
-<h1> Using Deploy Image plugin to generate APIs and source code </h1>
+<aside class="note" role="note">
+<p class="note-title"> Using Deploy Image plugin to generate APIs and source code </p>
 
 Now that you have a better understanding, you might want to check out the [Deploy Image][deploy-image] Plugin.
 This plugin allows users to scaffold APIs/Controllers to deploy and manage an Operand (image) on the cluster.

diff --git a/docs/book/src/migration/ai-helpers.md b/docs/book/src/migration/ai-helpers.md
@@ -2,9 +2,9 @@
 
 AI can assist manual migrations by reducing repetitive work and helping resolve breaking changes. It won't replace the [Manual Migration Process](./manual-process.md), but it can help reduce effort and accomplish the goal.
 
-<aside class="warning">
+<aside class="warning" role="note">
 
-<h1>Important</h1>
+<p class="note-title">Important</p>
 
 These AI instructions are provided as examples to help guide your migration. Always validate AI output carefully - you remain responsible for ensuring correctness.
 

diff --git a/docs/book/src/migration/discovery-commands.md b/docs/book/src/migration/discovery-commands.md
@@ -2,9 +2,9 @@
 
 Use AI to analyze your (now reorganized) Kubebuilder project and generate all CLI commands needed to recreate it with the latest version.
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>You May Not Need This</h1>
+<p class="note-title">You May Not Need This</p>
 
 **If you have a PROJECT file** and used Kubebuilder CLI to scaffold **all** resources (APIs, controllers, webhooks), you can use `kubebuilder alpha generate` instead.
 
@@ -17,9 +17,9 @@ The `alpha generate` command re-scaffolds everything tracked in your PROJECT fil
 
 </aside>
 
-<aside class="note">
+<aside class="note" role="note">
 
-<h1>When to Use This</h1>
+<p class="note-title">When to Use This</p>
 
 Use AI discovery if your project has:
 - APIs not tracked in the PROJECT file (manually created)
@@ -33,9 +33,9 @@ AI scans your entire codebase to discover everything, ensuring nothing is missed
 
 ## Instructions to provide to your AI assistant
 
-<aside class="warning">
+<aside class="warning" role="note">
 
-<h1>Standard Kubebuilder Layout Only</h1>
+<p class="note-title">Standard Kubebuilder Layout Only</p>
 
 These instructions work for projects using **standard Kubebuilder directory layout**:
 - API types in `api/` directory (some projects use `apis/`)