From ca22b6115b45931187ecc5e3001eb252ade169f3 Mon Sep 17 00:00:00 2001 From: Jieiku Date: Thu, 9 Jun 2022 21:57:10 -0700 Subject: Add Theme Switcher --- README.md | 129 +++++++++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 98 insertions(+), 31 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index ab4a88f..f062d21 100644 --- a/README.md +++ b/README.md @@ -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 contributors and sponsors. If you'd like to sponsor this project and have your avatar or company logo appear below click here. 💖 - - --- -## Demo +**[View demo](https://abridge.netlify.app/)** -[https://abridge.netlify.app/](https://abridge.netlify.app/) + ## 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 `` ...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: - -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.) - -First comment out this line in config.toml: +You can go even farther if you use leanify: + +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} + +Here is the results of using leanify on files previously processed with oxipng: + +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. -```toml -#js_search_index ="search_index.en.js -``` - -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**. -- cgit v1.3.1