Jekyll usage

This page is an introductory guide that explains what Jekyll is and how we use it.

What Jekyll Does

Jekyll is a static webpage generator. Say you want a header and a footer on your website. In vanilla HTML, you'd have to copy and paste this for every file. What Jekyll does is it allows us to create layouts, or templates, that can be reused, and updated quickly.

How It Works

First, lets note the following folders in the website home directory:

• _layouts
• _includes
• _site

These are folders used by Jekyll. Normally, Jekyll takes all the files in the site directory and compiles them based on their folder directory into web pages (for example, get-involved/index.html has the web address pioneers.berkeley.edu/get-involved). The final compiled HTML files that work on their own are placed into the _site folder. The exception is that folders or files marked with a "_" in the front are not compiled by Jekyll into webpages. The _site folder should never be directly edited, because it'll just be overwritten by the next time jekyll serve is run.

Using Layouts

Let's step back and look at the overall view of how we use layouts. First, we would have a layout file, which is like a customizable blueprint that has certain features we'd like to reuse. Then, we'd like to create new HTML webpages that use this layout file. In Jekyll, the layout files are contained in _layouts, and the webpage files would rely on these layouts, upon request.

Layout files are HTML files, except with Liquid/Jekyll tags, which often have these symbols: {} or %. For example, the "default" layout that PiE uses, in _layouts/default.html, describes to Jekyll how to place:

• a header (which includes a navbar),
• a hero image and message,
• and a footer.

In this file, you would use the tag {{content}} to describe where all the page content of a HTML files that uses this layout goes. For example, about/about-us.html looks kind of empty (it doesn't even have a body tag), but it will be compiled with the default layout. These layout files look kind of odd and wouldn't work if you just open them, but Jekyll will compile them into full HTML files using whatever cool beans you inserted into your HTML, and you can see the results using jekyll serve.

Thus, a webpage that uses this template would need to declare what template to use, and other details about the page, which is done in Jekyll frontmatter at the top of the html file. about/about-us.html declares in the frontmatter (denoted by --- markers) by setting the layout to default (layout: default), and thus Jekyll will take this page and build it using the default layout. Note that it also declares other things such as the image to use for the hero image (hero-image), and the message (hero-message). These are all fields that we designed in the default.html layout. If you're familiar with Object Oriented Programming or Java, we can thinking of this as treating pages as objects that can call the layout constructors, which we can think of as our classes, or blueprints, and allowing easy templating through easily extensible and modular parts.

Going back to the layout file, you can access these variables under page, such as page.hero-message, and inject them into your HTML via {{ page.hero-message }}. Jekyll does the work for you by converting it into real HTML. You can treat page as an object that is passed to the constructor, or layout blueprint.

Interactive Learning

• Think about how you can create a new layout. What are the steps required? What tags should you have? What extensible arguments woud you pass in (for example, a background-image, or header-color field).
• Now think about how you would use this layout in a new webpage. What do you need in a webpage that relies on a Jekyll layout?

Further resources

• See the Jekyll docs for an explanation of directory structure
• Cooler uses of Jekyll: to create injectable HTML that can be created whenever needed, and to use Liquid so to extend HTML to have programming features. See Jekyll Docs for more, or about/team.html for "list comprehensions" using yaml data files.