From 40fba63027c4a3937d0ca9369afd9a563ccb76da Mon Sep 17 00:00:00 2001
From: Jonathan Swoboda <154711427+swoboda1337@users.noreply.github.com>
Date: Mon, 25 May 2026 09:16:17 -0400
Subject: [PATCH 1/2] [esphome] Document esphome.build_flags option

---
 src/content/docs/components/esphome.mdx | 32 +++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/src/content/docs/components/esphome.mdx b/src/content/docs/components/esphome.mdx
index 52ac19a812..ed997b9812 100644
--- a/src/content/docs/components/esphome.mdx
+++ b/src/content/docs/components/esphome.mdx
@@ -48,6 +48,9 @@ Advanced options:
 - **platformio_options** (*Optional*, mapping): Additional options to pass over to PlatformIO in the
   platformio.ini file. See [`platformio_options`](#esphome-platformio_options).
 
+- **build_flags** (*Optional*, list of strings): Extra compiler flags to add to the build. Works on
+  both the PlatformIO and native ESP-IDF backends. See [`build_flags`](#esphome-build_flags).
+
 - **environment_variables** (*Optional*, mapping): Environment variables to set during the build process.
   See [`environment_variables`](#esphome-environment_variables).
 
@@ -191,6 +194,35 @@ esphome:
     board_build.f_flash: 80000000L
 ```
 
+<span id="esphome-build_flags"></span>
+
+## `build_flags`
+
+The `build_flags` option lets you add extra compiler flags to the build. Unlike
+`platformio_options.build_flags`, this option also works on the native ESP-IDF build (for variants
+that use it, such as ESP32-P4 and ESP32-H2), and is the recommended way to pass extra flags when
+you want a configuration that works on both backends.
+
+```yaml
+# Example configuration entry
+esphome:
+  # ...
+  build_flags:
+    - "-DMY_CUSTOM_DEFINE"
+    - "-Wno-error=maybe-uninitialized"
+```
+
+Flags are processed as follows:
+
+- `-D...` and `-W...` (non-linker warning) flags are applied project-wide on the IDF backend so
+  they reach every component, including managed ones.
+- `-Wl,...` linker flags are applied to the link step.
+- On the PlatformIO backend, flags are written to `build_flags` in `platformio.ini`.
+
+> [!NOTE]
+> `esphome.platformio_options.build_flags` keeps working unchanged and is still PlatformIO-only.
+> Use `esphome.build_flags` when you need the flag to apply on the native ESP-IDF build as well.
+
 <span id="esphome-environment_variables"></span>
 
 ## `environment_variables`

From fa5da46f22ab3ca7832254bb89684712388f8086 Mon Sep 17 00:00:00 2001
From: Jonathan Swoboda <154711427+swoboda1337@users.noreply.github.com>
Date: Mon, 25 May 2026 09:18:41 -0400
Subject: [PATCH 2/2] [esphome] Drop redundant note from build_flags section

---
 src/content/docs/components/esphome.mdx | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/src/content/docs/components/esphome.mdx b/src/content/docs/components/esphome.mdx
index ed997b9812..c4133fbd7b 100644
--- a/src/content/docs/components/esphome.mdx
+++ b/src/content/docs/components/esphome.mdx
@@ -219,10 +219,6 @@ Flags are processed as follows:
 - `-Wl,...` linker flags are applied to the link step.
 - On the PlatformIO backend, flags are written to `build_flags` in `platformio.ini`.
 
-> [!NOTE]
-> `esphome.platformio_options.build_flags` keeps working unchanged and is still PlatformIO-only.
-> Use `esphome.build_flags` when you need the flag to apply on the native ESP-IDF build as well.
-
 <span id="esphome-environment_variables"></span>
 
 ## `environment_variables`