From 9bf20958864f4a0f281abaf51d1a02b33d60b70a Mon Sep 17 00:00:00 2001
From: Alexander Petros <apetros15@gmail.com>
Date: Thu, 25 Jan 2024 11:14:30 -0500
Subject: [PATCH] Refactor out htmx 1.x migration guide to its own page

---
 www/content/docs.md                           | 82 ++++++-------------
 www/content/migration-guide-htmx-1.md         | 36 ++++++++
 ...uide.md => migration-guide-intercooler.md} |  0
 3 files changed, 61 insertions(+), 57 deletions(-)
 create mode 100644 www/content/migration-guide-htmx-1.md
 rename www/content/{migration-guide.md => migration-guide-intercooler.md} (100%)

diff --git a/www/content/docs.md b/www/content/docs.md
index 72f6986c..e82c9ed2 100644
--- a/www/content/docs.md
+++ b/www/content/docs.md
@@ -107,7 +107,9 @@ It's worth mentioning that, if you prefer, you can use the [`data-`](https://htm
 Htmx is a dependency-free, browser-oriented javascript library. This means that using it is as simple as adding a `<script>`
 tag to your document head.  No need for complicated build steps or systems.
 
-If you are migrating to htmx from intercooler.js, please see the [migration guide](@/migration-guide.md).
+If you are migrating to htmx from intercoolen.js, please see the [intercooler migration guide](@/migration-guide-intercooler.md).
+
+If you are migrating to htmx 2.x from htmx 1.x, please see the [htmx 1.x migration guide](@/migration-guide-htmx-1.md).
 
 ### Via A CDN (e.g. unpkg.com)
 
@@ -172,40 +174,6 @@ window.htmx = require('htmx.org');
 
 * Finally, rebuild your bundle
 
