diff --git a/data/buildx/docker_buildx_build.yaml b/data/buildx/docker_buildx_build.yaml
index 19918ff662..b9e032dcf7 100644
--- a/data/buildx/docker_buildx_build.yaml
+++ b/data/buildx/docker_buildx_build.yaml
@@ -39,6 +39,7 @@ options:
       value_type: stringArray
       default_value: '[]'
       description: Add annotation to the image
+      details_url: '#annotation'
       deprecated: false
       hidden: false
       experimental: false
@@ -526,6 +527,52 @@ inherited_options:
       kubernetes: false
       swarm: false
 examples: |-
+    ### Create annotations (--annotation) {#annotation}
+
+    ```text
+    --annotation="key=value"
+    --annotation="[type:]key=value"
+    ```
+
+    Add OCI annotations to the image index, manifest, or descriptor.
+    The following example adds the `foo=bar` annotation to the image manifests:
+
+    ```console
+    $ docker buildx build -t TAG --annotation "foo=bar" --push .
+    ```
+
+    You can optionally add a type prefix to specify the level of the annotation. By
+    default, the image manifest is annotated. The following example adds the
+    `foo=bar` annotation the image index instead of the manifests:
+
+    ```console
+    $ docker buildx build -t TAG --annotation "index:foo=bar" --push .
+    ```
+
+    You can specify multiple types, separated by a comma (,) to add the annotation
+    to multiple image components. The following example adds the `foo=bar`
+    annotation to image index, descriptors, manifests:
+
+    ```console
+    $ docker buildx build -t TAG --annotation "index,manifest,manifest-descriptor:foo=bar" --push .
+    ```
+
+    You can also specify a platform qualifier in square brackets (`[os/arch]`) in
+    the type prefix, to apply the annotation to a subset of manifests with the
+    matching platform. The following example adds the `foo=bar` annotation only to
+    the manifest with the `linux/amd64` platform:
+
+    ```console
+    $ docker buildx build -t TAG --annotation "manifest[linux/amd64]:foo=bar" --push .
+    ```
+
+    Wildcards are not supported in the platform qualifier; you can't specify a type
+    prefix like `manifest[linux/*]` to add annotations only to manifests which has
+    `linux` as the OS platform.
+
+    For more information about annotations, see
+    [Annotations](/build/building/annotations/).
+
     ### Create attestations (--attest) {#attest}
 
     ```text
diff --git a/data/buildx/docker_buildx_imagetools_create.yaml b/data/buildx/docker_buildx_imagetools_create.yaml
index 4a5104282e..67ec9d5a21 100644
--- a/data/buildx/docker_buildx_imagetools_create.yaml
+++ b/data/buildx/docker_buildx_imagetools_create.yaml
@@ -13,6 +13,7 @@ options:
       value_type: stringArray
       default_value: '[]'
       description: Add annotation to the image
+      details_url: '#annotation'
       deprecated: false
       hidden: false
       experimental: false
@@ -88,6 +89,34 @@ inherited_options:
       kubernetes: false
       swarm: false
 examples: |-
+    ### Add annotations to an image (--annotation) {#annotation}
+
+    The `--annotation` flag lets you add annotations the image index, manifest,
+    and descriptors when creating a new image.
+
+    The following command creates a `foo/bar:latest` image with the
+    `org.opencontainers.image.authors` annotation on the image index.
+
+    ```console
+    $ docker buildx imagetools create \
+      --annotation "index:org.opencontainers.image.authors=dvdksn" \
+      --tag foo/bar:latest \
+      foo/bar:alpha foo/bar:beta foo/bar:gamma
+    ```
+
+    > **Note**
+    >
+    > The `imagetools create` command supports adding annotations to the image
+    > index and descriptor, using the following type prefixes:
+    >
+    > - `index:`
+    > - `manifest-descriptor:`
+    >
+    > It doesn't support annotating manifests or OCI layouts.
+
+    For more information about annotations, see
+    [Annotations](/build/building/annotations/).
+
     ### Append new sources to an existing manifest list (--append) {#append}
 
     Use the `--append` flag to append the new sources to an existing manifest list
@@ -103,7 +132,7 @@ examples: |-
 
     ### Read source descriptor from a file (-f, --file) {#file}
 
-    ```
+    ```text
     -f FILE or --file FILE
     ```
 
@@ -124,7 +153,7 @@ examples: |-
 
     ### Set reference for new image  (-t, --tag) {#tag}
 
-    ```
+    ```text
     -t IMAGE or --tag IMAGE
     ```