Advanced Features

The quickstart guide was intended to provide you with the easiest possible setup of Jekyll Academic. The integration with GitHub Pages allows you to fully set up Jekyll Academic without ever installing Jekyll locally. However, many users may wish to make advanced modifications to their site. If you wish to do so, you would benefit from installing Jekyll locally. The following instructions are based on using Mac OSX as your operating system.

Setting Up Jekyll Locally

GitHub Pages has been designed to work with Jekyll allowing you to upload your 'raw' site files and have GitHub interpret them and create your site. This works well for any user that wants to use GitHub Pages. However, there are additional features that can be utilized if you wish to install Jekyll locally. Local installation allows you to preview the changes made to your site without committing them to GitHub. It also allows you to create new posts from the command line.

To set up Jekyll locally you will need to install the following three things:

Installing Ruby

Probably the easiest way to install Ruby on a Mac is using Homebrew. Once you have Homebrew installed you can install ruby using the command brew install ruby. If you are using another operating system, or wish to have a more advanced ruby setup, you may find the instructions listed here useful. After installing ruby on your system you will need to install RubyGems this can be completed by following the instructions on the RubyGems website.

Installing Jekyll

Jekyll can be installed using RubyGems once you have ruby and RubyGems installed you can install Jekyll using the command gem install jekyll.

Using Jekyll Locally

Jekyll is an incredibly powerful tool. It also has a ton of great documentation written about it already that can be found at the Jekyll website. We highly recommend you take a look at that site to get a better idea of the advanced features that are available. Two of the most common Jekyll commands are described below.

Adding Navigation Items

You may want to add additional navigation items that point to different types of content or individual pages. This can be accomplished by adding a new navigation item. In order to add a new navigation item you will:

1) Copy the folder of an existing navigation item (e.g resume) and paste it into the root directory of your project. Rename this folder with the name of the new navigation item.

2) Navigate to _data/navigation.yml and add a new navigation item by copying the layout of an existing navigation item.

3) Take a look at some of the existing files for other navigation items. Take note of the 'layout' element declared in the frontmatter. This will help you determine which layout is appropriate for your newly created page (e.g. Page or Resume)

Understanding Layouts

One of the fundamental elements of Jekyll is the ability to utilize different layouts for different types of pages. The layouts are found in the _layouts folder. These are .html files that drive the layout of any particular page. For example the 'slide' layout contains all of the necessary includes to power reveal.js slides. The current available layouts in Jekyll Academic are: