diff --git a/www/content/docs.md b/www/content/docs.md
index 6889666c0..dd61757c6 100644
--- a/www/content/docs.md
+++ b/www/content/docs.md
@@ -1038,7 +1038,7 @@ htmx supports some htmx-specific response headers:
 * `HX-Refresh` - if set to "true" the client-side will do a full refresh of the page
 * [`HX-Replace-Url`](@/headers/hx-replace-url.md) - replaces the current URL in the location bar
 * `HX-Reswap` - allows you to specify how the response will be swapped. See [hx-swap](@/attributes/hx-swap.md) for possible values
-* `HX-Retarget` - a CSS selector that updates the target of the content update to a different element on the page
+* `HX-Retarget` - a CSS selector that updates the target of the content update to a different element on the page. Note that this only changes *where* the swap happens; the swap style is still determined by the source element's [`hx-swap`](@/attributes/hx-swap.md) (or `HX-Reswap`). If the source uses `hx-swap="none"`, you also need to send `HX-Reswap` to make the swap actually occur at the new target.
 * `HX-Reselect` - a CSS selector that allows you to choose which part of the response is used to be swapped in. Overrides an existing [`hx-select`](@/attributes/hx-select.md) on the triggering element
 * [`HX-Trigger`](@/headers/hx-trigger.md) - allows you to trigger client-side events
 * [`HX-Trigger-After-Settle`](@/headers/hx-trigger.md) - allows you to trigger client-side events after the settle step
diff --git a/www/content/reference.md b/www/content/reference.md
index 8810b0b24..f8275844d 100644
--- a/www/content/reference.md
+++ b/www/content/reference.md
@@ -116,7 +116,7 @@ All other attributes available in htmx.
 | `HX-Refresh`                                         | if set to "true" the client-side will do a full refresh of the page
 | [`HX-Replace-Url`](@/headers/hx-replace-url.md)      | replaces the current URL in the location bar
 | `HX-Reswap`                                          | allows you to specify how the response will be swapped. See [hx-swap](@/attributes/hx-swap.md) for possible values
-| `HX-Retarget`                                        | a CSS selector that updates the target of the content update to a different element on the page
+| `HX-Retarget`                                        | a CSS selector that updates the target of the content update to a different element on the page (only changes *where* the swap happens; combine with `HX-Reswap` if the source has `hx-swap="none"`)
 | `HX-Reselect`                                        | a CSS selector that allows you to choose which part of the response is used to be swapped in. Overrides an existing [`hx-select`](@/attributes/hx-select.md) on the triggering element
 | [`HX-Trigger`](@/headers/hx-trigger.md)              | allows you to trigger client-side events
 | [`HX-Trigger-After-Settle`](@/headers/hx-trigger.md) | allows you to trigger client-side events after the settle step