diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 70 |
1 files changed, 66 insertions, 4 deletions
@@ -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 |