Setup and use Installation

All these commands should be executed in Terminal, one-by-one, in order.

xcode-select --install
/usr/bin/ruby -e "$(curl -fsSL"
brew install ruby
echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.bash_profile

Then open your repo in Terminal, from GitHub Desktop: Repository > Open in Terminal

bundle init Open the new Gemfile, add the following line:

gem "jekyll"

Pop back to Terminal, type:

bundle install

☛ Jekyll installation.

Starting & stopping

First, open your Jekyll folder in Terminal using the GitHub app shortcut—⌃`

Start Jekyll:

bundle exec jekyll serve

View your website in a browser:

‘http://localhost:4000/’ Stop Jekyll:

Control + C Or just quit Terminal. ☛ Jekyll terminal guide.

If hosting on GitHub, don’t forget baseurl

bundle exec jekyll serve --baseurl=""

Setting up Jekyll

Inside your folder you need to create the _config.yml file.

permalink: pretty

Add the baseurl if hosting on GitHub

baseurl: /your-folder-on-github Sample folder setup:

  └ dinos.yml
  └ button.html
  └ default.html
  └ main.css
  └ trex.jpg

Files & paths Linking pages

With permalink: pretty turned on the .html extension can be left off URLs.

*All links & hrefs & srcs should always start with a forward slash: /

<a href="/plant-eaters/">Plant eaters</a>

Don’t forget to add {{site.baseurl}} when hosting on GitHub.

<a href="{{site.baseurl}}/plant-eaters/">Plant eaters</a>

Connecting CSS

Link CSS files like normal, be sure to start with a /

<link href="/css/main.css" rel="stylesheet">

Or for GitHub Pages folder hosting:

<link href="{{site.baseurl}}/css/main.css" rel="stylesheet">

Linking images

Link images like normal, make sure to start with a /

<img src="/images/trex.jpg" alt="">

Or for GitHub Pages folder hosting:

<img src="{{site.baseurl}}/images/trex.jpg" alt="">

Layouts Common header & footer

First create a new file inside the _layouts folder, name it whatever you want. Inside that file put the common HTML.

Use {{content}} as the placeholder for the HTML from each page.


<!DOCTYPE html>
<html lang="en-ca">
  <meta charset="utf-8">

At the top of each page use YAML front matter to denote which layout to use:


layout: default


Layouts can be nested by including a different layout at the top of a layout HTML file.

Page variables

To pass information from a page to a layout you can use YAML frontmatter.


layout: default
title: Plant Eaters

Then inside the layout, we can use placeholder variables:


<!DOCTYPE html>
<html lang="en-ca">
  <meta charset="utf-8">

⋮See the complete list of already included Jekyll page variables.

Highlighting navigation

Use an if-statement inside the <a> tag to add the .current class.

<a href="/plant-eaters/" {% if page.url == '/plant-eaters/' %} class="current" {% endif %}>Plant eaters</a>

Data, includes & posts Data

Data files allow us to separate content from it’s presentation HTML.

Put data files in the _data folder.

All the data is found in the variable


  • name: Tyrannosaurus diet: Meat size: Big
  • name: Stegosaurus diet: Plants size: Medium
  • name: Velociraptor diet: Meat size: Small Includes

Includes are for making reusable, repeatable HTML blocks.

Put includes int the _includes folder.


<a class="btn" href="/go/">Go!</a>
{% include button.html %}
{% include button.html %}

Pass information into includes:

{% include button.html url="/plant-eaters/" title="Plant eaters" %}


<a class="btn" href="{{include.url}}">{{include.title}}</a>


Posts are like blog posts or news articles—time based, ordered content.

Posts must be inside the _posts folder.

Name posts in the following, strict format:

All the data is found in the variable site.posts

_posts/ Use the for loop to output posts:

  {% for post in site.posts %}
      <a href="{{post.url}}">{{post.title}}</a>
  {% endfor %}

Template tags Check out the complete Liquid for Designers resource.


The double curly braces, like {{ }} is to output something—they can be used anywhere to write it into the HTML.

<a href="{{page.url}}">Plant eaters</a>


The for-loop is used to run over a collection of information like data or posts.

{% for dino in %}
{% endfor %}


The if-statement can be used to do different things based on certain conditions.

{% if page.url == '/' %}
  <h1>Dinosaurs Rock!</h1>
{% else %}
  <strong>Dinosaurs Rock</strong>
{% endif %}

Template filters Check out the complete Liquid for Designers resource & Jekyll’s filter docs.


Will convert an ISO 8601 formatted date into something more friendly.

{{site.time | date: '%B %-d, %Y' }}


Will search for all instances of a piece of text and replace it with something else.

{{[0].diet | replace: 'Meat', 'Plants' }}


Will sort a YAML object by a specific field.

{{ | sort: 'name' }}


Takes Markdown inside YAML and converts it to HTML.

    {{[0].name | markdownify }}


Convert text to valid classes.

{{[0].name | classify }}


Will convert an object or array into JSON.

{{ | jsonify }}

Auto Generate Nav

<h3>Getting Started</h3>
    {% for doc in %}
      {% if doc.category == "getting-started" %}
        <li><a href="{{ doc.url }}">{{ doc.title }}</a></li>
      {% endif %}
    {% endfor %}

Add Class or ID to markdown element


<div class="sidebar__top">
  <a href="'''liquid{{site.github.repository_url}}'''/blob/gh-pages/{{}}">
    <i class="fab fa-github-square"></i>
  <a href="vscode://file{{ site.local_git_pc}}/{{ site.local_repo }}/{{ page.path }}">
    <i class="fas fa-laptop-code"></i>
  <a href="vscode://file{{ site.local_git_mac}}/{{ site.local_repo }}/{{ page.path }}">
    <i class="fas fa-laptop-code"></i>
  <a href="#page-title" class="back-to-top">{{[site.locale].back_to_top | default: 'Back to Top' }} &uarr;</a>