Table

of Contents
1. Introduction
2. Directory Structure
3. Config file
4. Github pages
5. Tutorials etc.
6. SCSS
7. Liquid
8. Markdown
Welcome to Jekyll
Transform your plain text into static websites and blogs!

What is it?

Jekyll is, at its heart, a text transformation engine. It is a simple, blog-aware static site generator. You can create page
templates and page elements like headers, footers, and navbars. You can create blog-type dated posts, or static pages.

Unlike wordpress its not a CMS, but in this case your github repo will fill that role.

Jekyll supports a variety of markup languages (Markdown, HTML, Textile), and Liquid to create templates and add dynamic
page elements.

Github pages has built in Jekyll support, so your repo acts as a webhost.

Why is it good?

1. Simple (once you understand it...)

2. Secure (no database vulnerability, edit in your chosen text editor)
3. Fast (static files only)
4. Ability to publish through Github pages

Installation:

gem install jekyll

refer to docs for more!

Ruby 1.9.3+ and Node need to be installed first.

Docs etc.
http://jekyllrb.com/

some jekyll reasons (and problems to look out for):

http://www.smashingmagazine.com/2014/08/01/build-blog-jekyll-github-pages/

what is a static website http://nilclass.com/courses/what-is-a-static-website/

Directory Structure

Warning!
Never work on a file in _site.
Jekyll rewrites this dir on every build.

Structure:
Jekyll uses a standard directory structure to define your website. Resources need to put in particular places, and some
aspects of your directory structure are translated directly into the finished site, e.g. file/directory names become URLS.

.
├── _config.yml
├── _drafts
| ├── begin-with-the-crazy-ideas.textile
| └── on-simplicity-in-technology.markdown
├── _includes
| ├── footer.html
| └── header.html
├── _layouts
| ├── default.html
| └── post.html
├── _posts
| ├── 2007-10-29-why-every-programmer-should-play-nethack.textile
| └── 2009-04-26-barcamp-boston-4-roundup.textile
├── _data
| └── members.yml
├── _site
└── index.html

What are they?

Each of these folders has a distinct purpose within Jekyll.

The _drafts folder is where you keep not-to-be-published posts. The advantage of having such a folder is that it allows you
to locally preview a post by using the jekyll serve --drafts command.

The _includes folder is where you can keep blocks of code that you are likely to reuse a lot. This lets you keep your code
dry and clean. If, for example, you have a certain header style that you wish to appear on most pages, and those pages
use different layouts, rather than repeating yourself across layouts, you can simply specify {% include header %} to inject
the header file within the _includes folder in each layout.

The _layouts folder is where much of the jekyll magic resides. This is where you specify templates in which your posts and
pages will be wrapped in according to what they specify in their YAML Front Matter. In other words, this is where you
specify presentation themes that your content can grab.

The _posts folder is where you stick your blog posts. These must follow the naming format of YYYY-MM-DD-
title.markupextension and begin with YAML Front Matter. Other than that, you can simply type your blog post in the file and
it will be processed by jekyll, fully formatted according to the layout specified in the Front Matter.

The _data folder is the content-parallel to the _includes folder. This is where you might store, for example, a memberlist.yml
file, in which are a list of members whom you refer to frequently on different web pages. Rather than repeating yourself, you
can simply reference the data file thusly: {% site.data.memberlist %}

Getting started:
You too can have such a directory structure!

Once jekyll is installed, run "jekyll new ." (notice the full stop) in an empty directory (or "jekyll new dirname"), and the default
jekyll site will appear.

Reference:
http://jekyllrb.com/docs/structure/

http://pixelcog.com/blog/2013/jekyll-from-scratch-core-architecture/

http://destroytoday.com/blog/hello-world-im-jekyll/
Config file
The default jekyll config file looks like this:

# Site settings
title: Your awesome title
email: your-email@domain.com
description: > # this means to ignore newlines until "baseurl:"
Write an awesome description for your new site here. You can edit this
line in _config.yml. It will appear in your document head meta (for
Google search results) and in your feed.xml site description.
baseurl: "" # the subpath of your site, e.g. /blog/
url: "http://yourdomain.com" # the base hostname & protocol for your site
twitter_username: jekyllrb
github_username: jekyll

# Build settings
markdown: kramdown

As you can see some changes need to be made.

Be aware, if for some reason you are using a 'project page' rather than a 'personal page' you will need to set the baserul to
"/my-project".

Reference:
http://jekyllrb.com/docs/configuration/
Github pages

Gemfile

To make your local environment match github pages, create a Gemfile in your root (see docs below). This way we won't be
caught out by version differences in jekyll's various dependancies.

Run "bundle install" initially, and "bundle update" in the future to stay up to date.

