Skip to content

Latest commit

 

History

History
178 lines (130 loc) · 7.05 KB

5-reference.md

File metadata and controls

178 lines (130 loc) · 7.05 KB
Raw
title nav
5-Ref
false

Reference

The basic components of the Jekyll stack are described below.

Markdown

markdown icon

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

Check out this GitHub Markdown tutorial{:target="_blank"} for more info.

Note: Jekyll uses the Ruby based kramdown{:target="_blank"} to compile Markdown, so supports a few extras beyond the standard syntax. Check the kramdown quickref{:target="_blank"}.

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:

  • dog
  • cat

Numbered:

  1. one
  2. two

Block quote.

YAML

yaml icon

YAML{:target="_blank"} is a human readable plain text data format. It is used in Jekyll for configuration, site data, and front matter:

  • Jekyll projects are configured{:target="_blank"} using the _config.yml file.
  • YAML, JSON, or CSV files in the _data directory are exposed by Jekyll as site data{:target="_blank"} for Liquid templating.
  • Any file in a Jekyll project with YAML Front matter{:target="_blank"} will be processed, others are just directly copied the the _site directory on build. For example, the front matter for the markdown file generating this page looks like:
---
layout: default
title: 5-Ref
---

Liquid

liquid icon

Liquid{:target="_blank"} is a flexible template language. In Jekyll{:target="_blank"} 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 {% raw %}{% %}{% endraw %} and variables in {% raw %}{{ }}{% endraw %}. For example, the default layout used for this page looks like: {% raw %}

<!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>

{% endraw %}

Sass

sass icon

Sass{:target="_blank"} 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{:target="_blank"} 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.

  • Search for Jekyll themes, there are lots of directories: Gem based{:target="_blank"}, "Jekyll Themes"{:target="_blank"}, and another "Jekyll Themes"{:target="_blank"}
  • Themes supported by gh-pages{:target="_blank"}, these can be added to _config.yml as in [3-Jekyll]({{ "/3-jekyll.html" | absolute_url }}) example and are the same as the Theme Chooser options. Only minima has navigation, alternative layouts, or blog post support built in--so they are not very useful. However, looking at the repository will give you info about how to customize the themes.
  • Remote themes on GitHub{:target="_blank"}, any theme that is hosted on GitHub can be used by adding remote_theme: owner/name to _config.yml. You can find options in the jekyll-theme topic{:target="_blank"}.

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{:target="_blank"} (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{:target="_blank"}. 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).

  • jekyll-seo-tag (GitHub info{:target="_blank"}, usage{:target="_blank"}, basically add {% raw %}{% seo %}{% endraw %} to the <head> of your pages, and make sure you have all the metadata in your _config.yml).
  • jekyll-sitemap (GitHub info{:target="_blank"}, repo{:target="_blank"}).