kubernetes-sigs · orangecms · Feb 8, 2026
diff --git a/docs/book/src/cronjob-tutorial/cronjob-tutorial.md b/docs/book/src/cronjob-tutorial/cronjob-tutorial.md
@@ -21,7 +21,7 @@ use this as an opportunity to see how to interact with external types.
 
 <aside class="note">
 
-<h1>Following Along vs Jumping Ahead</h1>
+<h4>Following Along vs Jumping Ahead</h4>
 
 Note that most of this tutorial is generated from literate Go files that
 live in the book source directory:
@@ -64,7 +64,7 @@ Kubebuilder has scaffolded for us so far...
 
 <aside class="note">
 
-<h1>Developing in <code>$GOPATH</code></h1>
+<h4>Developing in <code>$GOPATH</code></h4>
 
 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
@@ -13,7 +13,7 @@ make docker-build docker-push IMG=<some-registry>/<project-name>:tag
 ```
 
 <aside class="note">
-<h1> Using Kind </h1>
+<h4> Using Kind </h4>
 
 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.

diff --git a/docs/book/src/cronjob-tutorial/running.md b/docs/book/src/cronjob-tutorial/running.md
@@ -18,7 +18,7 @@ make install
 
 <aside class="note">
 
-<h1>Too long annotations error</h1>
+<h4>Too long annotations error</h4>
 
 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).
@@ -31,7 +31,7 @@ cluster with, so we don't need to worry about RBAC just yet.
 
 <aside class="note">
 
-<h1>Running webhooks locally</h1>
+<h4>Running webhooks locally</h4>
 
 If you want to run the webhooks locally, you'll have to generate
 certificates for serving the webhooks, and place them in the right
@@ -83,7 +83,7 @@ make deploy IMG=<some-registry>/<project-name>:tag
 ```
 
 <aside class="note">
-<h1>Registry Permission</h1>
+<h4>Registry Permission</h4>
 
 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>
+<h4>RBAC errors</h4>
 
 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
@@ -38,7 +38,7 @@ 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>
+<h4>Version Requirements</h4>
 
 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
@@ -10,7 +10,7 @@ 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>
+<h4>Other Examples</h4>
 
 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
@@ -2,7 +2,7 @@
 # FAQ
 
 <aside class="note">
-<h1> Controller-Runtime FAQ </h1>
+<h4> Controller-Runtime FAQ </h4>
 
 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
@@ -8,7 +8,7 @@ We will create a sample project to let you know how it works. This sample will:
 - Update the Memcached CR status
 
 <aside class="note">
-<h1>Why Operators?</h1>
+<h4>Why Operators?</h4>
 
 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
@@ -18,7 +18,7 @@ without any human intervention.
 </aside>
 
 <aside class="note">
-<h1>Following Along vs Jumping Ahead</h1>
+<h4>Following Along vs Jumping Ahead</h4>
 
 Note that most of this tutorial is generated from literate Go files that
 form a runnable project, and live in the book source directory:
@@ -39,7 +39,7 @@ kubebuilder init --domain=example.com
 ```
 
 <aside class="note">
-<h1>Developing in $GOPATH</h1>
+<h4>Developing in $GOPATH</h4>
 
 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.
@@ -67,7 +67,7 @@ While we've added only one Kind of resource in this example, we can have as many
 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>
+<h4> Please ensure that you check </h4>
 
 [Groups and Versions and Kinds, oh my!][group-kind-oh-my].
 
@@ -107,7 +107,7 @@ type MemcachedStatus struct {
 ```
 
 <aside class="note">
-<h1> Status Conditions </h1>
+<h4> Status Conditions </h4>
 
 Kubernetes has established conventions, and because of this, we use
 Status Conditions here. We want our custom APIs and controllers to behave
