- Install Ruby.
- Install Jekyll from the terminal:
$ gem install jekyll bundler
- Create a new
Gemfile
to list your project's dependencies:
$ bundle init
Writing new Gemfile to /path/to/jekyll/Gemfile
- Edit the
Gemfile
in a text editor and add jekyll as a dependency:
gem "jekyll"
- Run
bundle
to install jekyll for your project.
$ bundle
Bundle complete! 1 Gemfile dependency, 31 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.
$ bundle info jekyll
* jekyll (4.3.3)
Summary: A simple, blog aware, static site generator.
Homepage: https://jekyllrb.com
Source Code: https://github.com/jekyll/jekyll
Changelog: https://github.com/jekyll/jekyll/releases
Bug Tracker: https://github.com/jekyll/jekyll/issues
Path: /path/to/gems/gems/jekyll-4.3.3
- You can now prefix all jekyll commands listed in this tutorial with
bundle exec
to make sure you use the jekyll version defined in yourGemfile
.
- Create a new directory for your site
- Create
index.html
in your site root directory. - Note: You can also create a new Jekyll site by running the
jekyll new <PATH>
command.- E.g.,
jekyll new myblog
creates a new Jekyll site at./myblog
. - Jekyll will install a site that uses a gem-based theme called Minima.
- See "Themes" section below.
- E.g.,
- Run either of the following commands to build your site:
jekyll build
- Builds the site and outputs a static site to a directory called_site
.jekyll serve
- Doesjekyll build
and runs it on a local web server at http://localhost:4000, rebuilding the site any time you make a change.- To force the browser to refresh with every change, use
jekyll serve --livereload
. - Not suitable for deployment.
- To force the browser to refresh with every change, use
$ jekyll serve
Configuration file: none
Source: /path/to/jekyll/tutorial_site
Destination: /path/to/jekyll/tutorial_site/_site
Incremental build: disabled. Enable with --incremental
Generating...
done in 0.005 seconds.
Auto-regeneration: enabled for '/path/to/jekyll/tutorial_site'
Server address: http://127.0.0.1:4000
Server running... press ctrl-c to stop.
- Setup. (2024, April 23). Jekyll • Simple, Blog-Aware, Static Sites. https://jekyllrb.com/docs/step-by-step/01-setup/
- A basic Jekyll site usually looks something like this:
.
├── _config.yml
├── _data
│ └── members.yml
├── _drafts
│ ├── begin-with-the-crazy-ideas.md
│ └── on-simplicity-in-technology.md
├── _includes
│ ├── footer.html
│ └── header.html
├── _layouts
│ ├── default.html
│ └── post.html
├── _posts
│ ├── 2007-10-29-why-every-programmer-should-play-nethack.md
│ └── 2009-04-26-barcamp-boston-4-roundup.md
├── _sass
│ ├── _base.scss
│ └── _layout.scss
├── _site
├── .jekyll-cache
│ └── Jekyll
│ └── Cache
│ └── [...]
├── .jekyll-metadata
└── index.html # can also be an 'index.md' with valid front matter
- Directory Structure. (2024, April 23). Jekyll • Simple, Blog-Aware, Static Sites. https://jekyllrb.com/docs/structure/
- Liquid is an open-source template language created by Shopify and written in Ruby.
- It has 3 main components: objects, tags, and filters.
- Objects tell Liquid to output predefined variables as content on a page.
- Use double curly braces for objects:
{{
and}}
. - For example,
{{ page.title }}
displays thepage.title
variable.
- Tags define the logic and control flow for templates.
- Use curly braces and percent signs for tags:
{%
and%}
. - For example:
{% if page.show_sidebar %}
<div class="sidebar">
sidebar content
</div>
{% endif %}
- This displays the sidebar if the value of the
show_sidebar
page variable is true.
- Filters change the output of a Liquid object.
- They are used within an output and are separated by a
|
. - For example:
{{ "hi" | capitalize }}
- This displays
Hi
instead ofhi
.
- Use Liquid to make your
Hello World!
text lowercase:
...
<h1>{{ "Hello World!" | downcase }}</h1>
...
- To make Jekyll process your changes, add "front matter" to the top of the page:
---
# front matter tells Jekyll to process Liquid
---
- Liquid. (2024, April 23). Jekyll • Simple, Blog-Aware, Static Sites. https://jekyllrb.com/docs/step-by-step/02-liquid/
- Front matter is a snippet of YAML placed between two triple-dashed lines at the start of a file.
- You can use front matter to set variables for the page:
---
my_number: 5
---
- You can call front matter variables in Liquid using the
page
variable. - For example,
{{ page.my_number }}
.
- Change the
<title>
on your site to use front matter:tutorial_site/front_matter/index.html
(http://localhost:4000/front_matter/)
- Front Matter. (2024, April 23). Jekyll • Simple, Blog-Aware, Static Sites. https://jekyllrb.com/docs/step-by-step/03-front-matter/
- Layouts are templates that can be used by any page in your site and wrap around page content.
- They are stored in a directory called
_layouts
. - Create the
_layouts
directory in your site's root folder and create a newdefault.html
file. - This HTML is almost identical to
index.html
except:- there's no front matter, and
- the content of the page is replaced by a
content
variable.
content
is a special variable that returns the rendered content of the page on which it's called.
- You can set front matter in layouts, the only difference is when you're using in Liquid, you need to use the
layout
variable instead ofpage
.
---
city: San Francisco
---
<p>{{ layout.city }}</p>
{{ content }}
- To make
index.html
use your new layout, set thelayout
variable in the front matter. - Since the layout wraps around the content on the page, you can call front matter like
page
in the layout file.- When you apply the layout to a page, it uses the front matter on that page.
- Jekyll supports Markdown in addition to HTML when building pages.
- Add
about.md
(http://localhost:4000/layouts/about.html) to use your new layout in the About page.
- Layouts. (2024, April 23). Jekyll • Simple, Blog-Aware, Static Sites. https://jekyllrb.com/docs/step-by-step/04-layouts/
- Layouts. (2024, April 23). Jekyll • Simple, Blog-Aware, Static Sites. https://jekyllrb.com/docs/layouts/
- Navigation should be on every page so adding it to your layout is the correct place to do this.
- The
include
tag allows you to include content from another file stored in an_includes
folder. - Includes are useful for having a single source for source code that repeats around the site or for improving the readability.
- Create a file for the navigation at
_includes/navigation.html
. - Use the
include
tag to add the navigation to_layouts/default_include.html
. - Reference the modified layout in
tutorial_site/includes/index.html
andtutorial_site/includes/about.md
. (http://localhost:4000/includes/)
_includes/navigation.html
needs to know the URL of the page it's inserted into so it can add styling.- Using the
page.url
variable, you can check if each link is the current page and colour it red if true:<a href="/includes/" {% if page.url == "/includes/" %}style="color: red;"{% endif %}>
<a href="/includes/about.html" {% if page.url == "/includes/about.html" %}style="color: red;"{% endif %}>
- Includes. (2024, April 23). Jekyll • Simple, Blog-Aware, Static Sites. https://jekyllrb.com/docs/step-by-step/05-includes/
- Jekyll supports loading data from YAML, JSON, and CSV files located in a
_data
directory. - Data files are a great way to separate content from source code to make the site easier to maintain.
- Create a data file for the navigation at
_data/navigation.yml
. - Jekyll makes this data file available to you at
site.data.navigation
. - Instead of outputting each link in
_includes/navigation_data.html
, now you can iterate over the data file instead. (http://localhost:4000/data/)
- Data Files. (2024, April 23). Jekyll • Simple, Blog-Aware, Static Sites. https://jekyllrb.com/docs/step-by-step/06-data-files/
- Place CSS, JS, images, and other assets in your site folder and they'll copy across to the built site.
- Jekyll sites often use this structure to keep assets organized:
.
├── assets
│ ├── css
│ ├── images
│ └── js
...
- Inlining the styles used in
_includes/navigation_data.html
is not a best practice. - Instead, let's style the current page by defining a class in a new css file:
_includes/navigation_assets.html
. - You could use a standard CSS file for styling, but we're going to take it a step further by using Sass.
- Sass is baked right into Jekyll.
- Create a Sass file at
assets/css/styles.scss
.@import "main"
tells Sass to look for a file calledmain.scss
in the_sass
directory by default.
- Create the
current
class in order to colour the current link green at_sass/main.scss
. - Reference the stylesheet in your layout (
_layouts/default_assets.html
) and add the stylesheet to the<head>
.styles.css
referenced here is generated by Jekyll fromstyles.scss
inassets/css/
.
- Load up http://localhost:4000/sass/ and check that the active link in the navigation is green.
- Assets. (2024, April 23). Jekyll • Simple, Blog-Aware, Static Sites. https://jekyllrb.com/docs/step-by-step/07-assets/
- Blog posts live in a folder called
_posts
. - The filename for posts have a special format: the publish date, then a title, followed by an extension.
- Create your first post at
_posts/2018-08-20-bananas.md
.author
is a custom variable; it's not required and could have been named something likecreator
.
- Create more posts:
- Create the layout for the blog post at
_layouts/post.html
.- This is an example of layout inheritance.
- The post layout outputs the title, date, author and content body, which is wrapped by the default layout.
- Also note the
date_to_string
filter, which formats a date into a nicer format.
- Jekyll makes posts available with
site.posts
. - Create
blog.html
in your site root directory.post.url
is automatically set by Jekyll to the output path of the post.post.title
is pulled from the post filename and can be overridden by settingtitle
in front matter.post.excerpt
is the first paragraph of content by default.
- Add
_data/navigation_blogging.yml
for navigation. - Open http://localhost:4000/blogging/ and have a look through your blog posts.
- Blogging. (2024, April 23). Jekyll • Simple, Blog-Aware, Static Sites. https://jekyllrb.com/docs/step-by-step/08-blogging/
- Collections are similar to posts except the content doesn't have to be grouped by date.
- Jekyll configuration to set up a collection happens in a file called
_config.yml
(by default). - Create
_config.yml
in the site root directory. - Restart the jekyll server (
bundle exec jekyll serve
) to (re)load the configuration.
- Documents (the items in a collection) live in a folder in the root of the site named
_*collection_name*
, in this case,_authors
. - Create a document for each author:
- Let's add a page which lists all the authors on the site.
- Jekyll makes the collection available with
site.authors
. - Create
staff.html
and iterate oversite.authors
to output all the staff.- Since the content is markdown, you need to run it through the
markdownify
filter. - This happens automatically when outputting using
{{ content }}
in a layout.
- Since the content is markdown, you need to run it through the
- You also need a way to navigate to this page through the main navigation:
_data/navigation_collections.yml
.
- By default, collections do not output a page for documents.
- In this case we want each author to have their own page.
- Add
output: true
to the author collection configuration:_config.yml
.- Restart the jekyll server for the configuration changes to take effect.
- You can link to the output page using
author.url
instaff.html
. - Just like posts, create a layout for authors:
_layouts/author.html
.
- What you want is all posts to automatically have the post layout, authors to have author layout, and everything else to use the default layout.
- You can achieve this by using front matter defaults in
_config.yml
. - You set a scope of what the default applies to, then the default front matter you'd like.
- Now you can omit layout from the front matter of all pages and posts.
- The posts have a reference to the author so let's link it to the author's page in in
_layouts/post.html
.{% assign author = site.authors | where: 'short_name', page.author | first %}
:- assign the
site.authors
collection to theauthor
variable; - apply the
where
filter to create an array to include only objects where theshort_name
property is the post page'spage.author
custom variable value; - apply the
first
filter to return the first item in the array.
- assign the
- Open up http://localhost:4000/collections and have a look at the staff page and the author links on posts.
- Collections. (2024, April 23). Jekyll • Simple, Blog-Aware, Static Sites. https://jekyllrb.com/docs/step-by-step/09-collections/
- Shopify. (2024). where. Liquid Template Language. https://shopify.github.io/liquid/filters/where/
- Shopify. (2024). first. Liquid Template Language. https://shopify.github.io/liquid/filters/first/
- Jekyll themes specify plugins and package up assets, layouts, includes, and stylesheets in a way that can be overridden by your site's content.
- You can find and preview themes on different galleries: https://jekyllrb.com/docs/themes/#pick-up-a-theme.
- When you create a new Jekyll site (by running the
jekyll new <PATH>
command), Jekyll installs a site that uses a gem-based theme called Minima. - With gem-based themes, some of the site's directories (such as the
assets
,_data
,_layouts
,_includes
, and_sass
directories) are stored in the theme's gem. - In the case of Minima, you see only the following files in your Jekyll site directory:
.
├── 404.html
├── about.markdown
├── _config.yml
├── Gemfile
├── index.markdown
└── _posts
└── 2024-05-07-welcome-to-jekyll.markdown
- If you have the theme gem, you can run
bundle update
to update all gems in your project. - You can run bundle
update <THEME>
, replacing<THEME>
with the theme name, such asminima
, to just update the theme gem.
- You can override any of the theme default data, layouts, includes, and stylesheets with your own site content.
- To replace layouts or includes in your theme, create a file with the same name as the file you wish to override in your site's
_layouts
or_includes
directory.- For example, if your selected theme has a
page
layout, you can override it by creating your own_layouts/page.html
.
- For example, if your selected theme has a
- To modify any stylesheet you must take the extra step of also copying the main sass file (
_sass/minima.scss
in the Minima theme) into the_sass
directory in your site's source. - To locate a theme's files on your computer, run
bundle info --path <THEME>
, e.g.,bundle info --path minima
.
$ bundle info --path minima
/path/to/gems/minima-2.5.1
$ tree $(bundle info --path minima)
/path/to/gems/minima-2.5.1
├── assets
│ ├── main.scss
│ └── minima-social-icons.svg
├── _includes
│ ├── disqus_comments.html
│ ├── footer.html
│ ├── google-analytics.html
│ ├── header.html
│ ├── head.html
│ ├── icon-github.html
│ ├── icon-github.svg
│ ├── icon-twitter.html
│ ├── icon-twitter.svg
│ └── social.html
├── _layouts
│ ├── default.html
│ ├── home.html
│ ├── page.html
│ └── post.html
├── LICENSE.txt
├── README.md
└── _sass
├── minima
│ ├── _base.scss
│ ├── _layout.scss
│ └── _syntax-highlighting.scss
└── minima.scss
5 directories, 22 files
- The
jekyll new <PATH>
command isn't the only way to create a new Jekyll site with a gem-based theme. - To install a gem-based theme:
- Add the theme gem to your site's
Gemfile
, or if you've started with thejekyll new
command, replacegem "minima", "~> 2.0"
with the gem you want:gem "jekyll-theme-minimal"
- Install the theme:
bundle install
- Add the following to your site's
_config.yml
to activate the theme:theme: jekyll-theme-minimal
- Build your site:
bundle exec jekyll serve
- Add the theme gem to your site's
- Themes. (2024, April 23). Jekyll • Simple, Blog-Aware, Static Sites. https://jekyllrb.com/docs/themes/#pick-up-a-theme