From a712f98f6586a46beaf0a7757d70c23d9652e437 Mon Sep 17 00:00:00 2001
From: Daniel Maslowski <info@orangecms.org>
Date: Sun, 8 Feb 2026 13:43:04 +0100
Subject: [PATCH] docs: use <h4> instead of <h1> for <aside> notes

There should only be a single highest-level headline, see
https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements#avoid_using_multiple_h1_elements_on_one_page

Regarding aside, https://kb.daisy.org/publishing/docs/html/asides.html
> the first heading level within an `aside` should always be
> one level lower than its containing section.

> If a publisher cannot maintain heading numbering consistency, they
> should try to find another method that users can predict.
> For example, using `h6` for all sidebars.

Most pages have second- and third-level headings, so use fourth
level headings to keep it simple.

Signed-off-by: Daniel Maslowski <info@orangecms.org>
---
 .../src/cronjob-tutorial/cronjob-tutorial.md  |  4 +--
 .../src/cronjob-tutorial/running-webhook.md   |  2 +-
 docs/book/src/cronjob-tutorial/running.md     |  8 ++---
 .../webhook-implementation.md                 |  2 +-
 .../src/cronjob-tutorial/writing-tests.md     |  2 +-
 docs/book/src/faq.md                          |  2 +-
 docs/book/src/getting-started.md              | 16 +++++-----
 docs/book/src/migration/ai-helpers.md         |  2 +-
 docs/book/src/migration/discovery-commands.md |  6 ++--
 docs/book/src/migration/manual-process.md     | 32 +++++++++----------
 docs/book/src/migration/multi-group.md        |  8 ++---
 docs/book/src/migration/port-code.md          |  8 ++---
 docs/book/src/migration/reorganize-layout.md  |  2 +-
 docs/book/src/migrations.md                   | 12 +++----
 .../src/multiversion-tutorial/conversion.md   |  2 +-
 .../src/multiversion-tutorial/deployment.md   |  2 +-
 .../src/multiversion-tutorial/tutorial.md     |  2 +-
 .../plugins/available/autoupdate-v1-alpha.md  |  2 +-
 .../available/deploy-image-plugin-v1-alpha.md |  4 +--
 .../src/plugins/available/go-v4-plugin.md     |  2 +-
 .../src/plugins/available/grafana-v1-alpha.md |  2 +-
 .../src/plugins/available/helm-v1-alpha.md    |  6 ++--
 .../src/plugins/available/kustomize-v2.md     |  4 +--
 docs/book/src/plugins/extending.md            |  2 +-
 .../src/plugins/extending/custom-markers.md   |  2 +-
 .../src/plugins/extending/external-plugins.md |  2 +-
 docs/book/src/plugins/kustomize-v2.md         |  4 +--
 docs/book/src/plugins/plugins-versioning.md   |  2 +-
 docs/book/src/quick-start.md                  | 22 ++++++-------
 docs/book/src/reference/admission-webhook.md  |  2 +-
 docs/book/src/reference/artifacts.md          |  2 +-
 .../src/reference/commands/alpha_generate.md  |  2 +-
 .../src/reference/commands/alpha_update.md    |  2 +-
 docs/book/src/reference/completion.md         |  2 +-
 docs/book/src/reference/controller-gen.md     |  2 +-
 docs/book/src/reference/envtest.md            |  6 ++--
 docs/book/src/reference/good-practices.md     |  2 +-
 docs/book/src/reference/markers.md            |  2 +-
 .../src/reference/markers/crd-validation.md   |  4 +--
 docs/book/src/reference/markers/scaffold.md   |  2 +-
 docs/book/src/reference/metrics.md            |  8 ++---
 docs/book/src/reference/platform.md           |  6 ++--
 docs/book/src/reference/raising-events.md     |  4 +--
 docs/book/src/reference/submodule-layouts.md  |  2 +-
 .../reference/using_an_external_resource.md   |  2 +-
 docs/book/theme/css/markers.css               |  6 ++--
 46 files changed, 111 insertions(+), 111 deletions(-)

