Jekyll is a simple, blog-aware, static site generator. It takes a template directory containing raw text files in various formats, runs it through Markdown and Liquid converters, and spits out a complete, ready-to-publish static website suitable for serving with your favorite web server. Jekyll also happens to be the engine behind GitHub Pages, which means you can use Jekyll to host your project's page, blog, or website from GitHub's servers for free (taken from Jekyll's website: http://jekyllrb.com/docs/home/).
To test your website locally, you will need the following packages:
To install from apt-get, you can just run
sudo apt-get install ruby ruby-dev nodejs nodejs-dev jekyll
On Ubuntu 14.04, the versions of ruby and jekyll that are on apt-get are a
bit out of date. Thus, if you install all of the packages from apt-get using
the above command, you are likely to get errors when running commands in the
Basic Usage section below. If you see errors about the --watch
variable when running jekyll build --watch, run the following commands to use
rvm (Ruby Version Manager) to install a new version of ruby and jekyll:
1 $ sudo apt-get install libgdbm-dev libncurses5-dev automake libtool bison \
libffi-dev curl icedtea-7-jre-jamvm nodejs nodejs-dev
2 $ curl -L https://get.rvm.io | bash -s stable
3 $ source ~/.rvm/scripts/rvm
4 $ echo "source ~/.rvm/scripts/rvm" >> ~/.bashrc
5 $ rvm install ruby --latest
6 $ echo "gem: --no-ri --no-rdoc" > ~/.gemrc
7 $ gem update --system
8 $ gem install jekyll- line 1 installs dependencies for
rvm - lines 2-4 configure your environment to use
rubyversions installed fromrvminstead of fromapt-get - line 5 updates
rvmitself - line 6 sets
gemto not install documentation locally (this is optional) - line 7 updates
gem - line 8 installs the latest
jekyll
You'll first need a Jekyll site. If you are interested in using this template, you should clone this repo. In one terminal, build the jekyll site, watching for any changes (run in the site root directory)
$ jekyll build --watch
In another terminal, start a local server (run in site root directory)
$ jekyll serve
View the site in your browser at
localhost:4000/msr-student-template/
|-- README.md (this)
|-- _config.yml (overall configuration file for the site)
|-- _includes (all the markup partials)
| |-- footer.html
| |-- head.html
| |-- header.html
|-- _layouts (page markup templates)
| |-- about.html
| |-- contact.html
| |-- main.html
| |-- project.html
|-- _projects (markdown files that make up the "projects" jekyll collection)
| |-- 2014-09-22-project-1.md
| |-- 2014-09-23-project-2.md
| |-- 2014-09-24-project-3.md
| |-- 2014-09-25-project-4.md
| |-- 2014-09-26-project-5.md
| |-- 2014-09-27-project-6.md
| |-- 2014-09-28-project-7.md
| |-- 2014-09-29-project-8.md
|-- _site (the entire site after it is processed by Jekyll)
| |-- README.md
| |-- about
| |-- contact
| |-- feed.xml
| |-- index.html
| |-- projects
| |-- public
|-- about.md (about page markdown)
|-- contact.md (contact page markdown)
|-- feed.xml (contains general information about Jekyll's usage)
|-- index.html (home page of the site)
|-- public (static content including fonts, images, js, and css files)
| |-- fonts
| |-- images
| |-- javascripts
| |-- stylesheets
First, if you look inside the _site directory, you'll see that no directories or files there begin with an underscore (_). The contents of that directory are the end result of Jekyll's processing engine. All of the files and directories in the root directory of the repository that do begin with an underscore, on the other hand, are "raw". They either include markup that will be included within pages of the final site or they contain markdown and "Front Matter" (which I'll explain later) that will be converted into markup by Jekyll's engine. One of the two commands that you need to run in order to host the site on a local server:
jekyll build --watch
runs that engine, processing and reprocessing the "raw" files every time you make a change to a file. The files and directories in the root directory of the repository that don't begin with an underscore are ignored by Jekyll and will remain the exact same in the _site directory.
Any file that contains a YAML front matter block will be processed by Jekyll as a special file. The front matter must be the first thing in the file and must take the form of valid YAML, set between triple-dashed lines (taken from Jekyll's documentation: http://jekyllrb.com/docs/frontmatter/). Here's a basic example that you'll find in the index.html file:
---
layout: main
title: Portfolio
---
This first item tells Jekyll to take all of the markup in index.html and plug it into the _layouts/main.html template to take the place of the {{ content }} variable found in that template file. The second item tells Jekyll to create a variable, page.title, that you can use in the markup of the template. For example, in _layouts/main.html, you could write:
<head>
<title>{{ page.title }}</title>
</head>
and that would render as:
<head>
<title>Portfolio</title>
</head>
Collections allow you to define a new type of document that can be somewhat conceptualized as an object type, each having its own unique properties and namespaces. These collections are declared in the _config.yml file:
collections:
projects:
output: true
permalink: /projects/:path/
For this site, we only use one collections: projects, the contents of which can be found in the _projects directory. Notice that this directory name begins with an underscore. This is because each file in it only contains some combination of markdown and front-matter and will be processed by Jekyll's engine. Let's look at projects/2014-09-22-project-1.md as an example:
---
layout: project
title: Project 1
date: September 22, 2014
image: http://unsplash.it/400?random
---
## Overview
Lorem ipsum dolor sit amet, tota primis copiosae id quo. Melius eligendi elaboraret pri et, eam menandri platonem te. Tollit iudicabit gloriatur per ad. Ad diceret recteque eum, eu commodo petentium qui. No aliquid delectus eam, dicta eripuit convenire te nec. Vix no veritus dignissim. Erat ferri veniam ut eos, pro ex eius error intellegat, his te graecis oporteat honestatis.
### Topic 1
His nemore audiam consequat ad, no augue choro assueverit mei. Zril offendit tincidunt ne quo. At commodo integre alienum sea, cu vocent fuisset suscipit nam. Eum ex tation omnesque adversarium, mutat autem putant te nam. Id vix facilis complectitur, vis vitae vivendo euripidis ea, fugit eirmod an vix...
This file represents a project in the projects collection and contains both YAML front matter and Markdown. You can see how powerful collections are if we take a look at a snippet of index.html:
<ul id="portfolio-gallery">
{% for project in site.projects %}
<li>
<a href="{{ site.baseurl }}{{ project.url }}">
<img src="{{ project.image }}">
<h2>{{ project.title }}</h2>
</a>
</li>
{% endfor %}
</ul>
The {% %} tags represent liquid syntax and their contents are processed by Jekyll to render static HTML in the final site. You can see that all of the projects in the projects collection can be referenced with site.projects and iterated through with a for loop. In this specific for loop, for each project in the projects collection, we pull its image and title using {{ }} tags. All of a particular project's information is defined in its markdown file just like the one which we saw above. You can find more useful information about collections in Jekyll's website (http://jekyllrb.com/docs/collections/).
To add a project, just create a .md file in the _projects directory with front matter at the beginning that follows this format (taken from 2014-09-22-project-1.md):
---
layout: project
title: Project 1
date: September 22, 2014
image: http://unsplash.it/400?random
---
Following that front matter, just add content in regular markdown.
The appearance of the site is defined entirely by the interaction of several key HTML files and CSS defined to go along with them. The following describes the importance of each of the HTML files:
- main.html provides the general structure of every page
on the site. It includes common elements that are on all of the pages
including content for the HTML
<head>tag, and page footers/headers. These common elements are all defined in the_includesdirectory. - The other three html files inside of the
_layoutsdirectory define the appearance of the about page, the contact page, and each of the project entries. The index.html page defines the project grid that is shown on the site's base URL - Note that all of these HTML files are of the
mainlayout. Thus each of these pages has the same<head>tag, and footer/header.
These HTML files are only half of the story; the other requirement for defining appearance is the CSS to go along with the HTML. The CSS for this site is generated using SASS. Quoting from the SASS documentation:
Sass is an extension of CSS that adds power and elegance to the basic language. It allows you to use variables, nested rules, mixins, inline imports, and more, all with a fully CSS-compatible syntax. Sass helps keep large stylesheets well-organized, and get small stylesheets up and running quickly, particularly with the help of the Compass style library.
Basically we use the syntactical convenience of SASS to enable easier generation
of our CSS. What this means is that if we want to update our site's CSS, we
need to edit the public/stylesheets/style.scss
file and use SASS to build the corresponding CSS. To build the CSS file, cd to
the <project_root>/public/stylesheets/ directory and then execute
sass --watch style.scss:style.cssAs you edit the SCSS file, the CSS file will be automatically updated!
To install SASS you can either use apt-get or gem:
sudo apt-get install ruby-sassor
gem install sass