Laying It All Out

This chapter is from the book

Learn Enough HTML, CSS and Layout to Be Dangerous: An Introduction to Modern Website Creation and Templating Systems

Learn More Buy

This chapter is from the book

This chapter is from the book 

Learn Enough HTML, CSS and Layout to Be Dangerous: An Introduction to Modern Website Creation and Templating Systems

Learn More Buy

9.3 Layouts, Includes, and Pages (Oh My!)

One of the most powerful features of Jekyll is its ability to factor different parts of a website into reusable pieces. To accomplish this, Jekyll uses a system of folders and conventional names for files, along with a mini-language called Liquid. Originally developed by Tobi Lütke, cofounder of online store powerhouse Shopify,⁶ Liquid is a system for adding content to a site using what are in effect simple computer programs.

Files inside a Jekyll project can be static, meaning that they do not get processed by the Jekyll engine, or they can be dynamic and get constructed with Jekyll magic. (The site is still static because it consists of static files on the server, even if those files are generated dynamically by Jekyll. In other words, the files don’t change once they’ve been generated by Jekyll, so the results are the same for every visitor of the site.)

There are four main types of magic objects/files that the Jekyll engine can use in an automated way to build your site:

• Layouts/layout templates

• Includes

• Pages/page templates

• Posts

We’ll discuss each of these in abstract terms for reference, but their exact uses won’t become clear until we see some concrete examples starting in Section 9.4.

9.3.1 Layouts/Layout Templates

Anything in the special _layouts directory (which we’ll create in Section 9.4) can have Jekyll magic, meaning those files get read by the engine looking for Liquid tags and other Jekyll formatting.

One of the key parts of many Jekyll pages is frontmatter, which is metadata at the top of an HTML file (in YAML format) that identifies the kind of layout to be used, a page-specific title, etc. A fairly complicated example might look like this, where the frontmatter is everything between the two triple-dashes ---:

---
layout: post
title: This is the title of the post
postHero: images/shark.jpg
author: Me, Myself, and I
authorTwitter: https://twitter.com/mhartl
gravatar: https://gravatar.com/avatar/ffda7d145b83c4b118f982401f962ca6?s=150
postFooter: Additional information, and maybe a <a href="#">link or two</a>
---

<div>
  <p>Lorem ipsum dolor sit paragraph.</p>
<div>

In a simpler but still common example, the frontmatter identifies only the page layout template to be used when rendering the page:

---
layout: default
---

<div>
  <p>Lorem ipsum dolor sit paragraph.</p>
<div>

We’ll see the effects of this sort of code starting in Section 9.4.

If there is no frontmatter in a layout file, then it is a true layout, and it needs to have a full HTML page structure. If there is frontmatter, then the file is a layout template that can be built into other layouts, and it doesn’t need to have a full HTML page structure.

Layouts are often the most base-level objects, defining a standard page with a DOCTYPE, html/head/body tags, meta tags, stylesheet links, JavaScript, etc., and they usually pull in snippets like a site header or site footer. You often need only one default layout for a site, but you can also use layout templates for things like blogs (Section 12.3).

Layouts have the special ability to load content, like posts, using a generic Liquid tag that looks like this: {{ content }}. We’ll see a short example of this in an exercise (Section 9.6.3), and we’ll apply it to our full site in Chapter 10.

9.3.2 Includes

Files in the _includes folder can have Jekyll magic even though they don’t need frontmatter, and these files are always intended to be built into something else. Includes tend to be little snippets of a site that get repeated on many pages, such as the header and footer (Figure 9.1) or a standard set of social media links. Includes will be covered in Section 9.6.

9.3.3 Pages/Page Templates

Any other HTML file in the project directory is a page. If there is no frontmatter in the file it is a static page, and Jekyll magic will not work (Liquid tags go unprocessed). If a page has frontmatter, though, it will need to specify a layout, and then all the Jekyll magic will be available. We’ll cover pages more in Chapter 10.

9.3.4 Posts, and Post-Type Files

Posts are self-contained pieces of content, such as blog posts or product details, that are saved as files in the _posts directory. Some forms of content (like blog posts) are typically organized by date, while others (like product descriptions) are organized based on other attributes into collections. We’ll discuss posts further in Chapter 12; collections are beyond the scope of this tutorial, but you can read about them in the Jekyll documentation on collections (https://jekyllrb.com/docs/collections/).