# 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://web.dev/measure/?url=https%3A%2F%2Fabridge.netlify.app) 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)
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.14.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
Enable the theme in your `config.toml` in the site directory:
```toml
theme = "abridge"
```
Or 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)
```bash
cp themes/abridge/config.toml config.toml
```
Uncomment the theme line, and point extra_syntaxes_and_themes at the correct directory:
```bash
sed -i 's/^#theme = "abridge"/theme = "abridge"/' config.toml
sed -i 's/^extra_syntaxes_and_themes = \["highlight_themes"\]/extra_syntaxes_and_themes = \["highlight_themes", "themes\/abridge\/highlight_themes"\]/' config.toml
```
The result should be:
```toml
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.
**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:
```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.
## 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.
- 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.
- prestyle.js: Used to preload css files `