From 0b52a8c6a3522ff139e90849a9c3719510761b85 Mon Sep 17 00:00:00 2001
From: Adam Johnson <me@adamj.eu>
Date: Thu, 7 Apr 2022 20:40:37 +0100
Subject: [PATCH] Update installation instructions (#851)

As per #800.

* Recommend downloading htmx as the main way of installing it.
* Cover npm installation in a bit more detail.
* Note the downsides of unpkg.com and always recommend with the integrity SHA.
* Use `<script defer>` in all `<script>` examples. This tells the browser to defer the parsing and processing of the script until all content is on display, increasing performance. [See HTML spec diagram](https://html.spec.whatwg.org/multipage/scripting.html#attr-script-defer).
---
 README.md         |  3 +--
 www/docs.md       | 41 ++++++++++++++++++++++++++++++++---------
 www/extensions.md |  2 +-
 www/index.md      |  3 +--
 4 files changed, 35 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 196f4d1c..5d177054 100644
--- a/README.md
+++ b/README.md
@@ -34,8 +34,7 @@ By removing these arbitrary constraints htmx completes HTML as a
 ## quick start
 
 ```html
-  <!-- Load from unpkg -->
-  <script src="https://unpkg.com/htmx.org@1.7.0" ></script>
+  <script src="htmx.min.js" defer></script>
   <!-- have a button POST a click via AJAX -->
   <button hx-post="/clicked" hx-swap="outerHTML">
     Click Me
diff --git a/www/docs.md b/www/docs.md
index 2cf4a13f..0c33967e 100644
--- a/www/docs.md
+++ b/www/docs.md
@@ -100,22 +100,45 @@ It's worth mentioning that, if you prefer, you can use the `data-` prefix when u
 ## <a name="installing"></a> [Installing](#installing)
 
 Htmx is a dependency-free javascript library.
+Three different ways to add it to your project are described below.
 
-It can be used via [NPM](https://www.npmjs.com/) as "`htmx.org`" or downloaded or included from
-[unpkg](https://unpkg.com/browse/htmx.org/) or your other favorite NPM-based CDN:
+If you are migrating to htmx from intercooler.js, please see the [migration guide](/migration-guide).
+
+### Download a copy
+
+The simplest, recommended way to install htmx is to copy it into your project.
+
+Download `htmx.min.js` [from unpkg.com](https://unpkg.com/browse/htmx.org/dist/) and add it to the appropriate directory in your project.
+Then, include it where necessary with a `<script>` tag:
 
 ``` html
-    <script src="https://unpkg.com/htmx.org@1.7.0"></script>
+<script src="/path/to/htmx.min.js" defer></script>
 ```
 
-For added security, you can load the script using [Subresource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity).
+You can also add extensions this way, by downloading them from the `ext/` directory.
+
+### With npm
+
+For more advanced configuration, you can install htmx with [npm](https://www.npmjs.com/):
+
+``` sh
+npm install htmx.org
+```
+
+After installing, you’ll need to use appropriate tooling to use `node_modules/htmx.org/dist/htmx.js` (or `.min.js`).
+For example, you might bundle htmx with some extensions and project-specific code.
+
+## Via unpkg.com
+
+For prototyping or testing, you can use the npm package via the unpkg.com CDN.
+Avoid using unpkg.com or other JavaScript CDN’s in production, for [many good reasons](https://blog.wesleyac.com/posts/why-not-javascript-cdn) such as performance and robustness.
+
+To use htmx from unpkg.com, use this `<script>` tag:
 
 ``` html
-    <script src="https://unpkg.com/htmx.org@1.7.0" integrity="sha384-EzBXYPt0/T6gxNp0nuPtLkmRpmDBbjg6WmCUZRLXBBwYYmwAUxzlSGej0ARHX0Bo" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/htmx.org@1.7.0" integrity="sha384-EzBXYPt0/T6gxNp0nuPtLkmRpmDBbjg6WmCUZRLXBBwYYmwAUxzlSGej0ARHX0Bo" crossorigin="anonymous" defer></script>
 ```
 
-If you are migrating to htmx from intercooler.js, please see the [migration guide here](/migration-guide).
-
 ### <a name="webpack">[webpack](#webpack)
 
 If you are using webpack to manage your javascript:
@@ -1048,7 +1071,7 @@ site that will install:
 Simply add the following script tag to your demo/fiddle/whatever:
 
 ```html
-<script src="https://demo.htmx.org"></script>
+<script src="https://demo.htmx.org" defer></script>
 ```
 
 This helper allows you to add mock responses by adding `template` tags with a `url` attribute to indicate which URL. 
@@ -1067,7 +1090,7 @@ Here is an example of the code in action:
 
 ```html
 <!-- load demo environment -->
-<script src="https://demo.htmx.org"></script>
+<script src="https://demo.htmx.org" defer></script>
 
 <!-- post to /foo -->
 <button hx-post="/foo" hx-target="#result">
diff --git a/www/extensions.md b/www/extensions.md
index 3a2ebe9a..e0a919f4 100644
--- a/www/extensions.md
+++ b/www/extensions.md
@@ -17,7 +17,7 @@ Using an extension involves two steps:
 Here is an example
 
 ```html
-  <script src="https://unpkg.com/htmx.org@0.0.8/dist/ext/debug.js"></script>
+  <script src="/path/to/ext/debug.js" defer></script>
   <button hx-post="/example" hx-ext="debug">This Button Uses The Debug Extension</button>
 ```
 
diff --git a/www/index.md b/www/index.md
index 5ee9363f..de91a528 100644
--- a/www/index.md
+++ b/www/index.md
@@ -33,8 +33,7 @@ By removing these arbitrary constraints, htmx completes HTML as a [hypertext](ht
 ## quick start
 
 ```html
-  <!-- Load from unpkg -->
-  <script src="https://unpkg.com/htmx.org@1.7.0"></script>
+  <script src="htmx.min.js" defer></script>
   <!-- have a button POST a click via AJAX -->
   <button hx-post="/clicked" hx-swap="outerHTML">
     Click Me