Generated Sites
This chapter will covers installing and running Jekyll, site structure, configuration, and creating pages.
A static website contains only HTML, CSS and JS.
The word “static” means “unchanging”. A static website displays the output of files you have written, as you wrote them.
In contrast, the word “dynamic” means “changeable”. A dynamic website uses the files you have written to create pages as needed, for example creating a product page for every product in the database.
A Static Site Generator is a computer program which
Using a static site generator we can still do many of the “dynamic” actions of a dynamic website, such as generating a product page for every product in a list (no databases though!).
The main difference is that the files we publish are still static. We “dynamically” generate the “static” files for the website.
Static site generators are helpful for creating simple sites
The layout is written in one file, and the content which should be inserted into the layout is written in another file.
This makes it fairly easy to update content without worrying about accidentally breaking the layout.
By letting a static site generator do the hard work, we don’t have to worry about introducing complexity to our site by including a database and a server-side language like Python, Ruby or PHP.
As a site gets bigger and more complex you may decide that it would be better to build a full-stack project using a database and a server-side language.
Static site generators are good for small to medium-sized sites, and it’s up to you to decide if your site is big enough that it needs to evolve.
Jekyll
The most popular static site generator.
Jekyll is the static site generator we will be using for this course.
It’s the most popular one in use today. It was created by engineers at GitHub, the most popular website for publishing and sharing open source code projects.
There are many static site generators,
Top static site generators
Jekyll is just one of many static site generators. Some other popular ones are Gitbook and Octopress.
Each static site generator has different strengths, so you might choose a different one for a different purpose.
Once you understand how one static site generator works, it should be fairly straighforward to understand other ones with the help of tutorials on their websites.
Jekyll was originally created for blogging,
It’s most commonly used for small promo websites, blogging, and for project documentation.
Jekyll has support for blog posts, pages, and custom categories for a product shop or image gallery.
Even this website and slideshow are built in Jekyll!
Jekyll is a program that runs on your computer,
To use Jekyll, you install it on your computer and then run it from a website project folder. Jekyll then turns the website files into an actual website you can view in your web browser.
Jekyll is written using the Ruby programming language,
If you are unable to install Ruby or Jekyll on your computer, we recommend creating an account with CloudCannon and skipping the install instructions here.
Instead, go straight to creating a project and skip any bits talking about the command line.
Install Ruby
Windows Download here Mac
Run the installer and complete the installation process.
Ruby comes pre-installed on Macs, but you will still need to check that you have the correct version in the next step.
Windows users need to run the installer.
Open a command line so that we can check
You should have CMD or Terminal open.
We’ll be using the command line a lot when working with Jekyll, so you may want to lock the app to your taskbar or launcher bar for easy access.
To check if Ruby is installed correctly, ruby -v and press enter.
The displayed Ruby version should be 2.0.0 or higher.
If you have a higher version than 2.0.0 that’s fine, just make sure it’s not version 1 of Ruby!
Install Jekyll
In your command window, type in gem install jekyll and press enter.
Wait for the Jekyll installer to complete.
The gem program was installed along with the ruby programming language. In Ruby, a gem is a program written in Ruby which has been published for other developers to download and use. Jekyll is a Ruby Gem.
You can browse other published gems on the RubyGems website.
Check Jekyll is installed by typing in jekyll -v and then pressing enter.
Your Jekyll version should be 3.0.0 or higher.
If you have a higher version it’s fine, it just means a new version of Jekyll has been released since these instructions were written. That’s cool, new stuff!
Creating a Project
Create a new folder on your computer with jekyll-site.
This name can be changed later.
Create a folder called jekyll-site in a safe place.
You can create this folder anywhere you like, but we recommend having a Projects folder where you keep all of your programming projects so you don’t accidentally misplace them!
Open the project folder in your favourite
Open your project in a text editor.
Create an index page
Create an index.html in your project folder,
<!doctype html>
<html>
<head>
<title>My Jekyll Site</title>
</head>
<body>
<h1>Hello!</h1>
</body>
</html>
Make sure to save your index page!
Jekyll Configuration
Create a new file in your project called _config.yml and add the following code.
name: Jekyll Site
For a set of files to be considered a Jekyll site, we need to add a configuration file with some information for the Jekyll app, and we need our project to have a specific structure.
The bare minimum we need is a name for our site.
We will add more configurations here as we need them.
It is also a good idea to specify
name: Jekyll Site
version: 3.0.3
Make sure to save your configuration file!
Different versions of Jekyll have different functionality, so it’s a good idea to specify the version so that others running your code know which version to use.
If you are using Jekyll via the command line, your version number is the one you see when you run jekyll -v from the command line.
CloudCannon supports Jekyll versions 2.4.0, 2.5.3, and 3.0.3. You should use 3.0.3 which is the newest version.
If you do not specify a version, 2.4.0 will be used.
CloudCannon Jekyll Documentation
Running Your Site
Using the command line,
Run your site from the command line by jekyll serve and pressing enter.
Running jekyll serve generates a website from your project files and starts a web server so you can preview it in a web browser.
The serve command also watches out for any changes to your project. That means that every time you change a file and save it, Jekyll will automatically rebuild your website.
In your browser, go tohttp://localhost:4000/
You should see the word “Hello!”
The website “localhost” is a name for your own computer, when your computer is running a web server.
Jekyll started a web server for us, which is why we can see the site on the localhost URL.
4000 is the port number. You can run more than one website on your computer at the same time, so using different port numbers allows us to look at each different site while still using the localhost URL.
Closing the command line will shut down your website preview.
Because we are running Jekyll from the command line, it will only continue to run as long as the command window is open.
If you close the window or type Ctrl+C, Jekyll will stop running and the localhost web server will shut down until you run jekyll serve again.
The Site Folder
After running jekyll serve, you’ll see _site was created.
This is the generated output of your project.
These files are the “static files” we were talking about. As your Jekyll site becomes more complex, you’ll begin to see the differences between the “input” files (your project files) and the “output” files (your site files).
Every time you make a change,
Because the site files are generated, make sure when you’re editing that you don’t try editing these files, as any changes you make will be overwritten.
If you were uploading to a web server which didn’t support Jekyll,
The files in the site folder don’t need Jekyll to run them. They were generated by Jekyll, but once they’re generated they’re just plain HTML, CSS and JavaScript.
Some hosting providers support Jekyll, which means
GitHub and CloudCannon both support Jekyll.
These sites don’t even show you your site folder, they just take your input project files and generate the site output in the background.
Adding Pages
Extra pages can be added by making
For individual website pages, you create one file for each page just like in a normal website.
Create a new page called contact.html
<!doctype html>
<html>
<head>
<title>My Jekyll Site</title>
</head>
<body>
<h1>Contact Me!</h1>
</body>
</html>
Make sure to save your contact page!
This page is identical to the index page, except for the heading text.
Preview in your browser at localhost:4000/contact.html.
Because we are running jekyll serve, this new page will be automatically picked up by Jekyll, and will be available on localhost after a couple of seconds delay.
All your pages can be found on localhost, with a forward slash followed by the file name for pages other than the index page.
Summary
Config Files Creating Pages Live Preview
Now that we’ve covered the basics of running a Jekyll site, we can begin to introduce some of the nifty tricks it offers us.
Generated Sites: Complete
Next Chapter
You’ve completed the Generated Sites chapter, well done!
Continue to the next chapter for more.
