Alembic

⚗ A Jekyll boilerplate theme designed to be a starting point for any Jekyll website.

Contents

• About
• Features
• Examples
• Installation
• Customising
• Configuration
  • Gem dependency settings
  • Site settings
  • Site performance settings
  • Site navigation
  • Custom fonts
• Using includes
• Page layouts
• Page and Post options
• Credits

About

Alembic is a starting point for Jekyll projects. Rather than starting from scratch, this boilerplate theme is designed to get rolling immediately. Install it, configure it, tweak it, push it.

Features

• Available as a theme gem and GitHub Pages theme
• Clear and elegant design that can be used out of the box or as solid starting point
• Tested in all major browsers, including IE and Edge
• Built in Service Worker so it can work offline and on slow connections
• Configurable colours and typography in a single settings file
• Extensive set of shortcodes to include various elements; such as buttons, icons, figure images and more
• Solid typographic framework from Sassline
• Configurable navigation via a single file
• Modular Jekyll components
• Post category support in the form of a single post index page grouped by category
• Built in live search using JavaScript
• Contact form built in using Formspree or Netlify Forms
• Designed with Siteleaf in mind
• Has 9 of the most popular networks as performant sharing buttons
• Has documentation

Examples

Here are a few examples of Alembic out in the wild being used in a variety of ways:

• billmei.net
• bawejakunal.github.io
• case2111.github.io
• karateca.org

Installation

Quick setup

To give you a running start I've put together some starter kits that you can download, fork or even deploy immediately:

• Vanilla Jekyll starter kit:
• Forestry starter kit:

• Netlify CMS starter kit:

• GitHub Pages with remote theme kit - Download kit

• Stackbit starter kit:

As a Jekyll theme

1. Add

   gem "alembic-jekyll-theme"

   to your

   Gemfile

   to add the theme as a dependancy
2. Run the command

   bundle install

   in the root of project to install the theme and its dependancies
3. Add

   theme: alembic-jekyll-theme

   to your

   _config.yml

   file to set the site theme
4. Run

   bundle exec jekyll serve

   to build and serve your site
5. Done! Use the configuration documentation and the example

   _config.yml

   file to set things like the navigation, contact form and social sharing buttons

As a GitHub Pages remote theme

1. Add

   gem "jekyll-remote-theme"

   to your

   Gemfile

   to add the theme as a dependancy
2. Run the command

   bundle install

   in the root of project to install the jekyll remote theme gem as a dependancy
3. Add

   jekyll-remote-theme

   to the list of

   plugins

   in your

   _config.yml

   file
4. Add

   remote_theme: daviddarnes/[email protected]

   to your

   _config.yml

   file to set the site theme
5. Run

   bundle exec jekyll serve

   to build and serve your site
6. Done! Use the configuration documentation and the example

   _config.yml

   file to set things like the navigation, contact form and social sharing buttons

As a Boilerplate / Fork

(deprecated, not recommended)

1. Fork the repo
2. Replace the

   Gemfile

   with one stating all the gems used in your project
3. Delete the following unnecessary files/folders:

   .github

   ,

   LICENSE

   ,

   screenshot.png

   ,

   CNAME

   and

   alembic-jekyll-theme.gemspec

4. Run the command

   bundle install

   in the root of project to install the jekyll remote theme gem as a dependancy
5. Run

   bundle exec jekyll serve

   to build and serve your site
6. Done! Use the configuration documentation and the example

   _config.yml

   file to set things like the navigation, contact form and social sharing buttons

Customising

When using Alembic as a theme means you can take advantage of the file overriding method. This allows you to overwrite any file in this theme with your own custom file, by matching the file name and path. The most common example of this would be if you want to add your own styles or change the core style settings.

To add your own styles copy the

styles.scss

assets/styles.scss

@import "alembic";

If you're looking to set your own colours and fonts you can overwrite them by matching the variable names from the

_settings.scss

styles.scss

@import "alembic";

Configuration

There are a number of optional settings for you to configure. Use the example

_config.yml

Gem dependency settings

twitter

author

social

Gem settings

/_config.yml

Site settings

You'll need to change the

description

title

url

/assets/

lang

en-US

email

disqus

/_config.yml

Site settings

/_config.yml

repo

