# 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.3 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. Next we will use abridge as a theme to a NEW site. ### Step 1: Create a new zola site ```bash zola init mysite cd mysite ``` ### Step 2: Install abridge Download this theme to your themes directory: ```bash git clone https://github.com/jieiku/abridge.git themes/abridge ``` Or install as a submodule: ```bash 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 some files from the theme directory to your project's root directory: ```bash rsync themes/abridge/config.toml config.toml rsync themes/abridge/COPY-TO-ROOT-SASS/* sass/ rsync themes/abridge/netlify.toml netlify.toml rsync themes/abridge/package.json package.json rsync -r themes/abridge/content/static content/ ``` - `config.toml` base configuration with all config values - `COPY-TO-ROOT-SASS/abridge.scss` overrides to customize Abridge variables. - `netlify.toml` settings to deploy your repo with netlfiy - `package.json` to switch between nosearch, elasticlunr, tinysearch, stork. - `content/static` files for generating tinysearch and stork indexes. Uncomment the theme line in your project's root config.toml: ```bash sed -i 's/^#theme = "abridge"/theme = "abridge"/' config.toml ``` ### Step 4: Add new content Copy the content from the theme directory to your project or make a new post: ```bash rsync -r themes/abridge/content . ``` ### Step 5: Run the project Just run `zola serve` in the root path of the project: ```bash zola serve ``` Zola will start the dev web server, accessible by default at `http://127.0.0.1:1111`. Saved changes will live reload in the browser. ## Customization A lot of effort has been made to ensure Abridge features can be easily customized. ### Number of Items per page for pagination To change the number of items per page edit: `content/_index.md` and change the value for `paginate_by` ## Sass Overrides Abridge SASS variables can be overrided by editing `sass\abridge.scss` file in your project's root sass folder. ### Page Width: ```scss $mw:75%,// max-width ``` ### Abridge Theme Modes ```scss $abridgeMode: "switcher",//valid values: switcher, auto, dark, light ``` - Switcher automatically displays a dark or light version depending on browser/OS settings, and has a javascript user clickable theme switcher. - Auto automatically displays a dark or light version depending on browser/OS settings. - Dark is the dark theme always. - Light is the dark theme always. ### Colors and Styles You can specify which color template you want to use as a base: ```scss $color: "orange",// color template to use/override: orange, blue, blueshade ``` Then override individual colors as needed: ```scss /// Dark Colors $f1d: #ccc,// Font Color Primary $f2d: #ddd,// Font Color Headers $c1d: #111,// Background Color Primary $c2d: #222,// Background Color Secondary ... ``` ### Footer Social Icons You should configure which social icons you plan to use. (makes the css file size smaller) To simply turn them all off you can set `$enable-icons: false` Otherwise enable only the icons you need, eg for mail you would set `$icon-mail: true` You should then disable all the icons that you do not use. ## Config.toml Configuration Most Options in config.toml are self documenting. (obvious between name of config value and comments) Abridge will work with a barebones config.toml because default values are provided in the template files. I recommend copying the entire config.toml file as outlined in Step 3 as it provides all configurable values. ### Top and Footer menus Set a field in `extra` with a key of `menu` and `menu_footer`. If you want the link to open in a new tab/browser then set `blank = true`. If a link should have a trailing slash at the end of the url set `slash = true`. (generally all links should have a trailing slash unless its a file link such as sitemap.xml) ```toml menu = [ {url = "about", name = "About", slash = true, blank = false}, {url = "posts", name = "Posts", slash = true, blank = false}, {url = "categories", name = "Categories", slash = true, blank = false}, {url = "tags", name = "Tags", slash = true, blank = false}, ] menu_footer = [ {url = "about", name = "About", slash = true, blank = false}, {url = "contact", name = "Contact", slash = true, blank = false}, {url = "privacy", name = "Privacy", slash = true, blank = false}, {url = "sitemap.xml", name = "Sitemap", slash = false, blank = true}, ] ``` ### SEO and Header Tags You can review the SEO tags in the head macro located at `templates/macros/head.html`, all configurable values should be in config.toml under config.extra or in the content markdown files. In your post markdown file you should set a title less than 60 characters and a description between 80 and 160 characters in length. The description is what is displayed in search results below the page title. Anywhere that you do not set a page description, the primary site config.description will be used instead. You should also set page specific keywords unless your keywords defined in config.toml suffice, any keywords that you add to the page are in addition to the ones defined in config.toml, so do not add those same keywords to your page keywords. You can optionally also set a page specific image for search results by using page.extra.thumbnail. OpenGraph recommends 1200 x 630 (1.9:1). Twitter recommends 2:1 for large and 1:1 for small. If you do not set a page specific thumbnail then the banner defined in config.toml will be used instead. Refer to [overview-images](https://raw.githubusercontent.com/Jieiku/abridge/master/content/overview-images/index.md) for an example: ```md +++ title = "Image Shortcodes" description = "Images can be embedded directly using markdown `![Ferris](ferris.svg)`, but using a shortcode prevents CLS by explicitly setting the width and height." date = 2021-05-19 [taxonomies] categories = ["Features"] tags = ["shortcodes","images"] [extra] toc = true keywords = "Image, Markdown, Shortcodes, Hover" thumbnail = "ferris-gesture.png" +++ ``` ### KaTeX Math Notation KaTeX can be used to display complex mathematics, it is a "Fast math typesetting for the web." You can see a demo on [this page](https://abridge.netlify.app/overview-math/). For better performance I recommend only enabling math on a [per page bases in your post.md files](https://github.com/Jieiku/abridge/blob/master/content/overview-math.md?plain=1#L11-L13), instead of in your main config.toml file. ## Javascript files 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. - 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: tiny script to facilitate local storage for the theme switcher. (never bundle, always 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 `