@@ -198,7 +198,7 @@ reconcile App {
 ```
 
 <aside class="note">
-<h1> Return Options </h1>
+<h4> Return Options </h4>
 
 The following are a few possible return options to restart the Reconcile:
 
@@ -358,7 +358,7 @@ if err := ctrl.SetControllerReference(memcached, dep, r.Scheme); err != nil {
 
 <aside class="note">
 
-<h1><code>ownerRef</code> and Cascading Events</h1>
+<h4><code>ownerRef</code> and Cascading Events</h4>
 
 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
@@ -436,7 +436,7 @@ see: [Run It On the Cluster](./quick-start#run-it-on-the-cluster)
 - 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>
+<h4> Using Deploy Image plugin to generate APIs and source code </h4>
 
 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
@@ -4,7 +4,7 @@ AI can assist manual migrations by reducing repetitive work and helping resolve
 
 <aside class="warning">
 
-<h1>Important</h1>
+<h4>Important</h4>
 
 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
@@ -4,7 +4,7 @@ Use AI to analyze your (now reorganized) Kubebuilder project and generate all CL
 
 <aside class="note">
 
-<h1>You May Not Need This</h1>
+<h4>You May Not Need This</h4>
 
 **If you have a PROJECT file** and used Kubebuilder CLI to scaffold **all** resources (APIs, controllers, webhooks), you can use `kubebuilder alpha generate` instead.
 
@@ -19,7 +19,7 @@ The `alpha generate` command re-scaffolds everything tracked in your PROJECT fil
 
 <aside class="note">
 
-<h1>When to Use This</h1>
+<h4>When to Use This</h4>
 
 Use AI discovery if your project has:
 - APIs not tracked in the PROJECT file (manually created)
@@ -35,7 +35,7 @@ AI scans your entire codebase to discover everything, ensuring nothing is missed
 
 <aside class="warning">
 
-<h1>Standard Kubebuilder Layout Only</h1>
+<h4>Standard Kubebuilder Layout Only</h4>
 
 These instructions work for projects using **standard Kubebuilder directory layout**:
 - API types in `api/` directory (some projects use `apis/`)

diff --git a/docs/book/src/migration/manual-process.md b/docs/book/src/migration/manual-process.md
@@ -17,7 +17,7 @@ to better understand the project layouts and structure.
 
 
 <aside class="warning">
-<h1>About Manual Migration</h1>
+<h4>About Manual Migration</h4>
 
 Manual migration is more complex than automated methods but gives you complete control. Use manual migration when:
 - Your project has significant customizations
@@ -55,7 +55,7 @@ git checkout -b reorganize
 
 <aside class="note">
 
-<h1>Skip if Using AI Migration Helper</h1>
+<h4>Skip if Using AI Migration Helper</h4>
 
 If you used [Step 1: Reorganize to New Layout](./reorganize-layout.md) AI migration helper, your project is already reorganized. Skip to [Phase 2](#phase-2-migrate-to-latest-version).
 
@@ -154,7 +154,7 @@ Identify the information you'll need for initialization from your backup.
 
 <aside class="note">
 
-<h1>Skip if Using AI Migration Helper</h1>
+<h4>Skip if Using AI Migration Helper</h4>
 
 If you used [Step 2: Discovery CLI Commands](./discovery-commands.md) AI migration helper, you already have a complete script with all commands. Execute it and skip to [Step 4: Port Your Custom Code](#step-4-port-your-custom-code).
 
@@ -209,7 +209,7 @@ kubebuilder init --domain tutorial.kubebuilder.io --repo tutorial.kubebuilder.io
 Replace with your actual domain and repository (module path).
 
 <aside class="note">
-<h1>Understanding init options</h1>
+<h4>Understanding init options</h4>
 
 - `--domain`: The domain for your API groups (e.g., `tutorial.kubebuilder.io`). Your full API groups will be `<group>.<domain>`.
 - `--repo`: Your Go module path (same as in `go.mod`)
@@ -242,7 +242,7 @@ kubebuilder edit --multigroup=true
 ```
 
 <aside class="warning">
-<h1>Important</h1>
+<h4>Important</h4>
 
 This must be done before creating any APIs to ensure they're scaffolded in the multi-group structure.
 
@@ -283,7 +283,7 @@ resources:
 ```
 
 <aside class="note">
-<h1>Tip</h1>
+<h4>Tip</h4>
 
 Make a list of all APIs with their group, version, kind, and whether they have a controller.
 This will help you systematically re-scaffold everything.
@@ -321,7 +321,7 @@ See the [Quick Start][quick-start] guide for a detailed walkthrough of the API c
 Repeat this process for **ALL** APIs in your project.
 
 <aside class="note">
-<h1>Using External Types (controllers for types not defined in your project)</h1>
+<h4>Using External Types (controllers for types not defined in your project)</h4>
 
 If your project has controllers for Kubernetes built-in types (like `Deployment`, `Pod`) or types from other projects:
 
@@ -389,7 +389,7 @@ kubebuilder create webhook --group batch --version v1 --kind CronJob --defaultin
 If your project has multi-version APIs with conversion webhooks, you need to set up the hub-spoke conversion pattern.
 
 <aside class="note">
-<h1>Understanding Hub-Spoke Conversion</h1>
+<h4>Understanding Hub-Spoke Conversion</h4>
 
 In Kubernetes multi-version APIs, the **hub** is the version that all other versions (spokes) convert to and from:
 - **Hub version**: Usually the most complete/stable version (often the storage version)
@@ -431,7 +431,7 @@ The command generates method stubs that you'll fill in during Step 4:
 See the [Multi-Version Tutorial][multiversion-tutorial] for comprehensive guidance on implementing the conversion logic.
 
 <aside class="note">
-<H1> Forget a type of webhook ? </h1>
+<h4> Forget a type of webhook ? </h4>
 
 If you forget a webhook type, use `--force` to re-run the command:
 
@@ -441,7 +441,7 @@ kubebuilder create webhook --group batch --version v1 --kind CronJob --defaultin
 </aside>
 
 <aside class="note">
-<h1>Webhook for External Types</h1>
+<h4>Webhook for External Types</h4>
 
 **For external types**, you can also create webhooks:
 
@@ -462,7 +462,7 @@ make manifests && make build
 
 <aside class="note">
 
-<h1>Using AI Migration Helper</h1>
+<h4>Using AI Migration Helper</h4>
 
 If you used [Step 3: Port Custom Code](./port-code.md) AI migration helper, your code is already ported.
 
@@ -473,7 +473,7 @@ You may skip to [Step 5](#step-5-test-and-verify). However, it's still recommend
 Manually port your custom business logic and configurations from the backup to the new project.
 
 <aside class="note">
-<h1>Use diff tools</h1>
+<h4>Use diff tools</h4>
 
 Use IDE diff tools or commands like `diff -r ../migration-backup/ .` to compare directories and identify all customizations you need to port.
 Most modern IDEs support directory-level comparison which makes this process much easier.
@@ -562,7 +562,7 @@ Webhooks have changed location between Kubebuilder versions. Be aware of the pat
 5. **Webhook markers** - Usually auto-generated, but verify they match your needs
 
 <aside class="note">
-<h1>Important</h1>
+<h4>Important</h4>
 
 Even if the webhook file is in a different location, the implementation logic remains largely the same.
 Copy the method implementations, not just the entire file.
@@ -647,7 +647,7 @@ Check for additional customizations (Makefile, Dockerfile, test files). Use diff
 
 
 <aside class="note">
-<h1>Using diff tools</h1>
+<h4>Using diff tools</h4>
 
 Use your IDE's diff tools to compare the current directory with your backup (`../migration-backup/`) or use git to compare
 your current branch with your main branch. This helps identify any files you may have missed.
@@ -678,7 +678,7 @@ Deploy to a test cluster (e.g. [kind][kind-doc]) and verify the changes (i.e. va
 
 <aside class="note">
 
-<h1>If You Have a Helm Chart</h1>
+<h4>If You Have a Helm Chart</h4>
 
 If you had a Helm chart to distribute your project, you may want to regenerate it with the [helm/v2-alpha plugin](../plugins/available/helm-v2-alpha.md), then apply your customizations.
 
@@ -726,4 +726,4 @@ as before.
 [standard-go-project]: https://github.com/golang-standards/project-layout
 [kind-doc]: ../reference/kind.md
 [autoupdate-plugin]: ../plugins/available/autoupdate-v1-alpha.md
-[alpha-update]: ../reference/commands/alpha_update.md
+[alpha-update]: ../reference/commands/alpha_update.md
diff --git a/docs/book/src/migration/multi-group.md b/docs/book/src/migration/multi-group.md
@@ -6,7 +6,7 @@ See the [design doc][multigroup-design] for the rationale behind this design dec
 
 <aside class="note">
 
-<h1>What's a Multi-Group Project?</h1>
+<h4>What's a Multi-Group Project?</h4>
 
 Multi-group layout is useful when you're building APIs for different purposes or domains. For example, you might have:
 - A `batch` group for job-related resources (CronJob, Job)
@@ -21,7 +21,7 @@ See [Groups and Versions and Kinds, oh my!][gvks] to better understand API group
 
 <aside class="note">
 
-<h1>AI-Assisted Migration</h1>
+<h4>AI-Assisted Migration</h4>
 
 This migration involves repetitive file moving and import path updates. If you're using an AI coding assistant, see the [AI-Assisted Migration](#ai-assisted-migration) section for ready-to-use instructions.
 
@@ -64,7 +64,7 @@ This command updates your `PROJECT` file by adding `multigroup: true`. After thi
 - **Existing APIs** remain in their current location and must be migrated manually (steps 3-9 below)
 
 <aside class="note">
-<h1>What this command changes</h1>
+<h4>What this command changes</h4>
 
 The command adds or updates this line in your PROJECT file:
 
@@ -260,7 +260,7 @@ If you're using an AI coding assistant (Cursor, GitHub Copilot, etc.), you can a
 
 <aside class="note">
 
-<h1>AI Migration Instructions</h1>
+<h4>AI Migration Instructions</h4>
 
 **Prerequisites:**
 1. First, identify the API group name from `api/v1/groupversion_info.go` (look for `+groupName=<group>.<domain>`)