Dynamically Load Search

1 files changed, 66 insertions, 4 deletions

diff --git a/README.md b/README.md
index 760d918..647e6ac 100644
--- a/README.md
+++ b/README.md
@@ -91,6 +91,58 @@ By default abridge uses `highlight_theme = "css"`.
 
 This allows the code block light/dark mode to change with the rest of the site, this also prevents unsafe-inline for style-src in our CSP.
 
+**IMPORTANT!** by default abridge dynamically loads the js related to the search when the search box is clicked, this allows for a faster page load and saved bandwidth. (not everyone needs or will use the search!)
+
+This feature uses a bundle that has all js related to the search in a single js file, this ensures that the files are in the proper order, and that once downloaded the search is ready to use.
+
+to generate this file you have to do this:
+
+```shell
+zola build
+npm run abridge
+zola build
+```
+
+or if testing/running the theme directly:
+
+```shell
+zola build
+npm run abridge-demo
+zola build
+```
+
+I completely understand that this makes configuration a bit complicated. Zola does not have any built-in facilities for bundling javascript so we are using uglifyjs, shasum, openssl, etc (all defined in package.json) If you find this too difficult then I highly suggest just disabling the facade and loading the search index with the rest of the page:
+
+To disable the facade (dynamic loading of search), you can do this by commenting out the facade line in the config.toml.
+You also need to change the bundle that you use:
+
+```toml
+#js_search_facade = "search_facade.js" # Do not load search until user interaction with search. [comment out to disable]
+js_bundle = "abridge-nofacade.min.js"
+```
+
+The Abridge demo uses netlify, and the included package.json and netlify.toml files handle this extra bundle step for us automatically.
+
+An overview of this logic is this:
+
+```shell
+zola build # just to generate search_index.en.js
+uglifyjs to create search_bundle.min.js # all search related files
+update sha256 hash and base64 encoded sha384 hash in search_facade.js file for cachebust and subresource integrity
+uglifyjs to create abridge-bundle.min.js to include search_facade.js with the new hashes.
+zola build to update the hashes for abridge-bundle.min.js
+```
+
+If you plan to use the included netlify.toml file you should change the following:
+```toml
+command = "zola build && npm run abridge-demo && zola build"
+```
+
+to this:
+```toml
+command = "zola build && npm run abridge && zola build"
+```
+
 ### Step 4: Add new content
 
 You can copy the content from the theme directory to your project:
@@ -153,7 +205,9 @@ These are the javascript files currently used by Abridge:
 
 - search_index.en.js: search index generated by zola at each build for elasticlunr.
 - elasticlunr.min.js: search library for client side searching.
+- email.js: uses javascript to obfuscate your real email address for the mail icon at the bottom of the page.
 - search.js: to make use of elasticlunr from our sites search box for both suggestions and the results page.
+- search_facade.js: used to dynamically load a bundle containing all search related js ONLY when the search box is clicked.
 - codecopy.js: add a Copy Button to code blocks, to copy contents of the code block to clipboard.
 - theme.js: very tiny script to facilitate local storage for the theme switcher. (never bundle, gets loaded separate)
 - theme_button.js: tiny script for the theme switcher function when you click the theme switch button.
@@ -161,12 +215,20 @@ These are the javascript files currently used by Abridge:
 
 js_bundle is set to a javascript file with a bundle of multiple javascript files, this allows us to serve fewer javascript files (only the search index and the bundle). Included are a few of the likely most commonly used combinations, but you can generate these yourself using uglifyjs if you need to, there are examples in the config.toml, eg:
 
-`uglifyjs prestyle.js theme_button.js elasticlunr.min.js search.js -o abridge-switcher.min.js -c -m`
+`uglifyjs prestyle.js theme_button.js elasticlunr.min.js search.js -c -m -o abridge-nofacade.min.js`
+
+Abridge Default Bundle:
+- abridge-bundle.min.js: includes: prestyle, theme_button, search_facade, email, codecopy
 
-- search.min.js - includes: elasticlunr, search.
-- abridge.min.js - includes: prestyle, elasticlunr, search.
-- abridge-switcher.min.js: includes: prestyle, theme_button, elasticlunr, search.
+Abridge Alternate Bundles:
+- abridge-searchonly.min.js - includes: elasticlunr, search
+- abridge-noswitcher.min.js - includes: prestyle, email, codecopy, elasticlunr, search
+- abridge-nofacade.min.js: includes: prestyle, theme_button, email, codecopy, elasticlunr, search
 
+Support Files:
+- theme.min.js (not a bundle, just a minification of theme.js)
+- katexbundle.min.js - includes: katex.min.js mathtex-script-type.min.js auto-render.min.js katexoptions.js
+- search_bundle.min.js: includes: search_index.en, elasticlunr, search
 
 ### Global Configuration