Akademos installation guide

Akademos is a theme for websites built with Jekyll, the static site generator. This document provides information on the installation process and relevant configuration options.

Installing the Akademos Ruby gem

To follow these instructions, you will need (i) a basic Jekyll scaffold running on version 3.2 or higher, and (ii) access to the command line or terminal app.

Include this line in your site’s Gemfile:

gem "jekyll-akademos"

Then add this to your _config.yml:

theme: jekyll-akademos

Once both are in place, use the command line to execute:

bundle

Or install it yourself with:

gem install jekyll-akademos

Akademos themes

The gem includes an assets directory with various files necessary for the proper functioning of the theme. Among them is the assets/_data directory that has the themes.yml and akademos.yml files. The former file contains a list with the style options available. The latter is used to define the theme of choice.

By default, Akademos comes styled with the Gaia theme: a low contrast colour scheme that is pleasant for writing and coding. To change the theme, the user must add the theme key in their project’s _data/akademos.yml (create that file and directory):

# Example using the Ficus colours
theme: "ficus"

If you do not add anything or if your input is incorrect (e.g. a typo), Akademos will use the default colour scheme.

The options are presented below as [Proper name] - [Code value]:

• Alto - alto
• Archaic - archaic
• Bionis - bionis
• Blau - blau
• Caprice - caprice
• Cyprium - cyprium
• Ficus - ficus
• Flowerbed - flowerbed
• Magus - magus
• Nefelio - nefelio
• Neptune - neptune
• Ocarina - ocarina
• Oliveira - oliveira
• Orionis - orionis
• Overgrowth - overgrowth
• Playa - playa
• Sonho - sonho
• Symbiosis - symbiosis
• Vin - vin

These are part of the Prot16 collection. A group of syntax highlighting themes that use a 16-colour-palette. They are available for a number of applications, such as Atom and Vim. To view more about each item, visit the Prot16 pages.

Location of data files

In case you are not sure about where the _data directory should be, here is a sample of a website’s directory structure:

your-site.com
├── _config.yml
├── _posts
|   ├── 2017-02-21-example-title.md
|   └── 2017-02-22-second-example-title.md
├── _layouts
|   ├── default.html
|   └── post.html
|   └── page.html
├── _data
|   └── akademos.yml
└── index.html

Configurations and options

This section covers the underlying assumptions and various options for Akademos.

1. Page subtitle

To use a subtitle, just like in this article, you will first need to include the subtitle key in your post’s YAML front matter.

Here is an example:

---
title: "Akademos installation guide"
subtitle: "A minimalist theme for writers and coders"
layout: post
---

Then, set the following option in your _data/akademos.yml

subtitle: true # Existing subtitles will only be displayed if set to "true"

This will work for files that have values post or page for their layout key.

2. Date format

Dates in posts can be displayed using your format of choice. This is typically defined in your _config.yml file as a global variable with the key date_format.

In case it is not specified, Akademos will default to a [Year]-[Month]-[Day] format.

If you want to set your custom date format, here are some examples. Just pick the line of your preference:

date_format: "%A, %B %d, %Y"    # Wednesday, February 15, 2017
date_format: "%d %B %Y"         # 15 February 2017
date_format: "%A %d %B, %Y"     # Wednesday 15 February 2017
date_format: "%Y-%m-%d"         # 2017-02-15

For more customisation options, see Liquid’s documentation regarding date formats.

3. GitHub Flavoured Markdown (GFM)

It is not mandatory that you use GFM, but it is recommended if you intend to implement fenced blocks for highlighting code.

To learn more about GFM, see their own guide.

4. Syntax highlighting

Akademos is tested with the Kramdown interpreter and the Rouge highlighter. In other words, it is meant to work on GitHub/GitLab Pages out of the box.

Below are the settings. You may include them in your _config.yml file.

# Build settings
markdown: kramdown
kramdown:
  input: GFM
  syntax_highlighting: rouge
highlighter: rouge

Just copy/paste these or make the necessary adjustments. The actual placement of this piece of code is irrelevant. Just add it at the very end for clarity’s sake. Only make sure you do not accidentally alter the format of your existing settings.

If you are not sure where to place the options, here is a sample of a _config.yml file.

