docs for inheritance disablingdisable-inheritance

3 files changed, 41 insertions, 1 deletions

diff --git a/www/content/attributes/hx-inherit.md b/www/content/attributes/hx-inherit.md
new file mode 100644
index 00000000..f045794d
--- /dev/null
+++ b/www/content/attributes/hx-inherit.md
@@ -0,0 +1,33 @@
++++
+title = "hx-inherit"
++++
+
+The default behavior for htmx is to "inherit" many attributes automatically: that is, an attribute such as
+[hx-target](@/attributes/hx-target.md) may be placed on a parent element, and all child elements will inherit
+that target.  Some people do not like this feature and instead prefer to explicitly specify inheritance for attributes.
+
+To support this mode of development, htmx offers the `htmx.config.disableInheritance` setting, which can be set to
+`false` to prevent inheritance from being the default behavior for any of the htmx attributes.
+
+The `hx-inherit` attribute allows you to control the inheritance of attributes manually.
+
+htmx evaluates attribute inheritance as follows:
+
+* when `hx-inherit` is set on a parent node
+  * `inherit="*"` all attribute inheritance for this element will be enabled
+  * `hx-inherit="hx-select hx-get hx-target"` enable inheritance for only one or multiple specified attributes
+
+Here is an example of a div that shares an `hx-target` attribute for a set of anchor tags when `htmx.config.disableInheritance`
+is set to false:
+
+```html
+<div hx-target="#tab-container" hx-inherit="hx-target">
+  <a hx-boost="true" href="/tab1">Tab 1</a>
+  <a hx-boost="true" href="/tab2">Tab 2</a>
+  <a hx-boost="true" href="/tab3">Tab 3</a>
+</div>
+```
+
+## Notes
+
+* Read more about [Attribute Inheritance](@/docs.md#inheritance)
diff --git a/www/content/docs.md b/www/content/docs.md
index 1ec6486d..fa0e6cb2 100644
--- a/www/content/docs.md
+++ b/www/content/docs.md
@@ -752,7 +752,12 @@ be confirmed.  We could add an `unset` directive on it like so:
 
 The top two buttons would then show a confirm dialog, but the bottom cancel button would not.
 
-Automatic inheritance can be disabled using the [`hx-disinherit`](@/attributes/hx-disinherit.md) attribute.
+Inheritance can be disabled on a per-element and per-attribute basis using the 
+[`hx-disinherit`](@/attributes/hx-disinherit.md) attribute.
+
+If you wish to disable attribute inheritance entirely, you can set the `htmx.config.disableInheritance` configuration
+variable to `true`.   This will disable inheritance as a default, and allow you to specify inheritance explicitly
+with the [`hx-inherit`](@/attributes/hx-inherit.md) attribute.
 
 ## Boosting
 
@@ -1692,6 +1697,7 @@ listed below:
 | `htmx.config.methodsThatUseUrlParams` | defaults to `["get"]`, htmx will format requests with this method by encoding their parameters in the URL, not the request body                                            |
 | `htmx.config.selfRequestsOnly`        | defaults to `false`, if set to `true` will only allow AJAX requests to the same domain as the current document                                                             |
 | `htmx.config.ignoreTitle`             | defaults to `false`, if set to `true` htmx will not update the title of the document when a `title` tag is found in new content                                            |
+| `htmx.config.disableInheritance`      | disables attribute inheritance in htmx, which can then be overridden by the [`hx-inherit`](@/attributes/hx-inherit.md) attribute                                           |
 
 </div>
 
diff --git a/www/content/reference.md b/www/content/reference.md
index 98b31bce..0f0a5ff5 100644
--- a/www/content/reference.md
+++ b/www/content/reference.md
@@ -57,6 +57,7 @@ The table below lists all other attributes available in htmx.
 | [`hx-history-elt`](@/attributes/hx-history-elt.md)   | the element to snapshot and restore during history navigation                                                                      |
 | [`hx-include`](@/attributes/hx-include.md)           | include additional data in requests                                                                                                |
 | [`hx-indicator`](@/attributes/hx-indicator.md)       | the element to put the `htmx-request` class on during the request                                                                  |
+| [`hx-inherit`](@/attributes/hx-disinherit.md)        | control and enable automatic attribute inheritance for child nodes if it has been disabled by default                              |
 | [`hx-params`](@/attributes/hx-params.md)             | filters the parameters that will be submitted with a request                                                                       |
 | [`hx-patch`](@/attributes/hx-patch.md)               | issues a `PATCH` to the specified URL                                                                                              |
 | [`hx-preserve`](@/attributes/hx-preserve.md)         | specifies elements to keep unchanged between requests                                                                              |