diff --git a/docs/book/src/cronjob-tutorial/cronjob-tutorial.md b/docs/book/src/cronjob-tutorial/cronjob-tutorial.md
index f87ae89d94c..430b8e8381b 100644
--- 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
index 0ac135becc5..9652dffefba 100644
--- 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
index 7e745c2c441..f7e53b2190b 100644
--- 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
index ea4b4375a42..cfb41377324 100644
--- 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
index 1c758956c63..4c9614676a4 100644
--- 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
index 3b7a55d7843..ec13b9dd7e9 100644
--- 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
index 90683b2b19b..749bd43d755 100644
--- 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
index 2424330468a..740185c5902 100644
--- 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
index 73254c18667..c1ecfdd74a5 100644
--- 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
index eb63e482527..7436830cf21 100644
--- 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
\ No newline at end of file
+[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
index 5a07d753914..fbe3445f9e6 100644
--- 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>`)
diff --git a/docs/book/src/migration/port-code.md b/docs/book/src/migration/port-code.md
index f78c0a2344e..a83ade74891 100644
--- a/docs/book/src/migration/port-code.md
+++ b/docs/book/src/migration/port-code.md
@@ -4,7 +4,7 @@ After reorganizing your project (Step 1) and executing scaffolding commands from
 
 <aside class="warning">
 
-<h1>Important: Best Effort Only</h1>
+<h4>Important: Best Effort Only</h4>
 
 The AI instructions below are provided as an **example** to help you get started. Due to the complexity and variety of Kubebuilder projects, we **cannot guarantee** it will work perfectly for all projects or be 100% accurate.
 
@@ -20,7 +20,7 @@ The instructions may help you understand how to approach certain migration scena
 
 <aside class="warning">
 
-<h1>Prerequisites</h1>
+<h4>Prerequisites</h4>
 
 Before using these AI instructions:
 1. You've reorganized your project using Step 1 (`make build` succeeds)
@@ -277,7 +277,7 @@ The AI will:
 
 <aside class="warning">
 
-<h1>Manual Review Required</h1>
+<h4>Manual Review Required</h4>
 
 After AI ports the code:
 
@@ -387,7 +387,7 @@ After AI ports your code:
 
 <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 consider regenerate with the [helm/v2-alpha plugin](../plugins/available/helm-v2-alpha.md)
 and then applying your customizations on top.
diff --git a/docs/book/src/migration/reorganize-layout.md b/docs/book/src/migration/reorganize-layout.md
index 655bb1de840..243c72aad07 100644
--- a/docs/book/src/migration/reorganize-layout.md
+++ b/docs/book/src/migration/reorganize-layout.md
@@ -13,7 +13,7 @@ Reorganize files to match the new directory layout.
 
 <aside class="warning">
 
-<h1>Important: Best Effort Only</h1>
+<h4>Important: Best Effort Only</h4>
 
 These AI instructions work for projects using **standard Kubebuilder directory layout**. Projects with heavily customized structures may require manual reorganization.
 
diff --git a/docs/book/src/migrations.md b/docs/book/src/migrations.md
index f264a90d694..841dd2a615d 100644
--- a/docs/book/src/migrations.md
+++ b/docs/book/src/migrations.md
@@ -8,7 +8,7 @@ Migration may involve updating to a newer plugin version (e.g., from `go.kubebui
 Kubebuilder provides multiple migration paths to suit your workflow. Choose the approach that best fits your needs.
 
 <aside class="note">
-<h1>Understanding the PROJECT File</h1>
+<h4>Understanding the PROJECT File</h4>
 
 From Kubebuilder `v3.0.0` onwards, all inputs used by Kubebuilder are tracked in the [PROJECT][project-config] file.
 If you use the CLI to generate your scaffolds, this file will record the project's configuration and metadata,
@@ -22,7 +22,7 @@ which automation tools (alpha update, alpha generate, autoupdate plugin) depend
 </aside>
 
 <aside class="warning">
-<h1>Project Customizations</h1>
+<h4>Project Customizations</h4>
 
 After using the CLI to create your project, you are free to customize the business logic and add features as you see fit.
 However, it is not recommended to deviate from the proposed project layout unless you know what you are doing.
@@ -59,7 +59,7 @@ kubebuilder edit --plugins="autoupdate/v1-alpha"
 ```
 
 <aside class="note">
-<h1>Requirements and Limitations</h1>
+<h4>Requirements and Limitations</h4>
 
 - Requires GitHub repository (GitHub Actions workflow)
 - Requires branch protection rules for safety (recommended)
@@ -82,7 +82,7 @@ This command uses the same underlying mechanism as the AutoUpdate Plugin. You ca
 resolve any conflicts if needed, and then push a Pull Request from your local environment.
 
 <aside class="note">
-<h1>Requirements and Limitations</h1>
+<h4>Requirements and Limitations</h4>
 
 - Requires projects created with Kubebuilder **`v4.5.0`** or later
 - For projects created before `v4.6.0`: the CLI version is not tracked in the `PROJECT` file, so you may need to use `alpha generate` first to establish a baseline
@@ -109,7 +109,7 @@ kubebuilder alpha generate
 ```
 
 <aside class="note">
-<h1>Requirements and Limitations</h1>
+<h4>Requirements and Limitations</h4>
 
 - Requires a `PROJECT` file (projects created with Kubebuilder **v3.0.0** or later)
 - Only re-scaffolds resources that were created using the CLI and tracked in the `PROJECT` file
@@ -132,7 +132,7 @@ webhooks, and other resources. Then, manually copy your business logic and custo
 To streamline this one-time migration, [AI Migration Helpers](./migration/ai-helpers.md) have been added to automate repetitive tasks.
 
 <aside class="note">
-<h1>When to Use Manual Migration</h1>
+<h4>When to Use Manual Migration</h4>
 
 Use this approach when:
 - Your project was created with Kubebuilder versions **before `v3.0.0`** (no `PROJECT` file)
diff --git a/docs/book/src/multiversion-tutorial/conversion.md b/docs/book/src/multiversion-tutorial/conversion.md
index 4166992e419..a9982295e75 100644
--- a/docs/book/src/multiversion-tutorial/conversion.md
+++ b/docs/book/src/multiversion-tutorial/conversion.md
@@ -14,7 +14,7 @@ The above command will generate the `cronjob_conversion.go` next to our
 cluttering up our main types file with extra functions.
 
 <aside class="note">
-<h1>Conversion Webhooks and Custom Paths</h1>
+<h4>Conversion Webhooks and Custom Paths</h4>
 
 Unlike defaulting and validation webhooks, conversion webhooks do not support custom paths
 via command-line flags. Conversion webhooks use CRD conversion configuration
diff --git a/docs/book/src/multiversion-tutorial/deployment.md b/docs/book/src/multiversion-tutorial/deployment.md
index 617f0b35dd7..4e2bef0b55f 100644
--- a/docs/book/src/multiversion-tutorial/deployment.md
+++ b/docs/book/src/multiversion-tutorial/deployment.md
@@ -83,7 +83,7 @@ reconcile, even though our controller is written against our v1 API version.
 
 <aside class="note">
 
-<h1>kubectl and Preferred Versions</h1>
+<h4>kubectl and Preferred Versions</h4>
 
 When we access our API types from Go code, we ask for a specific version
 by using that version's Go type (e.g. `batchv2.CronJob`).
diff --git a/docs/book/src/multiversion-tutorial/tutorial.md b/docs/book/src/multiversion-tutorial/tutorial.md
index 192b7498a08..3f9a0c36100 100644
--- a/docs/book/src/multiversion-tutorial/tutorial.md
+++ b/docs/book/src/multiversion-tutorial/tutorial.md
@@ -13,7 +13,7 @@ Tutorial](/cronjob-tutorial/cronjob-tutorial.md).
 
 <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:
