diff --git a/docs/bazel.md b/docs/bazel.md
index 2438f03da6..f56710fb7e 100755
--- a/docs/bazel.md
+++ b/docs/bazel.md
@@ -101,7 +101,7 @@ xcodeproj(
 | <a id="xcodeproj-associated_extra_files"></a>associated_extra_files |  Optional. A `dict` of files to be added to the project.<br><br>The key is a `string` value representing the label of the target the files should be associated with, and the value is a `list` of `File`s. These files won't be added to the project if the target is unfocused.   |  `{}` |
 | <a id="xcodeproj-bazel_path"></a>bazel_path |  Optional. The path the `bazel` binary or wrapper script.<br><br>If the path is relative it will be resolved using the `PATH` environment variable that is set when generating the project. If you want to specify a path to a workspace-relative binary, you must prepend the path with `./` (e.g. `"./bazelw"`).   |  `"bazel"` |
 | <a id="xcodeproj-bazel_env"></a>bazel_env |  Optional. A `dict` of environment variables to set when invoking `bazel_path`.<br><br>This is useful for setting environment variables that are required for Bazel actions to run successfully, such as `JAVA_HOME` or `ANDROID_HOME`. It's also useful if `bazel_path` itself (if it's a wrapper) needs certain environment variables.<br><br>The keys are the names of the environment variables, and the values are the values of the environment variables. If a value is `None`, the environment variable will be resolved from the current environment as the project is generated. If a value references environment variables, those will be resolved from the current environment as the project is generated. If you want to use a literal `$` in a value, you must escape it with two backslashes.<br><br>If project generation succeeds, but building inside of Xcode fails because of missing environment variables, you probably have to set them here.<br><br>If `PATH` is not specified, it will default to `/bin:/usr/bin`, so you don't have to specify it unless you want to use a different value.   |  `{"PATH": "/bin:/usr/bin"}` |
-| <a id="xcodeproj-build_mode"></a>build_mode |  Optional. The build mode the generated project should use.<br><br>If this is set to `"xcode"`, the project will use the Xcode build system to build targets. Generated files and unfocused targets (see the `focused_targets` and `unfocused_targets` arguments) will be built with Bazel.<br><br>If this is set to `"bazel"`, the project will use Bazel to build targets, inside of Xcode. The Xcode build system still unavoidably orchestrates some things at a high level.   |  `"bazel"` |
+| <a id="xcodeproj-build_mode"></a>build_mode |  Optional. The build mode the generated project should use.<br><br><ul> <li>     `bazel`: The project will use Bazel to build targets, inside of     Xcode. The Xcode build system still unavoidably orchestrates     some things at a high level. </li> <li>     `xcode`: The project will use the Xcode build system to build     targets. Generated files and unfocused targets (see the     [`focused_targets`](#xcodeproj-focused_targets) and     [`unfocused_targets`](#xcodeproj-unfocused_targets) attributes)     will be built with Bazel.<br><br>    **Note:** This mode is does not work with Bazel 7+.<br><br>    **Note:** This mode is does not work with `generation_mode =     "incremental"`.<br><br>    **Note:** This mode is deprecated and will be removed in a     future version of **rules_xcodeproj**. </li> </ul>   |  `"bazel"` |
 | <a id="xcodeproj-config"></a>config |  Optional. The Bazel config to use when generating the project or invoking `bazel` inside of Xcode.<br><br>This is the basename of multiple configs. For example, if this is set to `"projectx_xcodeproj"`, then the following configs will be available for you to adjust in your `.bazelrc` file:<br><br><ul> <li>`projectx_xcodeproj`</li> <li>`projectx_xcodeproj_generator`</li> <li>`projectx_xcodeproj_indexbuild`</li> <li>`projectx_xcodeproj_swiftuipreviews`</li> </ul><br><br>See the [usage guide](usage.md#bazel-configs) for more information on adjusting Bazel configs.   |  `"rules_xcodeproj"` |
 | <a id="xcodeproj-default_xcode_configuration"></a>default_xcode_configuration |  Optional. The name of the the Xcode configuration to use when building, if not overridden by custom schemes.<br><br>If not set, the first Xcode configuration alphabetically will be used. Use [`xcode_configurations`](#xcodeproj-xcode_configurations) to adjust Xcode configurations.   |  `None` |
 | <a id="xcodeproj-extra_files"></a>extra_files |  Optional. A `list` of extra `File`s to be added to the project.   |  `[]` |
diff --git a/xcodeproj/internal/xcodeproj_macro.bzl b/xcodeproj/internal/xcodeproj_macro.bzl
index dab23c1b87..c48480ded3 100644
--- a/xcodeproj/internal/xcodeproj_macro.bzl
+++ b/xcodeproj/internal/xcodeproj_macro.bzl
@@ -121,14 +121,28 @@ def xcodeproj(
             prepend the path with `./` (e.g. `"./bazelw"`).
         build_mode: Optional. The build mode the generated project should use.
 
-            If this is set to `"xcode"`, the project will use the Xcode build
-            system to build targets. Generated files and unfocused targets (see
-            the `focused_targets` and `unfocused_targets` arguments) will be
-            built with Bazel.
-
-            If this is set to `"bazel"`, the project will use Bazel to build
-            targets, inside of Xcode. The Xcode build system still unavoidably
-            orchestrates some things at a high level.
+            <ul>
+            <li>
+                `bazel`: The project will use Bazel to build targets, inside of
+                Xcode. The Xcode build system still unavoidably orchestrates
+                some things at a high level.
+            </li>
+            <li>
+                `xcode`: The project will use the Xcode build system to build
+                targets. Generated files and unfocused targets (see the
+                [`focused_targets`](#xcodeproj-focused_targets) and
+                [`unfocused_targets`](#xcodeproj-unfocused_targets) attributes)
+                will be built with Bazel.
+
+                **Note:** This mode is does not work with Bazel 7+.
+
+                **Note:** This mode is does not work with `generation_mode =
+                "incremental"`.
+
+                **Note:** This mode is deprecated and will be removed in a
+                future version of **rules_xcodeproj**.
+            </li>
+            </ul>
         config: Optional. The Bazel config to use when generating the project or
             invoking `bazel` inside of Xcode.