When serving your website locally, use "bundle exec jekyll serve" to run the jekyll serve command in the context of your
bundle.

Misc

You don't need to build your site if you don't want to, github pages will serve it from unbuilt jekyll.

Reference:
http://jekyllrb.com/docs/github-pages/

https://help.github.com/articles/using-jekyll-with-pages/
Tutorials etc.
Basic tutorial for setting up a github page with jekyll. http://24ways.org/2013/get-started-with-github-pages/

Repo:
https://github.com/maban/christmas-recipes

More detailed tutorial

http://www.smashingmagazine.com/2014/08/01/build-blog-jekyll-github-pages/

Repo of a jekyll page, to check out structure etc.

https://github.com/csswizardry/csswizardry.github.com

Markdown cheatsheet
https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

Liquid intro
https://github.com/shopify/liquid/wiki/liquid-for-designers

Video intro https://www.youtube.com/watch?v=O7NBEFmA7yA

SCSS
SCSS stands for Sassy Cascading Style Sheets.

You can use it to condense your CSS.

One of the advantages of SASS is the ability to write programmatic CSS.

You can set resuable CSS variables:

$font-stack: Helvetica, sans-serif;

$primary-color: #333;

body {
font: 100% $font-stack;
color: $primary-color;
}

You can perform mathematical operations:

.container
width: 100%

article[role="main"]
float: left
width: 600px / 960px * 100%

aside[role="complimentary"]
float: right
width: 300px / 960px * 100%

compiles to:

.container {
width: 100%;
}

article[role="main"] {
float: left;
width: 62.5%;
}

aside[role="complimentary"] {
float: right;
width: 31.25%;
}

You can see that the classes 'img-circulardk' and 'img-circularphb' have the same CSS styling except for their background
images. With SCSS you can effectively create a CSS template to use in multiple classes.
Using @mixin, You can define the CSS that you'd like to template. The Syntax is @mixin name { }. Whenever you want a
class to have this template CSS. You put '@include name' where you would normally put your styling.
Liquid
Liquid is a template engine with simple markup that apparently produces beautiful results.

There are two types of markup in liquid: output and tag.

Output

Output uses the double curly brace syntax, e.g.

{{ page.title }}

Using output tags you can access objects (variables) defined in your YAML front matter, or by Jekyll and out put them to
your page.

You can also use simple methods in the form of filters. These have great usefulness. These take the form: {{ input |
filter [| filter...] }}

The following filter takes the title of a post, truncates it to ten words, then capitalizes it: {{ post.title | truncatewords: 10 |
capitalize }}

Tags

Tags may not resolve to text, and take the form:

{% comment %} this text wont be seen {% endcomment %}

Tags are a bit more complicated. These are used for logical operations. One such operation is the for-loop:

{% for post in site.posts %}

<HTML STUFF>
{% endfor %}

An example of what this can do is found in the default jekyll template:

<ul>
{% for post in site.posts reversed limit: 5 %}
<li><a href="{{ post.url }}">{{ post.title }}</a></li>
{% endfor %}
</ul>

Reference:

Liquid Docs
http://docs.shopify.com/themes/liquid-documentation/basics

liquid for designers https://github.com/Shopify/liquid/wiki/Liquid-for-Designers

Markdown

Cheatsheet!
Markdown is pretty damn simple to write, possibly harder to understand.

Markdown was initially created by John Gruber (of Daring Fireball) as a simple way for non-programming types to
write in an easy-to-read format that could be converted directly into HTML. Lifehacker

You may have heard of WYSIWYG (what you see is what you get) formatting.

Think of Markdown like a simplified WYSIWYG ... When web designers and developers approach a project, they
build styles into the project. Those styles dictate how basic elements, like headers and links will appear.

WYSIWYG editing tools gave away too much design control. Someone could unknowingly add a new style to the
design (like red italic bold headers) without meaning to... This makes designers sad :( because their carefully crafted
theme gets lost in the noise.

Bottom line, people who edit content should focus on the words and the designer should make them pretty... When a
designer pushes a new style to the website, the styles are consistently reflected across the whole site, so the design
stays fresh and up to date with browser caveats and features. (Dropshadows anyone?)

Markdown is widely accepted by developers and editors, so it's the best choice for implementing best practice.
Nearly every popular content management solution supports Markdown, if not out-of-the-box, then with an easy-to-
install extension. What is Markdown?

Anyway, what you probably want are commands, and I will show you!

Headers

Of Different

Sizes

super emphatic
really italic

Automatic character escaping & stuff! *literal asterisks*

...You get the idea.

Resources:
http://daringfireball.net/projects/markdown/ The original
http://lifehacker.com/5943320/what-is-markdown-and-why-is-it-better-for-my-to-do-lists-and-notes