Link

Setup

Install: follow Jekyll website

For GitHub Pages, change in _config.yml:

  • baseurl: to the domain name (repo_name for example)
  • Uncomment relevant part for GitHub Pages

Useful commands

Command Code
Create jekyll new SITE_NAME
Serve 1st time bundle exec jekyll serve
Serve jekyll serve
Serve drafts jekyll serve --draft

File structure

Folder name Description
_posts\ All blog posts
_drafts\ All drafts (created afterward)
_layouts\ All layouts (created afterward)
_includes\ All includes (created afterward)
_data\ All data (created afterward)
_site\ Website itself (output)
_config.yaml Config file
Gemfile Ruby dependencies, including plug-in

Front Matter

Gives information about each published pages, in YAML or JSON.

YAML Code Comment
--- Start of block, at the top of the page
layout: "post" mandatory to use the post template
title: "Welcome to Jekyll!" override title defined in markdown file
date: 2020-05-20 15:48:17 +0200 override date of file, have effect on URL
categories: jekyll update used in defined order to parse the URL
permalink: "/my-url/test/test2" override URL generation by Jekyll with a defined name
permalink: "/:categories/:year/:month/:day/:title" override URL generation by Jekyll with variables
author: "Bob" Custom Front Matter variable author
---  

Default Front Matter

Useful to avoid define layout

In _config.yml, at the end of it:

defaults:
  - scope:
      path: ""          | All files affected by those settings
      path: "folder"    | Files in "folder" affected
      type: "posts"     | Types to affect, avoid pages
    values:
      layout: "post"

Example for a image=true variable passed for all files in assets/img:

defaults:
  - scope:
        path: "assets/img"
    values:
        image: true

Theme

Installation from Gem

Search for themes in RubyGems.
Be careful to update layout: in your posts to ones defined in the theme.

  1. Edit in Gemfile, add the dependency after minima theme: gem "jekyll-theme-XX"
  2. Run bundle install to install all gems needed
  3. Edit _config.yml, change theme: to the one selected
  4. Run bundle exec jekyll serve

Just The Doc theme

Just The Doc
Search need to be initialized with bundle exec just-the-docs rake search:init
_config.yml options are here

For HTTPS, don’t forget to put “https://” in your CNAME and enforce HTTPS in GitHub Pages settings.

Templates

Layout

Create layout_name.html in _layouts\.
For example, post.html affect posts with layout: post.

In a layout page, a parent layout can be defined in the Front Matter: layout: "parent_layout"

Includes

Pieces like header or footer to be reused inside layouts.

Create header.html in _includes\.
Can be used in layout with: {% include header.html %}.
A variable can be passed: {% include header.html color="blue"%} and accessed with {{ include.color }}.

Variables

Variables Comment
{{ content }} Page content
{{ page.title }} Page title
{{ page.author }} Variable author defined in Front Matter of the page
{{ layout.author }} Same, but defined in layout
{{ site.author }} Same, but defined in _config.yml

More variables in Jekyll doc

For - Loops

Used in home layout definition

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

If - Conditional

{% if page.title == "Page Title" %}
    Do something
{% elsif (page.title == "Page2" and condition) or condition %}
    Do something
{% else %}
    Do something
{% endif %}

Entries

Post

Normal post entry.

Filename: yyyy-mm-dd-title-space-delimiter.md
Lives in _posts\ or _drafts\, can be in any (sub) directory in with no effects.

File content:

  1. Front Matter
  2. Actual content

Page

Like about page.

Filename: title.md
Lives in root directory. If in subdirectory, that’ll be reflected on URL.

In the Front Matter:

  • layout: "page"
  • title: Title

Data

Creation

Either YAML, JSON or CSV. Create people.yml in _data\

Access

Raw: {{ site.data.people }}
A loop can be used.

Assets - Static files

Can be anywhere.

{% for file in site.static_files %}
    {{ file.path }} <br>
{% endfor %}

Check related default Front Matter

References