diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 123 |
1 files changed, 95 insertions, 28 deletions
@@ -3,21 +3,19 @@ # Abridge Zola Theme -Abridge is a fast and lightweight Zola theme using semantic html, only ~6kb css before svg icons, no mandatory JS[*](https://github.com/Jieiku/abridge#contributing-and-philosophy), and perfect [Lighthouse](https://web.dev/measure/?url=https%3A%2F%2Fabridge.netlify.app) and [Observatory](https://observatory.mozilla.org/analyze/abridge.netlify.app) scores. +Abridge is a fast and lightweight Zola theme using semantic html, only ~6kb css before the svg icons and syntax highlighting css, no mandatory JS[*](https://github.com/Jieiku/abridge#contributing-and-philosophy), and perfect [Lighthouse](https://web.dev/measure/?url=https%3A%2F%2Fabridge.netlify.app) and [Observatory](https://observatory.mozilla.org/analyze/abridge.netlify.app) scores. -There is also an [Abridge-minimal](https://github.com/jieiku/abridge.css) Theme which is used to showcase the [abridge.css framework](https://github.com/Jieiku/abridge.css/tree/master/dist) +There is also [Abridge-minimal](https://github.com/jieiku/abridge.css) Theme which is used to showcase the [abridge.css framework](https://github.com/Jieiku/abridge.css/tree/master/dist) Maintainence of this project is made possible by all the <a href="https://github.com/Jieiku/abridge/graphs/contributors">contributors</a> and <a href="https://github.com/sponsors/Jieiku">sponsors</a>. If you'd like to sponsor this project and have your avatar or company logo appear below <a href="https://github.com/sponsors/Jieiku">click here</a>. 💖 <!-- sponsors --><a href="https://github.com/yugfletcher"><img src="https://github.com/yugfletcher.png" width="60px" alt="" /></a><!-- sponsors --> -</div> - --- -## Demo +**[View demo](https://abridge.netlify.app/)** -[https://abridge.netlify.app/](https://abridge.netlify.app/) +</div> ## Requirements @@ -85,8 +83,14 @@ The result should be: theme = "abridge" [markdown] extra_syntaxes_and_themes = ["highlight_themes", "themes/abridge/highlight_themes"] +highlight_code = true +highlight_theme = "css" ``` +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. + ### Step 4: Add new content You can copy the content from the theme directory to your project: @@ -114,6 +118,8 @@ You can customize your configurations, templates and content for yourself. Look at the `config.toml`, `content` files, and templates files in this repo for an idea. +Abridge does support a theme switcher for dark/light mode, but it is disabled by default because it reuires additional javascript. + ### Number of Items per page for pagination To change the number of items per page edit: `abridge/content/_index.md` and change the value for `paginate_by` @@ -131,10 +137,11 @@ $mb:1200px !default;// value at which to switch from fluid layout to using max-w Colors and style are handled by the sass files of [abridge.css](https://github.com/jieiku/abridge.css) -Abridge comes with two "Skins" each with their own auto, dark, and light modes. +Abridge comes with "Skins" each with their own auto, dark, light and switcher modes. Auto mode automatically displays a dark or light version depending on browser/OS settings. +Switcher mode automatically displays a dark or light version depending on browser/OS settings, and has a user clickable theme switcher, but it requires additional javascript. -The skin used on [the Demo](https://abridge.netlify.app/) uses primarily orange colors. +The skin used on [the Demo](https://abridge.netlify.app/) uses primarily orange colors, it the auto without the switcher. It is defined here: `/themes/abridge/sass/abridge.scss` There is also other variations, that you will see defined in this same directory. @@ -142,6 +149,26 @@ There is also other variations, that you will see defined in this same directory To change colors or fonts all you need to do is edit these files or duplicate them and create your own skin. Then in the root of your site type `zola build` which will regenerate your site, this is similar to what zola serve does, except it does not facilitate serving the site. +### Javascript Files, js_bundle and options + +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. +- search.js: to make use of elasticlunr from our sites search box for both suggestions and the results page. +- 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. +- prestyle.js: Used to preload css files `<link rel="preload"` - this script changes these to `<link rel="stylesheet"` once the page has finished loading, this allows us to load stylesheets for external fonts, fontawesome, or katex in a non blocking fashion. + +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` + +- search.min.js - includes: elasticlunr, search. +- abridge.min.js - includes: prestyle, elasticlunr, search. +- abridge-switcher.min.js: includes: prestyle, theme_button, elasticlunr, search. + + ### Global Configuration There are some configuration options that you can customize in `config.toml`. @@ -204,7 +231,7 @@ The following options should be under the `[extra]` in `config.toml` - `js_search_index = "search_index.en.js"` - The search index file to include in the header, comment out to disable. - `js_search = "search.min.js"` - The search script file to include in the header, comment out to disable. - `rss_atom_feed = "atom.xml"` - The atom.xml rss file to include in the header. -- `stylesheet = "abridge.css"` - The stylesheet file to include in the header. +- `stylesheets = [ "abridge.css" ]` - The stylesheet file(s) to include in the header. - `fontawesome =` - Uncomment to enable fontawesome library, this will include the file in the header. - `fonts =` - Uncomment to load external fonts, they will be loaded in the header. - `math` - Set to true to load the Katex library, enabling the use of the [katex shortcode](https://abridge.netlify.app/overview-math/) @@ -288,19 +315,40 @@ thumbnail = "ferris-gesture.png" There are tools you can use to test your page SEO metadata, such as: [smallseotools.com](https://smallseotools.com/meta-tags-analyzer/) -### KaTeX and CSP +### KaTeX Math Notation -KaTeX unfortunately requires `script-src 'unsafe-inline'` in the Content Security Policy. This is a security vulnerability, so the demo site will not render KaTeX correctly because the demo site uses best security practices. +KaTeX can be used to display complex mathematics, it is a "Fast math typesetting for the web." -KaTeX js is designed to work even with dynamic content, but because Zola is a SSG it seems to me the best solution is to avoid using this javascript all-together, process our markdown files similar to how KaTeX autorender does, but do it during zola build. insert some `<span class="KaTeX_Main">` ...etc so that we basically render it during the build process. If complex mathematics were part of my daily life then I might be motivated to write such code for Zola. +You can see a demo of this here [this page](https://abridge.netlify.app/overview-math/). -You will also see [this page](https://abridge.netlify.app/overview-math/) rendered correctly if you git clone this repo and use zola serve because then there will be no Content Security Policy in place. +I recommend only enabling math on a per page bases in your post.md files, instead of in your main config.toml file. ### Templates All pages extend to `base.html`, and you can customize them as need. -## Optional Optimizations: +## Optional Performance Optimizations: + +### Theme-Switcher + +The theme switcher relies on javascript to work, it applies the .light class to the root documentElement. The file that handles this (theme.js) is tiny and optimized and it is the first file loaded in the head, so the performance hit is minimal, but it does still exist. Without the Theme switcher you can still use The automatic Theme, it works by using Browser/OS preference and works well enough for me, you can even install a [Firefox plugin](https://addons.mozilla.org/en-US/firefox/addon/theme-switcher-for-firefox/) to quickly switch between the two. By default the demo has the theme switcher enabled so that it can be evaluated. + +With the growing number of options and configuration it can get confusing. To disable the Theme Switcher, you would comment out the Switcher section and enable your choice in the No switcher section, for example: + +```toml +########## Switcher ########## (comment this block out if NOT using switcher): +#js_theme = "theme.min.js" # Separate Always, comment out if using -auto/-light/-dark stylesheet. (required for switcher) +#js_themeButton = "theme_button.js"# Bundleable +#js_bundle = "abridge-switcher.min.js"# Bundle JS File, comment out to disable (includes switcher) +#stylesheets = [ "abridge-switcher.css" ] # Orange Automatic Dark/Light Theme based on browser/system preference with switcher +#stylesheets = [ "abridge-blue-switcher.css" ] # Blue Automatic Night/Light Theme based on browser/system preference with switcher +#stylesheets = [ "abridge-blueshade-switcher.css" ] # BlueShade Automatic Night/Light Theme based on browser/system preference with switcher + +########## No Switcher ########## +#js_bundle = "search.min.js"# Bundle JS File, comment out to disable (search only: no switcher/prestyle) +js_bundle = "abridge.min.js"# Bundle JS File, comment out to disable (no switcher) +stylesheets = [ "abridge.css" ] # Orange Automatic Dark/Light Theme based on browser/system preference +``` ### Optimize PNG files: @@ -311,22 +359,38 @@ cd static oxipng -o max --strip all -a -Z *.png ``` -### Consolidate two search js files into one: +You can go even farther if you use leanify: -Optionally you can serve a single js file for the search instead of a separate index by combining the two: -(although I am not sure how to accomplish this if your using the theme as a submodule, maybe you can use a git action for this command depending on your hosting provider.) +git clone https://github.com/JayXon/Leanify +cd Leanify +make +sudo cp leanify /usr/local/bin/leanify +exit #launch new terminal +leanify -i 7777 *.{png,ico} -First comment out this line in config.toml: +Here is the results of using leanify on files previously processed with oxipng: -```toml -#js_search_index ="search_index.en.js -``` +Processing: android-chrome-192x192m.png +2.23 KB -> 2.22 KB Leanified: 11 B (0.48%) +Processing: android-chrome-192x192.png +2.51 KB -> 2.48 KB Leanified: 33 B (1.28%) +Processing: android-chrome-512x512.png +5.49 KB -> 5.25 KB Leanified: 241 B **(4.29%)** +Processing: apple-touch-icon.png +2.57 KB -> 2.54 KB Leanified: 30 B (1.14%) +Processing: banner.png +13.07 KB -> 12.93 KB Leanified: 138 B (1.03%) +Processing: mstile-150x150.png +2.24 KB -> 2.20 KB Leanified: 38 B (1.66%) +Processing: favicon-16x16.png +559 B -> 366 B Leanified: 193 B **(34.53%)** +Processing: favicon-32x32.png +969 B -> 663 B Leanified: 306 B **(31.58%)** +Processing: favicon.ico +2.59 KB -> 1.90 KB Leanified: 703 B **(26.53%)** + +Google lighthouse will often notice when your pictures could be more compressed, this may even help SEO. -Then build and uglifyjs: -```bash -zola build -uglifyjs search_index.en.js search.min.js -o search.min.js -c -m -``` ### Pre gzip content to serve with nginx: @@ -349,12 +413,15 @@ gzip_types text/plain text/css application/json application/javascript text/xml #gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript; ``` -Then you can gzip your files: +Then you can gzip/brotli your files: ```bash zola build -find ./public -type f -regextype posix-extended -regex '.*\.(htm|html|css|js|xml|xsl|txt|woff|woff2|svg|otf|eot|ttf)' -exec gzip -k -9 -f {} \; +find ~/.dev/abridge/public -type f -regextype posix-extended -regex '.*\.(htm|html|css|js|xml|xsl|txt|woff|woff2|svg|otf|eot|ttf)' -exec gzip --best -k -f {} \+ -exec brotli --best -f {} \; +rsync -zvrh ~/.dev/abridge/public/ web:/var/www/abridge ``` +Nginx does not come by default with brotli support, but adding it was not difficult. + ## Reporting Issues We use GitHub Issues as the official bug tracker for **abridge**. |