Google Analytics can be enabled via the site configuration too. Add your tracking ID to the

/_config.yml

google_analytics: 'UA-XXXXXXXX-1'

google_analytics_anonymize_ip

false

Date format can be customised in the

/_config.yml

date_format

The

short_name

/_config.yml

Site performance settings

Alembic comes with a couple of options to enhance the speed and overall performance of the site you build upon it.

By default the built in Service Worker is enabled, and will work on a 'network first' method. Meaning if there's no internet connection the content the Service Worker has cached will be used until the connection comes back. It will always look for a live version of the code first. To disable the Service Worker add an option called

service_worker

false

/_config.yml

Another option to speed up Alembic is to enable inline CSS, which is off by default. You can enable this by setting

css_inline: true

/_config.yml

/assets/styles.scss

/_includes/site-styles.html

Please note that these options aren't a "silver bullet" for making your site faster, make sure to audit and debug your site to get the best performance for your situation.

Site navigation

There are a total of 4 different navigation types:

• navigation_header

  : The links shown in the header (it is also used on the 404 page)

• navigation_footer

  : The links shown in the footer

• social_links

  : The social icon links that are shown in the sidebar

• sharing_links

  : The social sharing buttons that are shown at the bottom of blog posts

All navigations can be edited using the

_config.yml

Site navigation

/_config.yml

If there are no items for the

navigation_header

navigation_footer

social_navigation

Twitter

Facebook

link

Custom fonts

Alembic comes with custom fonts served from Google fonts. By default it requests Merriweather but this can be any font from any provider assuming it supports requesting fonts in the same manner and does not require javascript.

This can be configured under the

custom_fonts

• urls

  : The urls supplied to you from your font provider (eg https://fonts.googleapis.com/css2?family=Merriweather). For best performance try to use as few urls as possible

• preconnect

  : (optional) If your font provider serves the font files from another domain it can be useful to make a connection to that domain in advance. For example google load the font files from fonts.gstatic.com. This can be omitted if not required

If you want to customise this further you can find the include for custom fonts in

_includes/site-custom-fonts.html

Using includes

There are 2 main types of includes: ones designed for the site and ones that are designed as shortcodes. Here are a list of the shortcode includes:

button.html

A button that can link to a page of any kind.

Example usage:

{% include button.html text="I'm a button" link="https://david.darn.es" %}

Available options: -

text

link

icon

color

figure.html

An image with optional caption.

Example usage:

{% include figure.html image="/uploads/feature-image.jpg" caption="Check out my photo" %}

Available options: -

image

caption

position

left

right

center

width

height

icon.html

An icon.

Example usage:

{% include icon.html id="twitter" %}

Available options: -

id

title

color

width

height

16

nav-share.html

A set of buttons that share the current page to various social networks, which is controlled within the

_config.yml

sharing_links

Example usage:

{% include nav-share.html %}

Available options:

yml
Twitter: "#1DA1F2"
facebook: "#3B5998"
Pinterest: "#BD081C"
LinkedIn: "#0077B5"
tumblr: "#36465D"
Reddit: "#FF4500"
HackerNews: "#ff6600"
DesignerNews: "#2D72D9"
Email: true

The first item is the name of the network (must be one of the ones stated above) and the second is the colour of the button. To remove a button remove the line of the same name.

video.html

A YouTube video.

Example usage:

{% include video.html id="zrkcGL5H3MU" %}

Available options: -

id

map.html

A Google map. See Google My Maps

Example usage:

{% include map.html id="1UT-2Z-Vg_MG_TrS5X2p8SthsJhc" %}

Available options: -

id

site-form.html

Adds a contact form to the page. This can be used with Formspree or Netlify Forms depending on your setup.

Example usage:

{% include site-form.html %}

Available options: -

netlify_form=true

name

Use the

email

/_config.yml

site-search.html

Adds a search form to the page.

Example usage:

{% include site-search.html %}

This include has no options. This include will add a block of javascript to the page and javascript reference in order for the search field to work correctly.

site-before-start.html

&

site-before-end.html

Optional html includes for adding scripts, css, js or any embed code you wish to add to every page without the need to overwrite the entire

default.html

Example usage: These are different to other includes as they are designed to be overwritten. If you create a

site-before-start.html

_includes/

site-before-end.html