diff --git a/docs/book/src/plugins/available/autoupdate-v1-alpha.md b/docs/book/src/plugins/available/autoupdate-v1-alpha.md
index 9ad2847ed00..6bd31d4096c 100644
--- a/docs/book/src/plugins/available/autoupdate-v1-alpha.md
+++ b/docs/book/src/plugins/available/autoupdate-v1-alpha.md
@@ -48,7 +48,7 @@ kubebuilder edit --plugins="autoupdate/v1-alpha" --use-gh-models
 ```
 
 <aside class="note">
-<h1>Permissions required to use GitHub Models in GitHub Actions</h1>
+<h4>Permissions required to use GitHub Models in GitHub Actions</h4>
 
 To use GitHub Models in your workflows, organization and repository administrators must grant this permission.
 
diff --git a/docs/book/src/plugins/available/deploy-image-plugin-v1-alpha.md b/docs/book/src/plugins/available/deploy-image-plugin-v1-alpha.md
index cfa88033e98..6a76afdbc5d 100644
--- a/docs/book/src/plugins/available/deploy-image-plugin-v1-alpha.md
+++ b/docs/book/src/plugins/available/deploy-image-plugin-v1-alpha.md
@@ -10,7 +10,7 @@ By using this plugin, you will get:
 - Environment variable support for managing the Operand (image) within the manager.
 
 <aside class="note">
-<h1>Examples</h1>
+<h4>Examples</h4>
 
 See the `project-v4-with-plugins` directory under the [testdata][testdata]
 directory in the Kubebuilder project to check an example
@@ -66,7 +66,7 @@ kubebuilder create api \
    ```
 
 <aside class="warning">
-<h1>Note on make run:</h1>
+<h4>Note on make run:</h4>
 
 When running the project locally with `make run`, the Operand image
 provided will be stored as an environment variable in the
diff --git a/docs/book/src/plugins/available/go-v4-plugin.md b/docs/book/src/plugins/available/go-v4-plugin.md
index b16b21034bf..006fb04b378 100644
--- a/docs/book/src/plugins/available/go-v4-plugin.md
+++ b/docs/book/src/plugins/available/go-v4-plugin.md
@@ -11,7 +11,7 @@ By following the [quickstart][quickstart] and creating any project,
 you will be using this plugin by default.
 
 <aside class="note">
-<h1>Examples</h1>
+<h4>Examples</h4>
 
 You can check samples using this plugin by looking at the `project-v4-<options>` projects under the [testdata][testdata]
 directory on the root directory of the Kubebuilder project.
diff --git a/docs/book/src/plugins/available/grafana-v1-alpha.md b/docs/book/src/plugins/available/grafana-v1-alpha.md
index d086fe17f09..a9a8b2d6776 100644
--- a/docs/book/src/plugins/available/grafana-v1-alpha.md
+++ b/docs/book/src/plugins/available/grafana-v1-alpha.md
@@ -6,7 +6,7 @@ default metrics which are exported by projects
 using [controller-runtime][controller-runtime].
 
 <aside class="note">
-<h1>Examples</h1>
+<h4>Examples</h4>
 
 You can check its default scaffold by looking at the `project-v4-with-plugins` projects
 under the [testdata][testdata] directory on the root directory of the Kubebuilder project.
diff --git a/docs/book/src/plugins/available/helm-v1-alpha.md b/docs/book/src/plugins/available/helm-v1-alpha.md
index a27f3ea8b72..6b56624c7cd 100644
--- a/docs/book/src/plugins/available/helm-v1-alpha.md
+++ b/docs/book/src/plugins/available/helm-v1-alpha.md
@@ -1,7 +1,7 @@
 # Helm Plugin (`helm/v1-alpha`) - **DEPRECATED**
 
 <aside class="warning">
-<h1> Deprecated Plugin</h1>
+<h4> Deprecated Plugin</h4>
 
 The `helm/v1-alpha` plugin is **deprecated**. Please use [`helm/v2-alpha`](./helm-v2-alpha.md) instead.
 
@@ -31,7 +31,7 @@ However, in many scenarios, you might prefer to provide a Helm chart to package
 If so, you can use this plugin to generate the Helm chart under the `dist` directory.
 
 <aside class="note">
