Reference

The basic components of the Jekyll stack are described below.

Markdown

markdown icon

Markdown is a standard to simplify writing content for the web. GitHub markdown flavor can be used any where on GitHub and in Jekyll. The basics are intuitive, you can learn in about a minute!

Check out this GitHub Markdown tutorial for more info.

Note: Jekyll uses the Ruby based kramdown to compile Markdown, so supports a few extras beyond the standard syntax. Check the kramdown quickref.

This Markdown code:

## Heading two

### Heading three, etc.

Any text with no empty lines between will become a paragraph.
Font can be *Italic* or **Bold**.
Code can be highlighted with `backticks`.

Links look like this [GitHub Help](https://help.github.com/).

List:

- dog
- cat

Numbered:

1. one
2. two 

> Block quote.

-------

Will be rendered like this:

Heading two

Heading three, etc.

Any text with no empty lines between will become a paragraph. Font can be Italic or Bold. Code can be highlighted with backticks.

Links look like this GitHub Help.

List:

Numbered:

  1. one
  2. two

Block quote.

YAML

yaml icon

YAML is a human readable plain text data format. It is used in Jekyll for configuration, site data, and front matter:

Liquid

liquid icon

Liquid is a flexible template language. In Jekyll it allows you to layout pages built from modular components and data, using the _includes, _layouts, and _data directories. Liquid includes features such as operators, loops, and filters to manipulate raw content. Liquid statements are enclosed by {% %} and variables in {{ }}. For example, the default layout used for this page looks like:

<!DOCTYPE html>
<html lang="en">
  {% include head.html %}
  <body>
    {% include header.html %}
    <main class="page-content" aria-label="Content">
      <div class="wrapper">
        {{ content }}
      </div>
    </main>
    {% include footer.html %}
  </body>
</html>

Sass

sass icon

Sass is a CSS extension / preprocessor. All normal CSS is valid SCSS, but Sass adds many powerful functions and programatic features. Writing SCSS is often easier and more sensible, for example by supporting nesting, variables, and operators. Jekyll lets you write SASS in modular chucks called partials, in the _sass directory, that will be combined and compiled into normal CSS files when the site is built. For example, notice the variables, nesting, and operators in the SCSS below:

$base-font-family: Helvetica, sans-serif;
$base-font-size: 16px;
$primary-color: #333;
$padding-links: 6px 12px;

nav {
    font-family: $base-font-family;
    font-size: $base-font-size * 1.25;
    color: lighten($primary-color, 25%);
    ul {
        list-style: none;
    }
    li { display: inline-block; }
    a {
        padding: $padding-links;
        text-decoration: none;
    }
}

@import "base";

Themes

Jekyll themes are really just a skeleton of directories and files making up a project. Some are Gems and can be installed by adding the theme to the config and gem file, which case you will not see the theme directories in your project. Others should just be downloaded and added to your project directory manually.

GH-Pages Jekyll Version and Plugins

If you are developing for gh-pages, it is a good idea to keep your environment in sync with what is used on GitHub. This can be done automatically using the github-pages gem (although I rarely bother to do so). To see what version of Jekyll and which plugins GH-Pages use, take a look at the Dependency Versions page. Most of these are builtin dependencies of Jekyll, but there are a few plugins of interest. To use the extra plugins, add them to your _config.yml, under gems:, not in the the gemfile (since gh-pages ignores that).