docs: binary limitations
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bf06015..958d1c1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,8 @@
### Added
-- Documenting `exclude_patterns` workaround for issue [#31](https://github.com/TendTo/rules_doxygen/issues/31)
+- Documenting `exclude_patterns` workaround [#31](https://github.com/TendTo/rules_doxygen/issues/31) (thanks to @AustinSchuh)
+- Documenting limitations for the automatic download of the doxygen binary in the `doxygen` extension rule [#32](https://github.com/TendTo/rules_doxygen/issues/32) (thanks to @oxidase)
## [2.4.2]
diff --git a/docs/extensions_doc.md b/docs/extensions_doc.md
index 2752c44..ef2327c 100755
--- a/docs/extensions_doc.md
+++ b/docs/extensions_doc.md
@@ -161,6 +161,14 @@
> The build will fail when the download does not match the SHA256 checksum, i.e. when the platform changes.
> Unless you are using a system-wide doxygen installation, you should always specify the platform.
+> [!Note]
+> When a version is specified, the extension will download the doxygen binary from the official [Doxygen releases](https://github.com/doxygen/doxygen/releases).
+> If a binary for the specified platform is not available (e.g., _linux-arm_, _mac-arm_), the build may fail.
+> If that happens, you can either:
+> - Use a different version of doxygen that supports your platform.
+> - Use a system-wide doxygen installation by setting the version to `0.0.0`.
+> - Use a local doxygen executable by providing a label pointing to the doxygen executable in the `executable` parameter.
+
#### System-wide doxygen installation
If you set the version to `0.0.0`, the doxygen executable will be assumed to be available from the PATH.
diff --git a/extensions.bzl b/extensions.bzl
index 04545be..99630d7 100644
--- a/extensions.bzl
+++ b/extensions.bzl
@@ -370,6 +370,14 @@
> The build will fail when the download does not match the SHA256 checksum, i.e. when the platform changes.
> Unless you are using a system-wide doxygen installation, you should always specify the platform.
+> [!Note]
+> When a version is specified, the extension will download the doxygen binary from the official [Doxygen releases](https://github.com/doxygen/doxygen/releases).
+> If a binary for the specified platform is not available (e.g., _linux-arm_, _mac-arm_), the build may fail.
+> If that happens, you can either:
+> - Use a different version of doxygen that supports your platform.
+> - Use a system-wide doxygen installation by setting the version to `0.0.0`.
+> - Use a local doxygen executable by providing a label pointing to the doxygen executable in the `executable` parameter.
+
#### System-wide doxygen installation
If you set the version to `0.0.0`, the doxygen executable will be assumed to be available from the PATH.