-<h1>Examples</h1>
+<h4>Examples</h4>
 
 You can check the plugin usage by looking at `project-v4-with-plugins` samples
 under the [testdata][testdata] directory on the root directory of the Kubebuilder project.
@@ -93,7 +93,7 @@ make manifests
 kubebuilder edit --plugins=helm/v1-alpha
 ```
 <aside class="note">
-  <h1>Use the edit command to update the Helm Chart with the latest changes</h1>
+  <h4>Use the edit command to update the Helm Chart with the latest changes</h4>
 
   After making changes to your project, ensure that you run `make manifests` and then
   use the command `kubebuilder edit --plugins=helm/v1-alpha` to update the Helm Chart.
diff --git a/docs/book/src/plugins/available/kustomize-v2.md b/docs/book/src/plugins/available/kustomize-v2.md
index 929b96457ed..deb6daea686 100644
--- a/docs/book/src/plugins/available/kustomize-v2.md
+++ b/docs/book/src/plugins/available/kustomize-v2.md
@@ -17,7 +17,7 @@ creation of "helper" plugins that work with different projects
 and languages.
 
 <aside class="note">
-<h1>Examples</h1>
+<h4>Examples</h4>
 
 You can check the kustomize content by looking at the `config/` directory provided in the sample `project-v4-*`
 under the [testdata][testdata] directory of the Kubebuilder project.
@@ -73,7 +73,7 @@ The kustomize plugin implements the following subcommands:
 * create webhook (`$ kubebuilder create api [OPTIONS]`)
 
 <aside class="note">
-<h1>Create API and Webhook</h1>
+<h4>Create API and Webhook</h4>
 
 The implementation for the `create api` subcommand scaffolds the kustomize
 manifests specific to each API. See more [here][kustomize-create-api].
diff --git a/docs/book/src/plugins/extending.md b/docs/book/src/plugins/extending.md
index fb5b5e75aea..4d95c292c9f 100644
--- a/docs/book/src/plugins/extending.md
+++ b/docs/book/src/plugins/extending.md
@@ -16,7 +16,7 @@ This flexibility enables you to create custom project
 setups tailored to specific needs.
 
 <aside class="note">
-<h1>Why use the Kubebuilder style?</h1>
+<h4>Why use the Kubebuilder style?</h4>
 
 Kubebuilder and SDK are both broadly adopted projects which leverage the [controller-runtime][controller-runtime] project. They both allow users to build solutions using the [Operator Pattern][operator-pattern] and follow common standards.
 
diff --git a/docs/book/src/plugins/extending/custom-markers.md b/docs/book/src/plugins/extending/custom-markers.md
index 69adfe02322..4ecc9759b01 100644
--- a/docs/book/src/plugins/extending/custom-markers.md
+++ b/docs/book/src/plugins/extending/custom-markers.md
@@ -78,7 +78,7 @@ func formatPrefix(prefix string) string {
 ```
 
 <aside class="note">
