Alembic

Alembic

Gem Version

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

Screenshot

Tweet it Tip me $5 💸

Contents

About

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

Features

Examples

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

Installation

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/alembic 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, simply 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 into your own project with the same file path (assets/styles.scss). From there you can add your own styles, you can even optionally ignore the theme styles by removing the @import "alembic"; line.

If you’re just looking to set your own colours and fonts copy the _settings.scss and main theme styles file alembic.scss into your project at the same file path (_sass/) and change variables however you wish. The settings are a mixture of custom variables and settings from Sassline - follow the link to find out how to configure the typographic settings.

Configuration

There are a number of optional settings for you to configure. Use the example _config.yml file in the repo and use the documentation below to configure your site:

Gem dependency settings

twitter, author and social values will need to be changed to the projects’ social information or removed. Look for the Gem settings comment within the /_config.yml file. These values are for the jekyll-seo-tag - follow the link to find out more.

Site settings

You’ll need to change the description, title and url to match with the project. You’ll also need to replace the /assets/logo.svg and /assets/default-social-image.png with the project logo and default social image. Setting the site language can be done with lang, the theme will default to en-US. The email needs to be changed to the email you want to receive contact form enquires with. The disqus value can be changed to your project username on Disqus, remove this from the /_config.yml file if you don’t want comments enabled. Look for the Site settings comment within the /_config.yml file. The repo setting is optional, for now, and can be removed entirely, if you wish.

Google Analytics can be enabled via the site configuration too. Add your tracking ID to the /_config.yml file in the following method: google_analytics: 'UA-XXXXXXXX-1'

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. That is, if there is no internet connection then 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 set an option called service_worker to false in the /_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 inside your /_config.yml file.

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.

There are a total of 4 different navigation types:

All navigations can be edited using the _config.yml file. To see example usage either look for the Site navigation comment within the /_config.yml file or see the nav-share.html include.

If there are no items for the navigation_header or navigation_footer, they will fallback to a list of pages within the site. The social_navigation properties should either be one that is already in the list (so Twitter or Facebook) or simply link, this is so an icon can be set for the link.

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: <a class="button" href="https://david.darn.es">I'm a button</a>

Available options:

figure.html

An image with optional caption.

Example usage: `

Check out my photo

Check out my photo

</figure> `

Available options:

icon.html

An icon.

Example usage: <svg width="16" height="16" class="icon icon--twitter" role="img" alt="twitter"><title>twitter</title><use xlink:href="#twitter" fill="CurrentColor"></use></svg>

Available options:

A set of buttons that share the current page to various social networks, which is controlled within the _config.yml file under the sharing_links keyword.

Example usage: `<div class="share">

<a class="button" href="https://twitter.com/intent/tweet/?url=https://rohitfarmer.github.io/alembic/&text=Alembic&via=rohitfarmer" style="background: #0d94e7">Twitter&nbsp; <svg width="16" height="16" class="icon  icon--twitter" role="img" alt="twitter"><title>twitter</title><use xlink:href="#twitter" fill="CurrentColor"></use></svg> </a>

  







<a class="button" href="https://facebook.com/sharer/sharer.php?u=https://rohitfarmer.github.io/alembic/" style="background: #3B5998">facebook&nbsp; <svg width="16" height="16" class="icon  icon--facebook" role="img" alt="facebook"><title>facebook</title><use xlink:href="#facebook" fill="CurrentColor"></use></svg> </a>

  







<a class="button" href="https://plus.google.com/share?url=https://rohitfarmer.github.io/alembic/" style="background: #DC4E41">Google+&nbsp; <svg width="16" height="16" class="icon  icon--google+" role="img" alt="google+"><title>google+</title><use xlink:href="#google+" fill="CurrentColor"></use></svg> </a>

  







<a class="button" href="https://www.linkedin.com/shareArticle?url=https://rohitfarmer.github.io/alembic/&title=Alembic&source=Rohit Farmer&mini=true" style="background: #0077B5">LinkedIn&nbsp; <svg width="16" height="16" class="icon  icon--linkedin" role="img" alt="linkedin"><title>linkedin</title><use xlink:href="#linkedin" fill="CurrentColor"></use></svg> </a>

</div> `

Available options:

Twitter: "#1DA1F2"
facebook: "#3B5998"
Google+: "#DC4E41"
Pinterest: "#BD081C"
LinkedIn: "#0077B5"
tumblr: "#36465D"
Reddit: "#FF4500"
Hacker News: "#ff6600"
Designer News: "#2D72D9"
Email: ""

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 just remove the line of the same name.

video.html

A YouTube video.

Example usage: `<div class="video">

</div> `

Available options:

map.html

A Google map. See Google My Maps

Example usage: <div class="map"><iframe src="https://www.google.com/maps/d/u/0/embed?mid=1UT-2Z-Vg_MG_TrS5X2p8SthsJhc" title="Map"></iframe></div>

Available options:

site-form.html

Adds a contact form to the page.

Example usage: `<div class="form form--contact">


* indicates a required field

</div>

`

This include has no options. Use the email option in the /_config.yml to change to the desired email.

site-search.html

Adds a search form to the page.

Example usage: `<div class="form form--search">

</div>

`

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.

Page layouts

As well as page, post, blog, there are a few alternative layouts that can be used on pages:

Page and Post options

There are some more specific options you can apply when creating a page or a post:

Note: The Post List Page options are actually in the collection data within the _config.yml file.

Credits