-### htmx 1.x to 2.x Upgrade Guide
-
-To upgrade to htmx 2.0 from htmx 1.0, you will need to do the following:
-
-* If you are still using the legacy `hx-ws` and `hx-sse` attributes, please upgrade to the extension versions (available in 1.x)
-* Default Changes
-  * If you want to retain the 1.0 behavior of "smooth scrolling" by default, revert `htmx.config.scrollBehavior` to `'smooth'`
-  * If you want `DELETE` requests to use a form-encoded body rather than parameters, revert
-    `htmx.config.methodsThatUseUrlParams` to `["get"]` (it's a little crazy, but `DELETE`, according to the spec, should
-     use request parameters.)
-  * If you want to make cross-domain requests with htmx, revert `htmx.config.selfRequestsOnly` to `false`
-* Convert any `hx-on` attributes to their `hx-on:` equivalent:
-  ```html
-     <button hx-get="/info" hx-on="htmx:beforeRequest: alert('Making a request!')
-                                   htmx:afterRequest: alert('Done making a request!')">
-      Get Info!
-     </button>
-  ```
-  becomes:
-  ```html
-     <button hx-get="/info" hx-on:htmx:before-request="alert('Making a request!')"
-                            hx-on:htmx:after-request="alert('Done making a request!')">
-      Get Info!
-     </button>
-  Note that you must use the kebab-case of the event name due to the fact that attributes are case-insensitive in HTML.
-  ```
-* The `htmx.makeFragment()` method now **always** returns a `DocumentFragment` rather than either an `Element` or `DocumentFragment`
-* If you are using htmx in a module setting, we now provide module-type specific files for all three of the major 
-  JavaScript module types: `/dist/htmx.esm.js`, `/dist/htmx.umd.js` & `/dist/htmx.amd.js`
-* htmx 2.0 offers [automatic head merging](#head) with boosted links.  If you do not want this behavior, set you can set `htmx.config.head.boosted` to `"none"`
-
-IE is no longer supported in htmx 2.0, but htmx 1.x continues to support IE and will be supported for the foreseeable 
-future.
-
 ## AJAX
 
 The core of htmx is a set of attributes that allow you to issue AJAX requests directly from HTML:
@@ -637,7 +605,7 @@ You can use this technique to "piggy-back" updates on other requests.
 
 #### Troublesome Tables
 
-Table elements can be problematic when combined with out of band swaps, because, by the HTML spec, many can't stand on 
+Table elements can be problematic when combined with out of band swaps, because, by the HTML spec, many can't stand on
 their own in the DOM (e.g. `<tr>` or `<td>`).
 
 To avoid this issue you can use a `template` tag to encapsulate these elements:
@@ -761,7 +729,7 @@ 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.
 
-Inheritance can be disabled on a per-element and per-attribute basis using the 
+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
@@ -983,7 +951,7 @@ HTML into the document at the target specified and with the swap strategy specif
 
 Sometimes you might want to do nothing in the swap, but still perhaps trigger a client side event ([see below](#response-headers)).
 
-For this situation, by default, you can return a `204 - No Content` response code, and htmx will ignore the content of 
+For this situation, by default, you can return a `204 - No Content` response code, and htmx will ignore the content of
 the response.
 
 In the event of an error response from the server (e.g. a 404 or a 501), htmx will trigger the [`htmx:responseError`](@/events.md#htmx:responseError)
@@ -1018,7 +986,7 @@ The fields available for response handling configuration on entries in this arra
 * `target` - A CSS selector specifying an alternative target for the response
 * `swapOverride` - An alternative swap mechanism for the response
 
-As an example of how to use this configuration, consider a situation when a server-side framework responds with a 
+As an example of how to use this configuration, consider a situation when a server-side framework responds with a
 [`422 - Unprocessable Entity`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422) response when validation
 occurs.  By default, htmx will ignore the response, since it matches the Regular Expression `[45]..`.  You can
 insert a rule at the start of the `htmx.config.responseHandling` array to override this:
@@ -1028,7 +996,7 @@ insert a rule at the start of the `htmx.config.responseHandling` array to overri
   htmx.config.responseHandling.unshift({code:"422", swap: true})
 ```
 
-You can also completely redefine the array of handlers via the normal configuration mechanisms discussed below. 
+You can also completely redefine the array of handlers via the normal configuration mechanisms discussed below.
 
 ### CORS
 
@@ -1076,7 +1044,7 @@ For more on the `HX-Trigger` headers, see [`HX-Trigger` Response Headers](@/head
 
 Submitting a form via htmx has the benefit of no longer needing the [Post/Redirect/Get Pattern](https://en.wikipedia.org/wiki/Post/Redirect/Get).
 After successfully processing a POST request on the server, you don't need to return a [HTTP 302 (Redirect)](https://en.wikipedia.org/wiki/HTTP_302). You can directly return the new HTML fragment.
- 
+
 ### Request Order of Operations {#request-operations}
 
 The order of operations in a htmx request are:
@@ -1118,7 +1086,7 @@ the [`hx-validate`](@/attributes/hx-validate.md) attribute to "true".
 
 ### Validation Example
 
-Here is an example of an input that uses the [`hx-on`](/attributes/hx-on) attribute to catch the 
+Here is an example of an input that uses the [`hx-on`](/attributes/hx-on) attribute to catch the
 `htmx:validation:validate` event and require that the input have the value `foo`:
 
 ```html
@@ -1406,7 +1374,7 @@ such as `onClick`:
 
 This feature allows scripting logic to be co-located with the HTML elements the logic applies to, giving good
 [Locality of Behaviour (LoB)](/essays/locality-of-behaviour).  Unfortunately, HTML only allows `on*` attributes for a fixed
-number of [specific DOM events](https://www.w3schools.com/tags/ref_eventattributes.asp) (e.g. `onclick`) and 
+number of [specific DOM events](https://www.w3schools.com/tags/ref_eventattributes.asp) (e.g. `onclick`) and
 doesn't provide a generalized mechanism for responding to arbitrary events on elements.
 
 In order to address this shortcoming, htmx offers [`hx-on*`](/attributes/hx-on) attributes.  These attributes allow
@@ -1422,8 +1390,8 @@ If we wanted to respond to the `click` event using an `hx-on` attribute, we woul
 
 So, the string `hx-on`, followed by a colon (or a dash), then by the name of the event.
 
-For a `click` event, of course, we would recommend sticking with the standard `onclick` attribute.  However, consider an 
-htmx-powered button that wishes to add a parameter to a request using the `htmx:config-request` event.  This would not 
+For a `click` event, of course, we would recommend sticking with the standard `onclick` attribute.  However, consider an
+htmx-powered button that wishes to add a parameter to a request using the `htmx:config-request` event.  This would not
 be possible using a standard `on*` property, but it can be done using the `hx-on:htmx:config-request` attribute:
 
 ```html
@@ -1559,7 +1527,7 @@ to generate a different `ETag` for each content.
 
 ## Security
 
-htmx allows you to define logic directly in your DOM.  This has a number of advantages, the largest being 
+htmx allows you to define logic directly in your DOM.  This has a number of advantages, the largest being
 [Locality of Behavior](@/essays/locality-of-behaviour.md), which makes your system easier to understand and
 maintain.
 
@@ -1569,8 +1537,8 @@ ends.
 
 ### Rule 1: Escape All User Content
 
-The first rule of HTML-based web development has always been: *do not trust input from the user*.  You should escape all 
-3rd party, untrusted content that is injected into your site.  This is to prevent, among other issues, 
+The first rule of HTML-based web development has always been: *do not trust input from the user*.  You should escape all
+3rd party, untrusted content that is injected into your site.  This is to prevent, among other issues,
 [XSS attacks](https://en.wikipedia.org/wiki/Cross-site_scripting).
 
 There is extensive documentation on XSS and how to prevent it on the excellent [OWASP Website](https://owasp.org/www-community/attacks/xss/),
@@ -1585,21 +1553,21 @@ mechanism in their templating language.  This can be done for good reasons, but
 from a 3rd party then it _must_ be scrubbed, including removing attributes starting with `hx-` and `data-hx`, as well as
 inline `<script>` tags, etc.
 
-If you are injecting raw HTML and doing your own escaping, a best practice is to *whitelist* the attributes and tags you 
-allow, rather than to blacklist the ones you disallow. 
+If you are injecting raw HTML and doing your own escaping, a best practice is to *whitelist* the attributes and tags you
+allow, rather than to blacklist the ones you disallow.
 
 ### htmx Security Tools
 
 Of course, bugs happen and developers are not perfect, so it is good to have a layered approach to security for
-your web application, and htmx provides tools to help secure your application as well. 
+your web application, and htmx provides tools to help secure your application as well.
 
 Let's take a look at them.
 
 #### `hx-disable`
 
-The first tool htmx provides to help further secure your application is the [`hx-disable`](/attributes/hx-disable) 
+The first tool htmx provides to help further secure your application is the [`hx-disable`](/attributes/hx-disable)
 attribute.  This attribute will prevent processing of all htmx attributes on a given element, and on all elements within
-it.  So, for example, if you were including raw HTML content in a template (again, this is not recommended!) then you 
+it.  So, for example, if you were including raw HTML content in a template (again, this is not recommended!) then you
 could place a div around the content with the `hx-disable` attribute on it:
 
 ```html
@@ -1615,15 +1583,15 @@ element, it will not be processed by htmx.
 #### `hx-history`
 
 Another security consideration is htmx history cache.  You may have pages that have sensitive data that you do not
-want stored in the users `localStorage` cache.  You can omit a given page from the history cache by including the 
-[`hx-history`](/attributes/hx-history) attribute anywhere on the page, and setting its value to `false`.  
+want stored in the users `localStorage` cache.  You can omit a given page from the history cache by including the
+[`hx-history`](/attributes/hx-history) attribute anywhere on the page, and setting its value to `false`.
 
 #### Configuration Options
 
 htmx also provides configuration options related to security:
 
 * `htmx.config.selfRequestsOnly` - if set to `true`, only requests to the same domain as the current document will be allowed
-* `htmx.config.allowScriptTags` - htmx will process `<script>` tags found in new content it loads.  If you wish to disable 
+* `htmx.config.allowScriptTags` - htmx will process `<script>` tags found in new content it loads.  If you wish to disable
    this behavior you can set this configuration variable to `false`
 * `htmx.config.historyCacheSize` - can be set to `0` to avoid storing any HTML in the `localStorage` cache
 * `htmx.config.allowEval` - can be set to `false` to disable all features of htmx that rely on eval:
@@ -1655,7 +1623,7 @@ document.body.addEventListener('htmx:validateUrl', function (evt) {
 
 ### CSP Options
 
-Browsers also provide tools for further securing your web application.  The most powerful tool available is a 
+Browsers also provide tools for further securing your web application.  The most powerful tool available is a
 [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP).  Using a CSP you can tell the
 browser to, for example, not issue requests to non-origin hosts, to not evaluate inline script tags, etc.
 
diff --git a/www/content/migration-guide-htmx-1.md b/www/content/migration-guide-htmx-1.md
new file mode 100644
index 00000000..3888886d
--- /dev/null
+++ b/www/content/migration-guide-htmx-1.md
@@ -0,0 +1,36 @@
++++
+title = "htmx 1.x &rarr; htmx 2.x Migration Guide"
++++
+
+The purpose of this guide is to provide instructions for migrations from htmx 1.x to htmx 2.x.
+We place a very high value on backwards compatibility, so in most cases this migrations should require very little, if any, work.
+
+* If you are still using the legacy `hx-ws` and `hx-sse` attributes, please upgrade to the extension versions (available in 1.x)
+* Default Changes
+  * If you want to retain the 1.0 behavior of "smooth scrolling" by default, revert `htmx.config.scrollBehavior` to `'smooth'`
+  * If you want `DELETE` requests to use a form-encoded body rather than parameters, revert
+    `htmx.config.methodsThatUseUrlParams` to `["get"]` (it's a little crazy, but `DELETE`, according to the spec, should
+     use request parameters.)
+  * If you want to make cross-domain requests with htmx, revert `htmx.config.selfRequestsOnly` to `false`
+* Convert any `hx-on` attributes to their `hx-on:` equivalent:
+  ```html
+     <button hx-get="/info" hx-on="htmx:beforeRequest: alert('Making a request!')
+                                   htmx:afterRequest: alert('Done making a request!')">
+      Get Info!
+     </button>
+  ```
+  becomes:
+  ```html
+     <button hx-get="/info" hx-on:htmx:before-request="alert('Making a request!')"
+                            hx-on:htmx:after-request="alert('Done making a request!')">
+      Get Info!
+     </button>
+  Note that you must use the kebab-case of the event name due to the fact that attributes are case-insensitive in HTML.
+  ```
+* The `htmx.makeFragment()` method now **always** returns a `DocumentFragment` rather than either an `Element` or `DocumentFragment`
+* If you are using htmx in a module setting, we now provide module-type specific files for all three of the major
+  JavaScript module types: `/dist/htmx.esm.js`, `/dist/htmx.umd.js` & `/dist/htmx.amd.js`
+* htmx 2.0 offers automatic head merging with boosted links.  If you do not want this behavior, set you can set `htmx.config.head.boosted` to `"none"`
+
+IE is no longer supported in htmx 2.0, but htmx 1.x continues to support IE and will be supported for the foreseeable future.
+
diff --git a/www/content/migration-guide.md b/www/content/migration-guide-intercooler.md
similarity index 100%
rename from www/content/migration-guide.md
rename to www/content/migration-guide-intercooler.md