Learn The Basics of Jekyll
Note, May 2016: As of now, this tutorial is intended for Mac users. For guidence on mac OS installation check here
IMPORTANT: in able to install these packages you will need root permissions, if your account does not have these permissions, you can run these commands along with the ‘sudo’ command. For example: 'sudo gem install jekyll'
Home Page
<h1 class="sectionHeader">About Jekyll</h1>
<p class="underline sectionContent">What Is Jekyll and What Does It Do?</p>
<p>
Jekyll is a static <a href="">site generator</a> used to create websites that exist as a directory of files. Because Jekyll is used to create static sites instead of dynamic ones, there are some helpful advantages that come along with using it:
<ol>
<li>
Static sites do not require an extensive back end, which allows for quicker and simpler development.
</li>
<br>
<li>
Due to the lack of server side scripts, the security of a jekyll site is far more apparent than that of a dynamic page. Because all of the files are created and collected upon launch there is little room for hacker threat to the sites infrastructure.
</li>
</ol>
</p>
<p class="subsection">There are also some Disadvantages to using a static site as well</p>
<ol>
<li>Because static sites cannot pull data from a standard database, the content within the site will always need to be edited manually. This requires some programming experience on the developer's end in able to edit content. </li>
<br>
<li>In addition to manually editing files in able to make changes, and depending on your changes multiple files may need to be edited. Just as the step before, YMMV depending on your programming experience.</li>
</ol>
<p class="sectionContent">For a visual representation of the power of Jekyll, here are some sites that were created with it:</p>
<ul>
<li><a href="http://tom.preston-werner.com/">Tom Preston-Werner</a></li>
<li><a href="https://services.github.com/training/">GitHub Official Teaching Materials</a></li>
<li><a href="https://rsms.me/">Rasmus Andersson</a></li>
</ul>
<p class="sectionContent">As you can see from both the <a href="http://tom.preston-werner.com/">Tom Preston-Werner</a> and <a href="https://rsms.me/">Rasmus Andersson</a> pages, but most notably the Tom Preston-Werner page, Jekyll functions primarily as a blog site with the ease of displaying and creating pages as posts.</p>
<h1 class="sectionHeader">Setting Up Jekyll and Jekyll Environment</h1>
<p class="underline sectionContent">a. Jekyll Installation</p>
<p class="sectionContent">
Installing and launching Jekyll will all be done from the <a href="http://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line">terminal</a>. All of the instructions here can also be found on the <a href="https://jekyllrb.com/docs/quickstart/">official jekyll</a> documentation page.
</p>
<p class="sectionContent">
After initially opening your terminal you should be in your user directory, displaying all of your documents when listing all of the files.
</p>
<p>
from within your user directory, run this command in able to begin the jekyll install
{% highlight ruby %}
gem install jekyll
{% endhighlight %}
b. Other Installations
<p class="sectionContent">
You will also need to install the <a href="https://learn.cloudcannon.com/jekyll/gemfiles-and-the-bundler/#what-is-the-bundler-and-how-do-we-use-it">jekyll bundler</a> by running the command:
{% highlight ruby %}
gem install jekyll bundler
{% endhighlight %}
<p class="sectionContent">
In able to access and edit files within your jekyll project, you will need a text editor. Any text editor will work, but I recommend the free text editor <a href="https://www.sublimetext.com/3">sublime text 3</a>.
</p>
<p class="sectionContent">
Lastly, you will need to have <a href="http://www.rubyist.net/~slagell/ruby/">Ruby</a> installed. Luckily, all mac devices come preinstalled with Ruby so no installation should be needed. However, if you do need to install Ruby, you can do so <a href="https://www.ruby-lang.org/en/documentation/installation/">here</a>.
</p>
<p class="underline">c. Getting Started With Jekyll</p>
<p clas="sectionHeader">
In able to begin building our jekyll site, we must first create the project directory. Luckily, this is can be done with a simple command from within the terminal. From the terminal, navigate to your Desktop and run the following command to create a project entitled ‘myjekyllsite’:
{% highlight ruby %}
Jekyll new myjekyllsite
{% endhighlight %}
<p class="sectionContent">
Now that we have our project directory created, navigate into it from within the terminal and launch it using the following command:
{% highlight ruby %}
Bundle exec jekyll serve
{% endhighlight %}
<p>
Now that we have our project up and running on a local server we can take a look at the active project by entering the URL address “localhost:4000” within any browser of your choice while the application is running. By default, all Jekyll projects run locally on port 4000, hence, the address “localhost:4000”. After entering the URL to your localhost, you should see a page similar to this one
</p>
<img class="thumbnail" src="/images/tutorials/jekyll-basics/default-site.png">
<p>
In able to stop your project press the following key combination in the terminal (at the same time):
{% highlight ruby %}
control + c
{% endhighlight %}
<p class="sectionContent">
While editing our Jekyll project files, front end changes to our code will be able to take effect immediately upon save and can be viewed upon reloading the page. You can see if these changes have been successfully implemented by viewing the active log on at the terminal. This log will remain active and up to date as long as the project is running. Any changes to the .config file will require a server restart in able for the changes to take effect.
</p>
<img class="thumbnail" src="/images/tutorials/jekyll-basics/terminal-changes.png">
<p class="sectionHeader underline">
Premade Files
</p>
<p class="sectionContent">
To view the project directory you can either open it directly from the desktop or by using our Sublime text editor. For the sake of convenience, we will be viewing our project inside of the Sublime text editor.
</p>
<img class="thumbnail" src="/images/tutorials/jekyll-basics/open-project.png">
<p class="sectionContent">
After opening the project within Sublime, or any other text editor of your choice, you should be able to view all of the files within the project. Various version updates to Jekyll may often change which files are included with your new project, so we will just go over the most relevant files.
</p>
<p class="sectionContent">
From within your project folder, you should have the files listed below. Click on each file to find out more about it.
</p>
<div id="filesGallery" class="row">
<!-- POST FILE -->
<div id="file" class="col-lg-4 col-sm-6">
<!-- Trigger the modal with a button -->
<a id="box" data-toggle="modal" data-target="#_posts">
<img class="thumbnail" src="/images/tutorials/jekyll-basics/gray.png">
</a>
<!-- Modal -->
<div id="_posts" class="modal fade" role="dialog">
<div class="modal-dialog">
<!-- Modal content-->
<div class="modal-content">
<div class="modal-header">
<button type="button" class="close" data-dismiss="modal">×</button>
<h4 class="modal-title">The '_posts' Folder</h4>
</div>
<div class="modal-body">
<p>Because of Jekyll’s main functionality as a blogging site, the project comes preinstalled with a _posts folder. The purpose of this folder is gather all of the bloggers “posts” that they will have on their site. In able for a post file to be usable, it must follow the naming convention of 'Year-Month-Day-Name'</p>
</div>
<div class="modal-footer">
<button type="button" class="btn btn-default" data-dismiss="modal">Close</button>
</div>
</div>
</div>
</div>
<p id="fileText">_posts</p>
</div>
<!-- _SITE FILE -->
<div id="file" class="col-lg-4 col-sm-6">
<!-- Trigger the modal with a button -->
<a data-toggle="modal" data-target="#_site">
<img class="thumbnail" src="/images/tutorials/jekyll-basics/gray.png">
</a>
<!-- Modal -->
<div id="_site" class="modal fade" role="dialog">
<div class="modal-dialog">
<!-- Modal content-->
<div class="modal-content">
<div class="modal-header">
<button type="button" class="close" data-dismiss="modal">×</button>
<h4 class="modal-title">The '_site' Folder</h4>
</div>
<div class="modal-body">
<p>In short, the site folder is used to hold your running application. Whenever a Jekyll project is launched, all of the files are compiled into the _site folder and launched from there.
</p>
<p>
You can view this yourself by launching your Jekyll project and viewing the _site directory
</p>
<p>
Any changes to this file will be overridden upon the launch of your Jekyll site
</p>
</div>
<div class="modal-footer">
<button type="button" class="btn btn-default" data-dismiss="modal">Close</button>
</div>
</div>
</div>
</div>
<p id="fileText">_site</p>
</div>
<!-- INDEX.MD FILE -->
<div id="file" class="col-lg-4 col-sm-6">
<!-- Trigger the modal with a button -->
<a data-toggle="modal" data-target="#indexMarkdown">
<img class="thumbnail" src="/images/tutorials/jekyll-basics/gray.png">
</a>
<!-- Modal -->
<div id="indexMarkdown" class="modal fade" role="dialog">
<div class="modal-dialog">
<!-- Modal content-->
<div class="modal-content">
<div class="modal-header">
<button type="button" class="close" data-dismiss="modal">×</button>
<h4 class="modal-title">The 'index.md' File</h4>
</div>
<div class="modal-body">
<p>
In this project, the index.md file serves as the homepage of the site. Jekyll will look for an 'index.md' or 'index.html' file to open first upon launching.
</p>
<p>
The extension .md is shorthand for mark down. Much like an HTML file, a markdown file will allow a user to display text, but without having to worry about the coding aspect of HTML.
</p>
<p>
For further insight into what a Markdown file is, follow the link <a href="https://guides.github.com/features/mastering-markdown/">Here</a>
</p>
</div>
<div class="modal-footer">
<button type="button" class="btn btn-default" data-dismiss="modal">Close</button>
</div>
</div>
</div>
</div>
<p id="fileText">index.md</p>
</div>
<!-- _CONFIG.YML -->
<div id="file" class="col-lg-4 col-lg-offset-2 col-sm-6">
<!-- Trigger the modal with a button -->
<a data-toggle="modal" data-target="#_config">
<img class="thumbnail" src="/images/tutorials/jekyll-basics/gray.png">
</a>
<!-- Modal -->
<div id="_config" class="modal fade" role="dialog">
<div class="modal-dialog">
<!-- Modal content-->
<div class="modal-content">
<div class="modal-header">
<button type="button" class="close" data-dismiss="modal">×</button>
<h4 class="modal-title">The '_config.yml' File</h4>
</div>
<div class="modal-body">
<p>
The _config.yml, in a sense, serves as the global settings for your Jekyll project. From here, you can configure your site by changing the title or description of your web site, configuring the gems within your project, applying a theme, and several other helpful settings.
</p>
</div>
<div class="modal-footer">
<button type="button" class="btn btn-default" data-dismiss="modal">Close</button>
</div>
</div>
</div>
</div>
<p id="fileText">_config.yml</p>
</div>
<div id="file" class="col-lg-4 col-sm-6">
<!-- Trigger the modal with a button -->
<a data-toggle="modal" data-target="#gemfile">
<img class="thumbnail" src="/images/tutorials/jekyll-basics/gray.png">
</a>
<!-- Modal -->
<div id="gemfile" class="modal fade" role="dialog">
<div class="modal-dialog">
<!-- Modal content-->
<div class="modal-content">
<div class="modal-header">
<button type="button" class="close" data-dismiss="modal">×</button>
<h4 class="modal-title">The 'gemfile' File</h4>
</div>
<div class="modal-body">
<p>
All of the gems within your project are stored here. For more information on the gemfile folder, check out the link <a href="https://learn.cloudcannon.com/jekyll/gemfiles-and-the-bundler/#what-is-a-gem">here</a>
</p>
</div>
<div class="modal-footer">
<button type="button" class="btn btn-default" data-dismiss="modal">Close</button>
</div>
</div>
</div>
</div>
<p id="fileText">gemfile</p>
</div>
</div> <!-- files gallery end -->
<!-- ADDITIONAL FILES -->
<div id="additionalFiles" class="sectionHeader">
<div class="underline" id="additionalFiles">
<p>Additional Files</p>
</div>
<b>
Note, While adding files to the directory, it is important to remember to follow the spelling as shown below. This includes having the underscore in front of specific folders names.
</b>
<p class="sectionContent">
In addition to the pages provided with our default creation, we will also need some additional folders to the project directory as well. In able to add files into the project folder, simply bring up the right click menu on the 'myjekyllsite' folder and 'new folder'.
</p>
<p class="sectionContent">
Below are the files that need to be added, click on each box to learn about individual files.
</p>
<div class="sectionContent">
<!--_INCLUDES -->
<div class="row">
<div id="file" class="col-lg-4 col-sm-6">
<!-- Trigger the modal with a button -->
<a data-toggle="modal" data-target="#_includes">
<img class="thumbnail" src="/images/tutorials/jekyll-basics/gray.png">
</a>
<!-- Modal -->
<div id="_includes" class="modal fade" role="dialog">
<div class="modal-dialog">
<!-- Modal content-->
<div class="modal-content">
<div class="modal-header">
<button type="button" class="close" data-dismiss="modal">×</button>
<h4 class="modal-title">The '_includes' Folder</h4>
</div>
<div class="modal-body">
<p>
The includes file, in the case of this tutorial, will hold any files that will require consistency throughout several pages or give an organizational advantage to have somewhere else within the directory.
</p>
<p>
For example, on many websites, both the header and footer sections of the page are all the same. With the exception of any page specific javascript or database related information, the files for these two are very much copy and paste onto every other page by being pulled from this folder.
</p>
</div>
<div class="modal-footer">
<button type="button" class="btn btn-default" data-dismiss="modal">Close</button>
</div>
</div>
</div>
</div>
<p id="fileText">_includes</p>
</div>
<!-- CSS -->
<div id="file" class="col-lg-4 col-sm-6">
<!-- Trigger the modal with a button -->
<a data-toggle="modal" data-target="#css">
<img class="thumbnail" src="/images/tutorials/jekyll-basics/gray.png">
</a>
<!-- Modal -->
<div id="css" class="modal fade" role="dialog">
<div class="modal-dialog">
<!-- Modal content-->
<div class="modal-content">
<div class="modal-header">
<button type="button" class="close" data-dismiss="modal">×</button>
<h4 class="modal-title">The 'css' Folder</h4>
</div>
<div class="modal-body">
<p>
This folder hold the styling for the site. Css files within a jekyll project, and pretty much every other web application, hold the custom and individual styles for the project. While Jekyll also supports .scss (Sass) files, we will only be using css for the sake of simplicity.
</p>
</div>
<div class="modal-footer">
<button type="button" class="btn btn-default" data-dismiss="modal">Close</button>
</div>
</div>
</div>
</div>
<p id="fileText">css</p>
</div>
<!-- _LAYOUTS -->
<div id="file" class="col-lg-4 col-sm-6">
<!-- Trigger the modal with a button -->
<a data-toggle="modal" data-target="#_layouts">
<img class="thumbnail" src="/images/tutorials/jekyll-basics/gray.png">
</a>
<!-- Modal -->
<div id="_layouts" class="modal fade" role="dialog">
<div class="modal-dialog">
<!-- Modal content-->
<div class="modal-content">
<div class="modal-header">
<button type="button" class="close" data-dismiss="modal">×</button>
<h4 class="modal-title">The 'gemfile' File</h4>
</div>
<div class="modal-body">
<p>
This file holds the layouts for your site. Layouts allow a user to create and apply individual themes to each page of their Jekyll site. Much like applying a theme to a wordpress site, Jekyll allows the customization of page content by only having to modify the body, relieving the worry of your new content causing unknown bugs within the header, footer, or any other peripheral file.
</p>
</div>
<div class="modal-footer">
<button type="button" class="btn btn-default" data-dismiss="modal">Close</button>
</div>
</div>
</div>
</div>
<p id="fileText">_layouts</p>
</div>
</div>
<p class="sectionContent">
Before moving on throughout this tutorial, make sure to delete the 'index.md' file and replace it with an 'index.html' file. This will allow us to use HTML on our index file.
</p>
</div>
Creating Your First Page
<b>
Note, due to the nature of how the steps for this section were laid out, it would be best to restart/start your project server after all of the steps in the 'Ceating Your First Page' section have been completed. Specifically, after creating your content and before styling your page.
</b>
<div>
<p class="sectionContent underline">
Front Matter and Content
</p>
<p class="sectionContent">
A Jekyll page consists of two main parts, the <a href="https://jekyllrb.com/docs/frontmatter/">front matter</a> and the content.
</p>
<div class="sectionContent">
<div class="row">
<div class="col-lg-5">
<p class="underline subsection center">Front Matter</p>
<img class="thumbnail" src="/images/tutorials/jekyll-basics/frontMatter.png">
<p class="subsection">
Very much like the config.yml, in the sense that it can control settings on specific pages. The difference, however, being that while a config.yml file can control settings for multiple elements across several pages, the front matter of a Jekyll file can only control the settings for the page in which it is located.
</p>
</div>
<div class="col-lg-5 col-lg-offset-2">
<p class="underline subsection center">Content</p>
<img class="thumbnail" src="/images/tutorials/jekyll-basics/content.png">
<p class="subsection">
The content of a Jekyll page contains all of the body text, everything in between the headers and footers.
</p>
</div>
</div>
</div>
</div>
<p class="sectionContent">
At this point, you should have already replaced the 'index.md' file within the directory with an 'index.html' file. If not, then simply delete the “index.md” file from your Jekyll project and add a new one by the name of “index.html” into the root directory.
</p>
<!-- creating the font matter -->
<div>
<p class="underline sectionHeader">
Creating The Front Matter
</p>
<p class="sectionContent">
The front matter in this tutorial will consist of only a layout, and will implement custom paths in a further section. On your empty Index.html page, apply this code:
</p>
{% highlight ruby %}
layout: home
{% endhighlight %}
<b>
Note, when applying layouts to a page through this matter, the extension '.html' does not need to be applied to the name just as above.
</b>
<p class="sectionContent">
This code will allow us to pull a layout from the “_layouts” page as our layout. Next, after telling our file to pull the layout, we must now create one in able for our page to have something to load.
</p>
</div>
<!-- creating the layout -->
<div>
<p class="underline sectionHeader">
Creating The Layout
</p>
<p class="sectionContent">
From within our _layouts folder, create a file by the name of “home.html”, and then open it in our text editor.
</p>
<p class="sectionContent">
Because our layout file will dictate how our page is presented, we will need to create the outline of our layout for jekyll to fill in upon load. The code below shows how we will structure our home page layout. Copy and paste this into your empty home file in the _layouts directory.
</p>
<pre>
<!DOCTYPE html> <html> <head> {% include header.html %} {% include head.html %} </head> <body> <div class="page-wrap">
{{content}}
</div>
<footer class="site-footer">
{% include footer.html %}
</footer>
</body> </html>
</div>
<div>
<p class="sectionContent">
From this code snippet we can see that our home page will include both the header and header files, the page content below that, and then the footer last.
</p>
<img class="thumbnail" src="/images/tutorials/jekyll-basics/includes.png">
</div>
<div class="sectionContent">
<p>Now to create the Header, Head, and Footer files for this layout to include. Within the '_includes' folder, add these files below with the names exactly as they are shown. Click on the individual names to receive the code to copy and paste into each corresponding file.</p>
<div id="file" class="col-lg-4 col-sm-6">
<!-- Trigger the modal with a button -->
<a data-toggle="modal" data-target="#header">
<img class="thumbnail" src="/images/tutorials/jekyll-basics/gray.png">
</a>
<!-- Modal -->
<div id="header" class="modal fade" role="dialog">
<div class="modal-dialog">
<!-- Modal content-->
<div class="modal-content">
<div class="modal-header">
<button type="button" class="close" data-dismiss="modal">×</button>
<h4 class="modal-title">The 'header' File</h4>
</div>
<div class="modal-body">
<p>
Within the header file is the navbar of our site.
</p>
<p class="sectionContent">
<pre>
<xmp>
</div>
<div class="modal-footer">
<button type="button" class="btn btn-default" data-dismiss="modal">Close</button>
</div>
</div>
</div>
</div>
<p id="fileText">header.html</p>
</div>
</div>
<!-- CSS -->
<div id="file" class="col-lg-4 col-sm-6">
<!-- Trigger the modal with a button -->
<a data-toggle="modal" data-target="#head">
<img class="thumbnail" src="/images/tutorials/jekyll-basics/gray.png">
</a>
<!-- Modal -->
<div id="head" class="modal fade" role="dialog">
<div class="modal-dialog">
<!-- Modal content-->
<div class="modal-content">
<div class="modal-header">
<button type="button" class="close" data-dismiss="modal">×</button>
<h4 class="modal-title">The 'head' File</h4>
</div>
<div class="modal-body">
<p>
The head file in the tutorial site will contain the title, Bootstrap CND, and link to our stylesheet.
</p>
<p class="sectionContent">
<pre>
<xmp>
</div>
<div class="modal-footer">
<button type="button" class="btn btn-default" data-dismiss="modal">Close</button>
</div>
</div>
</div>
</div>
<p id="fileText">head.html</p>
</div>
<!-- _LAYOUTS -->
<div id="file" class="col-lg-4 col-sm-6">
<!-- Trigger the modal with a button -->
<a data-toggle="modal" data-target="#footer">
<img class="thumbnail" src="/images/tutorials/jekyll-basics/gray.png">
</a>
<!-- Modal -->
<div id="footer" class="modal fade" role="dialog">
<div class="modal-dialog">
<!-- Modal content-->
<div class="modal-content">
<div class="modal-header">
<button type="button" class="close" data-dismiss="modal">×</button>
<h4 class="modal-title">The 'footer' File</h4>
</div>
<div class="modal-body">
<p>
The footer file will include the footer section of our site, which holds the javascript and any extra text.
</p>
<p class="sectionContent">
<pre>
<xmp>
This is the footer file
</xmp>
</pre>
</p>
</div>
<div class="modal-footer">
<button type="button" class="btn btn-default" data-dismiss="modal">Close</button>
</div>
</div>
</div>
</div>
<p id="fileText">footer.html</p>
</div>
Now that we have all the includes for our home page, let’s go on to creating the content.
<div>
<p class="underline sectionHeader">
Creating The Content
</p>
<p class="sectionContent">
Luckily, the harder part of creating the home page is behind us, and now that we have our layout set up, we can simply type up some content for our page.
</p>
<p class="sectionContent">
Underneath your front matter on the “index.html” file, go ahead and type up a sentence or two of raw text into the specified location below as an introduction to the site, just as if you were typing in a Microsoft Office document.
</p>
<img class="thumbnail" src="/images/tutorials/jekyll-basics/content2.png">
<p class="sectionContent">
Even though simply placing raw text within a .html file may seem wrong at first, as you will see, it is very much doable. In addition to being able to process raw text, jekyll will also accept html code in able to better organize and style your page just as any other html file. For example, <div> and <p> tags WILL WORK here.
</p>
<p class="sectionContent">
Something to keep in mind when creating pages is that every page will need a layout, and if a layout is not specified, our will not be applied and none of the includes that we have within our layout would be activated. After a layout has been created, it can be applied to a page by telling it to do so from within the front matter of that specific page.
</p>
<p>
Upon relaunching, your page should look like this.
</p>
<img class="thumbnail" src="/images/tutorials/jekyll-basics/unstyled-page.png">
</div>
</div>
Styling Your Page
<p class="sectionContent">
In able to keep our directory organized, make a file called “main.css” within the css folder of our project, and just as before, I will provide you with some code in able to expedite this step, all you will have to do is copy the code snippet below and paste it into the main.css file you just created.
</p>
<pre>
body{ overflow-y: hidden; text-align: center; }
- { margin: 0; } html, body { height: 100%; } .page-wrap { min-height: 100%; /* equal to footer height */ margin-bottom: -142px; } .page-wrap:after { content: ""; display: block; } .site-footer, .page-wrap:after { height: 142px; } .site-footer { background: #F8F8F8; }
.site-footer p{ text-align: center; padding-top: 2%; }
<p>
After styling your page, it should look like the image below. With the main.css file attached to your head, it will allow you to edit any element within the web page.
</p>
<img class="thumbnail" src="/images/tutorials/jekyll-basics/styled-page.png">