diff --git a/docs/mkdocs/docs/api/macros/json_use_simdutf.md b/docs/mkdocs/docs/api/macros/json_use_simdutf.md
index 097ce795b..c1bb4da12 100644
--- a/docs/mkdocs/docs/api/macros/json_use_simdutf.md
+++ b/docs/mkdocs/docs/api/macros/json_use_simdutf.md
@@ -18,6 +18,13 @@ scalar path.
 When `JSON_USE_SIMDUTF` is defined you must make the `simdutf.h` header available on the include path and link the
 simdutf library. When it is not defined, no simdutf header is included and there is no dependency.
 
+!!! warning "Define consistently"
+
+    The macro selects between two definitions of the same inline validation function. It must therefore be defined
+    identically for **every** translation unit that includes the library; mixing translation units that define it with
+    ones that do not is an ODR violation. Prefer setting it as a compile definition on the target rather than with
+    `#!cpp #define` in individual source files.
+
 ## Default definition
 
 By default, `#!cpp JSON_USE_SIMDUTF` is not defined and the portable C++11 scalar validator is used.
diff --git a/docs/mkdocs/docs/features/macros.md b/docs/mkdocs/docs/features/macros.md
index 1d169fdeb..c4602fa5a 100644
--- a/docs/mkdocs/docs/features/macros.md
+++ b/docs/mkdocs/docs/features/macros.md
@@ -137,6 +137,14 @@ behavior is deprecated and switched off (`0`) by default.
 
 See [full documentation of `JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`](../api/macros/json_use_legacy_discarded_value_comparison.md).
 
+## `JSON_USE_SIMDUTF`
+
+When defined, UTF-8 validation of JSON strings read from contiguous byte input is delegated to the
+[simdutf](https://github.com/simdutf/simdutf) library instead of the built-in scalar validator. This is an opt-in
+external dependency and is not defined by default.
+
+See [full documentation of `JSON_USE_SIMDUTF`](../api/macros/json_use_simdutf.md).
+
 ## `NLOHMANN_DEFINE_TYPE_*(...)`, `NLOHMANN_DEFINE_DERIVED_TYPE_*(...)`
 
 The library defines 12 macros to simplify the serialization/deserialization of types. See the page on