Document [data-turbo-preload] quirks

_source/handbook/02_drive.md

@@ -378,9 +378,23 @@ function hasSlowInternet() {
 
 ## Preload Links Into the Cache
 
-Preload links into Turbo Drive's cache using `<a href="/" data-turbo-preload>Home</a>`.
+Preload links into Turbo Drive's cache using the [data-turbo-preload][] boolean attribute.
 
 This will make page transitions feel lightning fast by providing a preview of a page even before the first visit. Use it to preload the most important pages in your application. Avoid over usage, as it will lead to loading content that is not needed.
 
+Not every `<a>` element can be preloaded. The `[data-turbo-preload]` attribute
+won't have any effect on links that:
+
+* navigate to another domain
+* have a `[data-turbo-frame]` attribute that drives a `<turbo-frame>` element
+* drive an ancestor `<turbo-frame>` element
+* have the `[data-turbo="false"]` attribute
+* have the `[data-turbo-stream]` attribute
+* have a `[data-turbo-method]` attribute
+* have an ancestor with the `[data-turbo="false"]` attribute
+* have an ancestor with the `[data-turbo-prefetch="false"]` attribute
+
 It also dovetails nicely with pages that leverage [Eager-Loading Frames](/reference/frames#eager-loaded-frame) or [Lazy-Loading Frames](/reference/frames#lazy-loaded-frame). As you can preload the structure of the page and show the user a meaningful loading state while the interesting content loads.
 <br><br>
+
+[data-turbo-preload]: /reference/attributes#data-attributes

_source/reference/attributes.md

@@ -14,6 +14,7 @@ The following data attributes can be applied to elements to customize Turbo's be
 * `data-turbo="false"` disables Turbo Drive on links and forms including descendants. To reenable when an ancestor has opted out, use `data-turbo="true"`. Be careful: when Turbo Drive is disabled, browsers treat link clicks as normal, but [native adapters](/handbook/native) may exit the app.
 * `data-turbo-track="reload"` tracks the element's HTML and performs a full page reload when it changes. Typically used to [keep `script` and CSS `link` elements up-to-date](/handbook/drive#reloading-when-assets-change).
 * `data-turbo-frame` identifies the Turbo Frame to navigate. Refer to the [Frames documentation](/reference/frames) for further details.
+* `data-turbo-preload` signals to [Drive](/handbook/drive#preload-links-into-the-cache) to pre-fetch the next page's content
 * `data-turbo-action` customizes the [Visit](/handbook/drive#page-navigation-basics) action. Valid values are `replace` or `advance`. Can also be used with Turbo Frames to [promote frame navigations to page visits](/handbook/frames#promoting-a-frame-navigation-to-a-page-visit).
 * `data-turbo-permanent` [persists the element between page loads](/handbook/building#persisting-elements-across-page-loads). The element must have a unique `id` attribute. It also serves to exclude elements from being morphed when using [page refreshes with morphing](/handbook/page_refreshes.html)
 * `data-turbo-temporary` removes the element before the document is cached, preventing it from reappearing when restored.