zola/docs/content/themes/abridge/index.md

+++ title = "abridge" description = "A fast and lightweight Zola theme using semantic html, abridge.css class-light CSS, and No JS." template = "theme.html" date = 2022-04-11T13:14:44+08:00

[extra] created = 2022-04-11T13:14:44+08:00 updated = 2022-04-11T13:14:44+08:00 repository = "https://github.com/Jieiku/abridge.git" homepage = "https://github.com/jieiku/abridge" minimum_version = "0.14.1" license = "MIT" demo = "https://jieiku.github.io/abridge-demo/"

[extra.author] name = "Jake G (jieiku)" homepage = "https://github.com/jieiku" +++

Abridge Zola Theme

Abridge is a fast and lightweight Zola theme using semantic html, class-light abridge.css, and No JS.

Demo

https://jieiku.github.io/abridge-demo/

Requirements

This theme requires version 0.14.1 or later of Zola

Quick Start

git clone https://github.com/jieiku/abridge
cd abridge
zola serve
# open http://127.0.0.1:1111/ in the browser

Installation

The Quick Start example shows you 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

zola init mysite

Step 2: Install abridge

Download this theme to your themes directory:

cd mysite/themes
git clone https://github.com/jieiku/abridge.git

Or install as a submodule:

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:

theme = "abridge"

Or copy the config.toml from the theme directory to your project's root directory, and uncomment the theme line:

cp themes/abridge/config.toml config.toml
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:

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:

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.

Global Configuration

There are some configuration options that you can customize in config.toml.

Configuration options before extra options

Set the authors's taxonomies for the site.

taxonomies = [
  {name = "authors"},
]

Use search function for the content.

build_search_index = true

Currently this theme has not yet implemented a search, there are however several themes that have. For the moment you can look at how those other themes have implemented their search. I plan to implement a search field eventually, but am still weighing my options. I would prefer a self hosted search method that works even if javascript is disabled in the browser. (open an issue report if you know of one.)

Configuration options under the extra

The following options should be under the [extra] in config.toml

• recent = true - This enabled the Recent posts box visible on the top right.
• recent_items = 9 - The number of items to display in the recent posts box
• footer_credit = true - This enables the powered by zola and abridge line in the footer.
• textlogo - The Text based logo in the top left corner
• sitedesc - This add the site description just below the text based logo.
• author - Used for articles to denote the author.
• keywords - This is used for SEO, I am however still working on the SEO related fields, they are likely not 100% correct yet.
• banner - Image to use in seo related cards, this will be the fallback image if the individual articles does not provide one, still a work in progress.
• menu - This is an array of links to display at the top right corner of the page
• menu_footer - This is an array of links to display in the footer of the page
• extra.social - These are the options for the social icons in the footer, and a couple are also used in SEO related meta tags, still a work in progress.

Additionally you should configure which social icons you plan to use. (makes the css file size smaller)

open themes/abridge/sass/_variables.scss

To simply turn them all off you can set $enable-icons: false Otherwise to turn on only the ones you need you would set $enable-icons: true Then 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, as this will decrease the final size of your css file. The difference in size is NOT a lot, without icons its ~4kb, with all the social icons its ~12kb. There are also some general purpose icons you can use, they are disabled by default.

The theme requires tags and categories taxonomies to be enabled in your config.toml:

taxonomies = [
    # You can enable/disable RSS
    {name = "categories", rss = true},
    {name = "tags", rss = true},
]

Top and Footer menus

Set a field in extra with a key of menu and menu_footer. If a link should have a trailing slash at the end of the url set slash = true.

# This is the default menu
menu = [
    {url = "/", name = "Home", slash = true},
    {url = "/about/", name = "About", slash = true},
    {url = "/posts/", name = "Posts", slash = true},
    {url = "/categories/", name = "Categories", slash = true},
    {url = "/tags/", name = "Tags", slash = true},
]
menu_footer = [
    {url = "/", name = "Home", slash = true},
    {url = "/about/", name = "About", slash = true},
    {url = "/contact/", name = "Contact", slash = true},
    {url = "/privacy/", name = "Privacy", slash = true},
    {url = "/sitemap.xml", name = "Sitemap", slash = false},
]

SEO and Header Tags

Some SEO Tags have been added as well as some important head tags for browser compatibility.

you can review them in the head section of templates/base.html, all configurable values should be in config.toml under config.extra

SEO is still a work in progress, will be performing more testing and updates as time allows.

Templates

All pages are extend to the base.html, and you can customize them as need.

Reporting Issues

We use GitHub Issues as the official bug tracker for abridge. Please search existing issues. It’s possible someone has already reported the same problem.

If your problem or idea is not addressed yet, open a new issue.

Contributing

We'd love your help! Especially with fixes to issues. The overall idea behind abridge is to be lightweight and fast, and to use zero javascript. The only place that I may eventually add javascript will be for the site search, but hopefully I can find another way.

License

abridge is distributed under the terms of the MIT license.