-<h1>Implementation Reference</h1>
+<h4>Implementation Reference</h4>
 
 The `formatPrefix` implementation shown above is adapted from Kubebuilder's internal
 [markerPrefix function](https://github.com/kubernetes-sigs/kubebuilder/blob/master/pkg/machinery/marker.go).
diff --git a/docs/book/src/plugins/extending/external-plugins.md b/docs/book/src/plugins/extending/external-plugins.md
index 49126066620..c9de9f7e76d 100644
--- a/docs/book/src/plugins/extending/external-plugins.md
+++ b/docs/book/src/plugins/extending/external-plugins.md
@@ -140,7 +140,7 @@ External plugins can support the following Kubebuilder subcommands:
 - `flags`: Inform Kubebuilder of supported flags, enabling early error detection.
 
 <aside class="note">
-<h1>More about `flags` subcommand</h1>
+<h4>More about `flags` subcommand</h4>
 
 The `flags` subcommand in an external plugin allows for early error detection by informing Kubebuilder about the flags the plugin supports. If an unsupported flag is identified, Kubebuilder can issue an error before the plugin is called to execute.
 If a plugin does not implement the `flags` subcommand, Kubebuilder will pass all flags to the plugin, making it the external plugin's responsibility to handle any invalid flags.
diff --git a/docs/book/src/plugins/kustomize-v2.md b/docs/book/src/plugins/kustomize-v2.md
index 03d0e6f3d56..001c59065a8 100644
--- a/docs/book/src/plugins/kustomize-v2.md
+++ b/docs/book/src/plugins/kustomize-v2.md
@@ -11,7 +11,7 @@ which uses the same and we are also
 able to create "helper" plugins which can work with many projects and languages.
 
 <aside class="note">
-<h1>Examples</h1>
+<h4>Examples</h4>
 
 You can check the kustomize content by looking at the `config/` directory provide on the sample `project-v4-*` under the [testdata][testdata]
 directory of the Kubebuilder project.
@@ -81,7 +81,7 @@ The kustomize plugin implements the following subcommands:
 * create webhook (`$ kubebuilder create api [OPTIONS]`)
 
 <aside class="note">
-<h1>Create API and Webhook</h1>
+<h4>Create API and Webhook</h4>
 
 Its implementation for the subcommand create api will scaffold the kustomize manifests
 which are specific for each API, see [here][kustomize-create-api]. The same applies
diff --git a/docs/book/src/plugins/plugins-versioning.md b/docs/book/src/plugins/plugins-versioning.md
index a0a34dada38..288c6a6ef55 100644
--- a/docs/book/src/plugins/plugins-versioning.md
+++ b/docs/book/src/plugins/plugins-versioning.md
@@ -30,7 +30,7 @@ for users to upgrade their projects from `vX` to `v(X+1)-alpha`.
 
 <aside class="note">
 
-<h1>Example</h1>
+<h4>Example</h4>
 
 Kubebuilder scaffolds projects with plugin `go.kubebuilder.io/v4` by default.
 
diff --git a/docs/book/src/quick-start.md b/docs/book/src/quick-start.md
index b1a2b47107d..6e840ea7e06 100644
--- a/docs/book/src/quick-start.md
+++ b/docs/book/src/quick-start.md
@@ -15,7 +15,7 @@ This Quick Start guide will cover:
 - Access to a Kubernetes v1.11.3+ cluster.
 
 <aside class="note">
-<h1>Versions Compatibility and Supportability</h1>
+<h4>Versions Compatibility and Supportability</h4>
 
 Please, ensure that you see the [guidance](./versions_compatibility_supportability.md).
 
@@ -32,7 +32,7 @@ chmod +x kubebuilder && sudo mv kubebuilder /usr/local/bin/
 ```
 
 <aside class="note">
-<h1>Using the Master Branch</h1>
+<h4>Using the Master Branch</h4>
 
 You can work with the master branch by cloning the repository and running `make install` to generate the binary.
 Please follow the steps in the section **How to Build Kubebuilder Locally** from the [Contributing Guide](https://github.com/kubernetes-sigs/kubebuilder/blob/master/CONTRIBUTING.md#how-to-build-kubebuilder-locally).
@@ -40,7 +40,7 @@ Please follow the steps in the section **How to Build Kubebuilder Locally** from
 </aside>
 
 <aside class="note">
-<h1>Enabling shell autocompletion</h1>
+<h4>Enabling shell autocompletion</h4>
 
 Kubebuilder provides autocompletion support via the command `kubebuilder completion <bash|fish|powershell|zsh>`, which can save you a lot of typing. For further information see the [completion](./reference/completion.md) document.
 
@@ -57,7 +57,7 @@ kubebuilder init --domain my.domain --repo my.domain/guestbook
 ```
 
 <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.
@@ -75,7 +75,7 @@ kubebuilder create api --group webapp --version v1 --kind Guestbook
 ```
 
 <aside class="note">
-<h1>Press Options</h1>
+<h4>Press Options</h4>
 
 If you press `y` for Create Resource [y/n] and for Create Controller [y/n] then this will create the files `api/v1/guestbook_types.go` where the API is defined
 and the `internal/controller/guestbook_controller.go` where the reconciliation business logic is implemented for this Kind(CRD).
@@ -146,7 +146,7 @@ type Guestbook struct {
 
 
 <aside class="note">
-<h1> `+kubebuilder` markers </h1>
+<h4> `+kubebuilder` markers </h4>
 
 `+kubebuilder` are [markers][markers] processed by [controller-gen][controller-gen]
 to generate CRDs and RBAC. Kubebuilder also provides [scaffolding markers][scaffolding-markers]
@@ -161,7 +161,7 @@ You'll need a Kubernetes cluster to run against. You can use
 run against a remote cluster.
 
 <aside class="note">
-<h1>Context Used</h1>
+<h4>Context Used</h4>
 
 Your controller will automatically use the current context in your
 kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows).
@@ -229,7 +229,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.
@@ -245,7 +245,7 @@ kind load docker-image <your-image-name>:tag --name <your-kind-cluster-name>
 It is highly recommended to use [Kind][kind] for development purposes and CI.
 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.
@@ -273,7 +273,7 @@ Kubebuilder design is based on [Plugins][plugins] and you can use
 [available plugins][available-plugins] to add optional features to your project.
 
 <aside class="note">
-<h1>References and Examples</h1>
+<h4>References and Examples</h4>
 
 Use the [Deploy Image Plugin (deploy-image/v1-alpha)][deploy-image-v1-alpha] as a reference when creating your project. It follows Kubernetes conventions and recommended good practices. For example:
 
@@ -284,7 +284,7 @@ kubebuilder create api --group webapp --version v1alpha1 --kind Busybox --image=
 </aside>
 
 <aside class="note">
-<h1> Keeping your project up to date with ecosystem changes </h1>
+<h4> Keeping your project up to date with ecosystem changes </h4>
 
 Use [AutoUpdate Plugin][autoupdate-v1-alpha] to keep your project
 aligned with the latest ecosystem changes. When a new release is available,
diff --git a/docs/book/src/reference/admission-webhook.md b/docs/book/src/reference/admission-webhook.md
index 222d49f7437..73c63d9913f 100644
--- a/docs/book/src/reference/admission-webhook.md
+++ b/docs/book/src/reference/admission-webhook.md
@@ -54,7 +54,7 @@ kubebuilder create webhook --group batch --version v1 --kind CronJob \
 ```
 
 <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 follows a
 fixed pattern based on the resource's group, version, and kind, and cannot be customized.
diff --git a/docs/book/src/reference/artifacts.md b/docs/book/src/reference/artifacts.md
index 03ef63a9ba9..f161c862fcb 100644
--- a/docs/book/src/reference/artifacts.md
+++ b/docs/book/src/reference/artifacts.md
@@ -17,7 +17,7 @@ When you run `make envtest` or `make test`, the necessary tarballs are downloade
 configured for your project.
 
 <aside class="note">
-<h1>Setup ENV TEST tool</h1>
+<h4>Setup ENV TEST tool</h4>
 
 To learn more about the tooling used to configure ENVTEST, which is utilized in the `setup-envtest`
 target in the Makefile of projects built with Kubebuilder, see the [README](https://github.com/kubernetes-sigs/controller-runtime/blob/main/tools/setup-envtest/README.md)
diff --git a/docs/book/src/reference/commands/alpha_generate.md b/docs/book/src/reference/commands/alpha_generate.md
index 46c79163d08..36c2fa96818 100644
--- a/docs/book/src/reference/commands/alpha_generate.md
+++ b/docs/book/src/reference/commands/alpha_generate.md
@@ -39,7 +39,7 @@ This approach allows you to compare changes between your current branch and upst
 scaffold updates (e.g., from the main branch), and helps you overlay custom code atop the new scaffold.
 
 <aside class="note tip">
-<h1>Looking for a more automated migration?</h1>
+<h4>Looking for a more automated migration?</h4>
 
 If you want to upgrade your project scaffold with less manual work,
 try [`kubebuilder alpha update`](./alpha_update.md).
diff --git a/docs/book/src/reference/commands/alpha_update.md b/docs/book/src/reference/commands/alpha_update.md
index e5e46d91c0c..11c8ec6d35e 100644
--- a/docs/book/src/reference/commands/alpha_update.md
+++ b/docs/book/src/reference/commands/alpha_update.md
@@ -255,7 +255,7 @@ We use that value to pick the correct CLI for re-scaffolding.
 <iframe width="560" height="315" src="https://www.youtube.com/embed/J8zonID__8k?si=WC-FXOHX0mCjph71" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
 <aside class="note">
-<h1>About this demo</h1>
+<h4>About this demo</h4>
 
 This video was recorded with Kubebuilder release `v7.0.1`.
 Since then, the command has been improved,
diff --git a/docs/book/src/reference/completion.md b/docs/book/src/reference/completion.md
index 507474bc1f3..79aac9e8586 100644
--- a/docs/book/src/reference/completion.md
+++ b/docs/book/src/reference/completion.md
@@ -5,7 +5,7 @@ Note that sourcing the completion script in your shell enables Kubebuilder autoc
 ## Bash
 
 <aside class="note">
-<h1>Prerequisites for Bash</h1>
+<h4>Prerequisites for Bash</h4>
 
 The completion Bash script depends on [bash-completion](https://github.com/scop/bash-completion), which means that you have to install this software first (you can test if you have bash-completion already installed). Also, ensure that your Bash version is 4.1+.
 
diff --git a/docs/book/src/reference/controller-gen.md b/docs/book/src/reference/controller-gen.md
index 97225650ca3..057f94a117c 100644
--- a/docs/book/src/reference/controller-gen.md
+++ b/docs/book/src/reference/controller-gen.md
@@ -39,7 +39,7 @@ plus per-generator overrides (specified as `output:<generator>:<rule>`).
 
 <aside class="note">
 
-<h1>Default Rules</h1>
+<h4>Default Rules</h4>
 
 When no fallback rule is specified manually, a set of default
 per-generator rules are used which result in YAML going to
diff --git a/docs/book/src/reference/envtest.md b/docs/book/src/reference/envtest.md
index 757efd7ca6d..f8ab64ad37c 100644
--- a/docs/book/src/reference/envtest.md
+++ b/docs/book/src/reference/envtest.md
@@ -96,7 +96,7 @@ err = testEnv.Stop()
 Logs from the test runs are prefixed with `test-env`.
 
 <aside class="note">
-<h1>Examples</h1>
+<h4>Examples</h4>
 
 You can use the plugin [DeployImage](../plugins/available/deploy-image-plugin-v1-alpha.md) to check examples. This plugin allows users to scaffold API/Controllers to deploy and manage an Operand (image) on the cluster following the guidelines and best practices. It abstracts the complexities of achieving this goal while allowing users to customize the generated code.
 
@@ -160,7 +160,7 @@ var _ = AfterSuite(func() {
 ```
 
 <aside class="note">
-<h1>ENV TEST Config Options</h1>
+<h4>ENV TEST Config Options</h4>
 
 You can look at the controller-runtime docs to know more about its configuration options, see [here](https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/envtest#Environment). On top of that, if you are
 looking to use ENV TEST to test your webhooks then you might want to give a look at its install [options](https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/envtest#WebhookInstallOptions).
@@ -343,7 +343,7 @@ testEnv = &envtest.Environment{
 ```
 
 <aside class="note">
-<h1>Setup ENV TEST tool</h1>
+<h4>Setup ENV TEST tool</h4>
 To know more about the tooling used to configure ENVTEST which is used in the setup-envtest target in the Makefile
 of the projects build with Kubebuilder see the [README][readme]
 of its tooling.
diff --git a/docs/book/src/reference/good-practices.md b/docs/book/src/reference/good-practices.md
index 70b0e574632..b7e9de773c5 100644
--- a/docs/book/src/reference/good-practices.md
+++ b/docs/book/src/reference/good-practices.md
@@ -56,7 +56,7 @@ We recommend you manage your solutions using Status Conditionals following the [
 - **Compatibility**: By adopting the common pattern of using conditions in Kubernetes APIs, Operator authors ensure their custom resources align with the broader ecosystem, which helps users to have a consistent experience when interacting with multiple Operators and resources in their clusters.
 
 <aside class="note">
-<h1> Example of Usage </h1>
+<h4> Example of Usage </h4>
 
 Check out the [Deploy Image Plugin][deploy-image]. This plugin allows users to scaffold API/Controllers to deploy and manage an Operand (image) on the cluster following the guidelines and best practices. It abstracts the
 complexities of achieving this goal while allowing users to customize the generated code.
diff --git a/docs/book/src/reference/markers.md b/docs/book/src/reference/markers.md
index 0520717b0f2..a9927a64ae4 100644
--- a/docs/book/src/reference/markers.md
+++ b/docs/book/src/reference/markers.md
@@ -16,7 +16,7 @@ a marker name, optionally followed by some marker specific configuration:
 ```
 
 <aside class="note">
-<h1>difference between <code>// +optional</code> and <code>// +kubebuilder:validation:Optional</code></h1>
+<h4>difference between <code>// +optional</code> and <code>// +kubebuilder:validation:Optional</code></h4>
 
 Controller-gen supports both (see the output of `controller-gen crd -www`). `+kubebuilder:validation:Optional` and `+optional` can be applied to fields.
 
diff --git a/docs/book/src/reference/markers/crd-validation.md b/docs/book/src/reference/markers/crd-validation.md
index e9a890b9c79..27b7e8ff563 100644
--- a/docs/book/src/reference/markers/crd-validation.md
+++ b/docs/book/src/reference/markers/crd-validation.md
@@ -7,7 +7,7 @@ schema option.
 See [Generating CRDs](/reference/generating-crd.md) for examples.
 
 <aside class="note">
-<h1>Understanding Marker Grouping in Documentation</h1>
+<h4>Understanding Marker Grouping in Documentation</h4>
 
 Certain markers may seem duplicated. However, these markers are grouped based on their context of use
 — such as fields, types, or arrays. For instance, a marker like `+kubebuilder:validation:Enum` can be applied to
@@ -18,7 +18,7 @@ The grouping ensures clarity by showing how the same marker can be reused for di
 </aside>
 
 <aside class="note">
-<h1>Schema & Validation</h1>
+<h4>Schema & Validation</h4>
 
 Custom resources are validated using the generated OpenAPI v3 schema and must comply with Kubernetes structural schema rules.
 Only field types and constraints that can be represented in the CRD schema are enforced by the API server.
diff --git a/docs/book/src/reference/markers/scaffold.md b/docs/book/src/reference/markers/scaffold.md
index 2068a77b9d8..582e189d6ae 100644
--- a/docs/book/src/reference/markers/scaffold.md
+++ b/docs/book/src/reference/markers/scaffold.md
@@ -165,7 +165,7 @@ For further guidance, you can refer to examples in the `testdata/` directory in
 </aside>
 
 <aside class="note">
-<h1>Creating Your Own Markers</h1>
+<h4>Creating Your Own Markers</h4>
 
 If you are using Kubebuilder as a library to create [your own plugins](./../../plugins/creating-plugins.md) and extend its CLI functionalities,
 you have the flexibility to define and use your own markers. To implement your own markers, refer to the [kubebuilder/v4/pkg/machinery](https://pkg.go.dev/sigs.k8s.io/kubebuilder/v4/pkg/machinery),
diff --git a/docs/book/src/reference/metrics.md b/docs/book/src/reference/metrics.md
index a93e21f9c30..b4998429c0e 100644
--- a/docs/book/src/reference/metrics.md
+++ b/docs/book/src/reference/metrics.md
@@ -241,7 +241,7 @@ spec:
 ### **(Recommended)** Enabling certificates for Production (Disabled by default)
 
 <aside class="warning">
-<h1>Why Is This Not Enabled by Default?</h1>
+<h4>Why Is This Not Enabled by Default?</h4>
 
 This option is not enabled by default because it introduces a dependency on CertManager.
 To keep the project as lightweight and beginner-friendly as possible, it is disabled by default.
@@ -249,7 +249,7 @@ To keep the project as lightweight and beginner-friendly as possible, it is disa
 </aside>
 
 <aside class="warning">
-<h1>Recommended for Production</h1>
+<h4>Recommended for Production</h4>
 
 The default scaffold in `cmd/main.go` uses a **controller-runtime feature** to
 automatically generate a self-signed certificate to secure the metrics server.
@@ -456,7 +456,7 @@ You may then record metrics to those collectors from any part of your
 reconcile loop. These metrics can be evaluated from anywhere in the operator code.
 
 <aside class="note">
-<h1>Enabling metrics in Prometheus UI</h1>
+<h4>Enabling metrics in Prometheus UI</h4>
 
 In order to publish metrics and view them on the Prometheus UI, the Prometheus instance would have to be configured to select the Service Monitor instance based on its labels.
 
@@ -468,7 +468,7 @@ other openmetrics systems to scrape.
 ![Screen Shot 2021-06-14 at 10 15 59 AM](https://user-images.githubusercontent.com/37827279/121932262-8843cd80-ccf9-11eb-9c8e-98d0eda80169.png)
 
 <aside class="note">
-<h1>Controller-Runtime Auth/Authz Feature Current Known Limitations and Considerations</h1>
+<h4>Controller-Runtime Auth/Authz Feature Current Known Limitations and Considerations</h4>
 
 Some known limitations and considerations have been identified. The settings for `cache TTL`, `anonymous access`, and
 `timeouts` are currently hardcoded, which may lead to performance and security concerns due to the inability to
diff --git a/docs/book/src/reference/platform.md b/docs/book/src/reference/platform.md
index 9f2fddb3f21..6ee6c4b5cc3 100644
--- a/docs/book/src/reference/platform.md
+++ b/docs/book/src/reference/platform.md
@@ -131,7 +131,7 @@ Template: corev1.PodTemplateSpec{
 ```
 
 <aside class="note">
-<h1> Example(s) </h1>
+<h4> Example(s) </h4>
 
 You can look for some code examples by checking the code which is generated via the Deploy
 Image plugin. ([More info](../plugins/available/deploy-image-plugin-v1-alpha.md))
@@ -177,7 +177,7 @@ Therefore, ensure that you uncomment the following code in the `config/manager/m
 ```
 
 <aside class="note">
-<h1>Building images for releases</h1>
+<h4>Building images for releases</h4>
 
 You will probably want to automate the releases of your projects to ensure that the images are always built for the
 same platforms. Note that Goreleaser also supports [docker buildx][buildx]. See its [documentation][goreleaser-buildx] for more detail.
@@ -209,7 +209,7 @@ an image will be built from the client host (local environment) and produce an i
 the client os/arch, which is commonly linux/amd64 or linux/arm64.
 
 <aside class="note">
-<h1>Mac Os</h1>
+<h4>Mac Os</h4>
 
 If you are running from an Mac Os environment then, Docker also will consider it as linux/$arch. Be aware that
 when, for example, is running Kind on a Mac OS operational system the nodes will
diff --git a/docs/book/src/reference/raising-events.md b/docs/book/src/reference/raising-events.md
index 91954d8e1a1..4477db2f195 100644
--- a/docs/book/src/reference/raising-events.md
+++ b/docs/book/src/reference/raising-events.md
@@ -5,7 +5,7 @@ It is often useful to publish *Event* objects from the controller Reconcile func
  Recent Events for an object can be viewed by running `$ kubectl describe <resource kind> <resource name>`. Also, they can be checked by running `$ kubectl get events`.
 
 <aside class="warning">
-<h1>Events should be raised in certain circumstances only</h1>
+<h4>Events should be raised in certain circumstances only</h4>
 
 Be aware that it is **not** recommended to emit Events for all operations. If authors raise too many events, it brings bad UX experiences for those consuming the solutions on the cluster, and they may find it difficult to filter an actionable event from the cluster. For more information, please take a look at the [Kubernetes APIs convention][Events].
 
@@ -29,7 +29,7 @@ Eventf(regarding, related runtime.Object, eventtype, reason, action, message str
 
 
 <aside class="note">
-<h1>Example Usage</h1>
+<h4>Example Usage</h4>
 
 Following is an example of a code implementation that raises an Event.
 
diff --git a/docs/book/src/reference/submodule-layouts.md b/docs/book/src/reference/submodule-layouts.md
index ed67b18a862..b995dd80a90 100644
--- a/docs/book/src/reference/submodule-layouts.md
+++ b/docs/book/src/reference/submodule-layouts.md
@@ -5,7 +5,7 @@ This part describes how to modify a scaffolded project for use with multiple `go
 Sub-Module Layouts (in a way you could call them a special form of [Monorepo's][monorepo]) are a special use case and can help in scenarios that involve reuse of APIs without introducing indirect dependencies that should not be available in the project consuming the API externally.
 
 <aside class="note">
-<h1>Using External Resources/APIs</h1>
+<h4>Using External Resources/APIs</h4>
 
 If you are looking to do operations and reconcile via a controller a Type(CRD) which are owned by another project
 or By Kubernetes API then, please see [Using an external Resources/API](/reference/using_an_external_type.md)
diff --git a/docs/book/src/reference/using_an_external_resource.md b/docs/book/src/reference/using_an_external_resource.md
index 9234999d664..e104df262a6 100644
--- a/docs/book/src/reference/using_an_external_resource.md
+++ b/docs/book/src/reference/using_an_external_resource.md
@@ -32,7 +32,7 @@ kubebuilder create api --group certmanager --version v1 --kind Certificate --con
 ```
 
 <aside class="note">
-<h1>Pinning External API Versions</h1>
+<h4>Pinning External API Versions</h4>
 
 You can pin a specific version of the external API dependency using the `--external-api-module` flag:
 
diff --git a/docs/book/theme/css/markers.css b/docs/book/theme/css/markers.css
index 0a7ab272f7f..701b7ef1ea2 100644
--- a/docs/book/theme/css/markers.css
+++ b/docs/book/theme/css/markers.css
@@ -338,7 +338,7 @@ aside.note > * {
 }
 
 /* note title */
-aside.note > h1 {
+aside.note > h4 {
     border-bottom: 1px solid var(--searchbar-border-color);
     margin: 0;
     padding: 0.5em 1em;
@@ -348,10 +348,10 @@ aside.note > h1 {
 }
 
 /* warning notes */
-aside.note.warning > h1 {
+aside.note.warning > h4 {
     background: var(--warning-note-background-color, #fcf8f2);
 }
-aside.note.warning > h1::before {
+aside.note.warning > h4 {
     /* TODO(directxman12): fill in these colors in theme.
      * If you're good with colors, feel free to play around with this
      * in dark mode. */