# 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)
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. 💖
---
**[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.
### 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.
- search.js: to make use of elasticlunr from our sites search box for both suggestions and the results 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 `