# Site settings
title: My title
description: My awesome website
baseurl: "" # the subpath of your site, e.g. /blog
url: "http://your-domain.com"

# Collections
collections:
  schemes:
    output: true

defaults:
  - scope:
      type: schemes
    values:
      layout: post

# Build settings
markdown: kramdown
kramdown:
  input: GFM
  syntax_highlighting: rouge
highlighter: rouge

By default, Rouge prefixes a .highlight CSS class to all the code objects. This is what the Akademos stylesheets will search for. If you have manually changed the prefixed class, you will need to revert to the original.

5. Menu items

There are a number of approaches to adding items to a menu. Akademos makes use of what I have come to consider the best in terms of extensibility and ease of maintenance (assuming the menu is simple). Here I describe how to go about it.

Create a menu.yml file in your site’s _data directory. In it include the name and url of the menu items (internal links can have relative values, such as /test/ instead of your-site.com/test/).

Here is an example:

- name: About
  url: "/about/"

- name: Contact
  url: "/contact/"

- name: Blog
  url: "/blog/"

The above example will create a menu structure like this:

├── About     => your-site.com/about/
├── Contact   => your-site.com/contact/
├── Blog      => your-site.com/blog/

The name key is what determines the label that will show up on the menu. Try to keep it short.

Note that the name is only about the menu labels. It is not related to the actual title of the corresponding page. That is defined in the page’s front matter.

To point to your pages, you will need to specify their permanent URL (or just the slug for internal links).

The direct way is to manually define it in the page’s YAML front matter using the permalink key. Example of my “Contact” page:

---
title: "Contact information"
permalink: /contact/
---

IMPORTANT NOTE: This approach requires you to manually reference the baseurl in case you have defined it in your site’s _config.yml.

Here is a more varied sample of the _data/akademos-menu.yml:

- name: Author
  url: "/author/" # Relative internal link without baseurl

- name: Guide
  url: "/jekyll-akademos/guide/" # Relative internal link with baseurl

- name: Contact
  url: "https://protesilaos.com/contact/" # Absolute link (can be external) 

Optional: Once your pages show up in the menu as intended, my recommendation is to proceed with creating a pages directory under the root folder where all your page files will be grouped. That will further ease your effort to keep your site organised. It will also be easier to filter them out of your local jekyll serve, if you want to speed things up. For more on that, see Speeding up Jekyll

Summary of configurations

All in all, Akademos will make use of a maximum of two additional lines in your akademos.yml file under _data. These are:

# Akademos options
theme: ''     # Defaults to Gaia
subtitle: ''  # Must be 'true' to show on posts/pages

In addition, the theme expects you to create two files in your _data directory. These are the akademos.yml and menu.yml. They provide the structured data necessary for constructing the theme’s secondary parameters and header menu.

Homepage

Akademos is packaged with an index.html file. It is what determines the structure and styles of your homepage.

If you wish to replicate this demo’s homepage, create an index.html file under the root directory and include the following:

---
layout: index
title: "Your homepage title"
subtitle: "Some subtitle text"
---

<div class="index">
  <ul>
    {% for post in site.posts limit:6 %}
      <li>
        <a href="{{ post.url | prepend: site.baseurl }}">
          {{ post.title }}
        </a>
        {% if site.date_format %}
          <time>{{ page.date | date: site.date_format }}</time>
        {% else %}
          <time>{{ page.date | date: '%Y-%m-%d' }}</time>
        {% endif %}
      </li>
    {% endfor %}
  </ul>
</div>

Then modify the values for the title and subtitle keys (delete the subtitle line if not needed).

The above code limits the list output to up to 6 items. This is achieved via the limit:6 filter in the {% for post in site.posts limit:6 %} line. Change the number if you wish, or remove the limit:10 filter altogether.

Contributions and requests

I am looking forward to receiving your suggestions, especially as concerns the optimisation of the existing codebase.

In terms of features, this theme is the finished article. Any additions I may make will only iterate on existing functionality or presentation. The exception would be to address some serious omission in the original version.

Useful links:

• Akademos GitLab repo
• Contact information of Protesilaos Stavrou

License

GNU General Public License Version 3