# Abridge Zola Theme
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://pagespeed.web.dev/report?url=abridge.netlify.app), [YellowLabTools](https://yellowlab.tools/), and [Observatory](https://observatory.mozilla.org/analyze/abridge.netlify.app) scores.
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)
Here is a [Zola Themes Benchmarks](https://github.com/Jieiku/zola-themes-benchmarks/blob/main/README.md) Page.
Maintenance 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. 💖
---
**[View demo](https://abridge.netlify.app/)**
## Requirements
This theme requires version 0.17.1 or later of [Zola](https://www.getzola.org/documentation/getting-started/installation/)
## Quick Start
```bash
git clone https://github.com/jieiku/abridge.git
cd abridge
zola serve
# open http://127.0.0.1:1111/ in the browser
```
## Installation
The Quick Start shows how to run the theme directly as a site.
Next we will use abridge as a theme to a NEW site.
### Step 1: Create a new zola site
```bash
zola init mysite
```
### Step 2: Install abridge
Download this theme to your themes directory:
```bash
cd mysite/themes
git clone https://github.com/jieiku/abridge.git
```
Or install as a submodule:
```bash
cd mysite
git init # if your project is a git repository already, ignore this command
git submodule add https://github.com/jieiku/abridge.git themes/abridge
```
### Step 3: Configuration
Copy the `config.toml` from the theme directory to your project's root directory:
(This will give you a base configuration with all config values used)
If you plan to use the search_facade feature (dynamic ondemand loading of search) then also copy the package.json (and netlify.toml if you use netlify)
You will also want to copy the content/static folder if you intend to use stork or tinysearch
```bash
cp themes/abridge/config.toml config.toml
cp themes/abridge/package.json package.json
cp themes/abridge/netlify.toml netlify.toml
cp -r themes/abridge/content/static content/
```
Uncomment the theme line:
```bash
sed -i 's/^#theme = "abridge"/theme = "abridge"/' config.toml
```
### Step 4: Add new content
You can copy the content from the theme directory to your project:
```bash
cp -r themes/abridge/content .
```
You can modify or add new posts in the content directory as needed.
### Step 5: Run the project
Just run `zola serve` in the root path of the project:
```bash
zola serve
```
Zola will start the development web server making your site accessible by default at
`http://127.0.0.1:1111`. Saved changes will live reload in the browser.
### Step 6: Add provisions for search_facade.js (dynamic ondemand loading of search related js) or disable the facade.
**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 zola serve
```
or if testing/running the theme directly:
```shell
zola build
npm run abridge-demo
zola build # or zola serve
```
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:
You can disable the facade (dynamic loading of search) in the config.toml:
```toml
js_search_facade = false
```
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 7: Switch Search library (optional)
Abridge by default uses elasticlunr for the search library (zola's default), but both tinysearch and stork are supported search libraries.
tinysearch demo: https://jieiku.github.io/abridge-tinysearch/
stork demo: https://jieiku.github.io/abridge-stork/
**Switch to tinysearch:**
First you have to install tinysearch so that you can build the index:
```shell
git clone https://github.com/tinysearch/tinysearch
cd tinysearch
cargo build --release
sudo cp ./target/release/tinysearch /usr/local/bin/tinysearch
exit # reload shell environment
```
Switch abridge to tinysearch:
```shell
cd ~/.dev/abridge
sed -i 's/^search_library =.*/search_library = "tinysearch"/' config.toml
sed -i 's/^draft =.*/draft = true/' content/static/stork_toml.md
sed -i 's/^draft =.*/draft = false/' content/static/tinysearch_json.md
zola build
tinysearch --optimize --path static public/data_tinysearch/index.html
# zola serve
```
**Switch to stork:**
First you have to install stork so that you can build the index:
```shell
git clone https://github.com/jameslittle230/stork
cd stork
cargo build --release
sudo cp ./target/release/stork /usr/local/bin/stork
exit # reload shell environment
```
Switch abridge to stork:
```shell
cd ~/.dev/abridge
sed -i 's/^search_library =.*/search_library = "stork"/' config.toml
sed -i 's/^draft =.*/draft = false/' content/static/stork_toml.md
sed -i 's/^draft =.*/draft = true/' content/static/tinysearch_json.md
zola build
stork build --input public/data_stork/index.html --output static/stork.st
# zola serve
```
**Switch back to elasticlunr:**
abridge as a theme:
```shell
cd ~/.dev/abridge
sed -i 's/^search_library =.*/search_library = false/' config.toml
sed -i 's/^draft =.*/draft = true/' themes/abridge/content/static/stork_toml.md
sed -i 's/^draft =.*/draft = true/' themes/abridge/content/static/tinysearch_json.md
zola build
npm run abridge
zola build
# zola serve
```
abridge theme directly:
```shell
cd ~/.dev/abridge
sed -i 's/^search_library =.*/search_library = false/' config.toml
sed -i 's/^draft =.*/draft = true/' content/static/stork_toml.md
sed -i 's/^draft =.*/draft = true/' content/static/tinysearch_json.md
zola build
npm run abridge-demo
zola build
# zola serve
```
## Customization
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.
### 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`
### Page width
You can set the overal page width by editing `themes\abridge\sass\_variables.scss` file, and adjusting these two lines:
```scss
$mw:50% !default;// max-width
$mb:1200px !default;// value at which to switch from fluid layout to using max-width
```
### Colors and Styles
Colors and style are handled by the sass files of [abridge.css](https://github.com/jieiku/abridge.css)
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.
It is defined here: `/themes/abridge/sass/abridge-switcher.scss`
There is also other variations, that you will see defined in this same directory, they are also all defined in config.toml
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.
- search_facade.js: used to dynamically load a bundle containing all search related js ONLY when the search box is clicked. (on-demand)
- email.js: uses javascript to obfuscate your real email address for the mail icon at the bottom of the page.
- 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.
- prestyle.js: Used to preload css files `