How Does Jekyll Layouts Directory Shape the Look of Your GitHub Pages Site

By -

When building a GitHub Pages blog with Jekyll, you will quickly discover the _layouts directory. This folder is not just another storage space—it is the engine that determines how your posts and pages appear. While the _posts folder gives you content, the _layouts folder gives your site its structure and design. Beginners often ask: “What exactly is a layout?” and “Why does Jekyll need a separate folder for them?” In this guide, we will walk step by step through the purpose of Jekyll layouts and how you can use them effectively to design a professional-looking GitHub Pages site.

Main Questions Answered in This Guide

What are layouts and how do they work in Jekyll

Layouts in Jekyll are templates stored in the _layouts folder. They define the structure of your pages without containing the actual content. Instead, content from your posts or pages is injected into the layout wherever you place the {{ content }} tag. This separation allows you to maintain consistent design across your entire site while still being free to write different content for each page.

For example, you may have one layout for blog posts, another for standalone pages like “About” or “Contact,” and yet another for special sections like documentation. By keeping structure and content separate, you can change your site’s appearance without rewriting every post.

What default layouts are commonly used

Most Jekyll sites include at least two common layouts:

  • default – The base layout, usually containing your site’s header, navigation, and footer. Other layouts often extend this one.
  • post – A layout specifically for blog articles. It might include metadata like the author, date, and categories above the post content.

Beyond these, you can create as many custom layouts as you need. For example, if you want a portfolio section on your site, you could create a portfolio.html layout. The key is to keep them organized and name them clearly so you know what each layout is for.

How layouts use Liquid to structure your site

Layouts make heavy use of Liquid, the templating language Jekyll relies on. The most important tag inside layouts is {{ content }}, which tells Jekyll where to insert the body of your post or page. Beyond that, you can add conditional statements, loops, and variables to control how different parts of your site appear.

For example, you might add:

{% if page.categories %}
  <p>Categories: {{ page.categories | join: ", " }}</p>
{% endif %}

This snippet checks if a page has categories and, if so, displays them. Using Liquid in layouts allows you to automate design features without writing code into every single post.

How to choose a layout for posts and pages

When you create a new post or page, you can specify which layout to use by adding a layout key in the front matter:

---
title: "My First Post"
date: 2025-09-25
layout: post
---

If you do not specify a layout, Jekyll will not apply one, which can result in a page with raw content and no structure. Therefore, always double-check that your posts and pages have the correct layout assigned in their front matter.

This feature also makes it possible to experiment with multiple designs. For instance, you can create two layouts, apply them to the same content, and compare which one looks better.

Can layouts use other layouts

Yes, Jekyll supports nested layouts. This means you can create a post.html layout that extends a default.html layout. Inside the post layout, you can place {{ content }}, which in turn is inserted into the default layout’s {{ content }} section. This layering makes it easy to maintain consistency while still giving different sections of your site unique designs.

For example, your default.html might include your site-wide navigation and footer, while post.html adds metadata and styles specific to blog articles. If you ever decide to redesign your header or footer, you only need to edit default.html, and the changes will flow to all other layouts.

Tips for customizing layouts to match your brand

Layouts are one of the best ways to give your blog a personal touch. Here are some tips for customizing them:

  • Add your brand colors and logo in the header.
  • Design a footer with useful links like “Privacy Policy” or “Contact.”
  • Use CSS classes in layouts to style repeated elements consistently.
  • Experiment with including sidebars or call-to-action banners.

By making small adjustments to your layouts, you can transform a plain Jekyll site into something unique and memorable. This is especially important for blogs that want to stand out among thousands of others on GitHub Pages.

Common mistakes when working with layouts

Beginners often encounter issues like:

  • Forgetting to add {{ content }}, which causes the page body not to appear.
  • Assigning the wrong layout name in front matter, leading to missing design elements.
  • Breaking Liquid syntax inside layouts, which can stop your site from building correctly.

Fortunately, these mistakes are easy to fix once you understand the role of layouts. Always test your site locally before pushing changes to GitHub Pages to avoid publishing errors.

How good layouts improve SEO and readability

Well-structured layouts are not just about appearance—they also affect SEO. Search engines rely on consistent headers, meta tags, and structured content to understand your site. By defining these elements in layouts, you ensure every page includes them without having to repeat code manually.

For instance, you can add an SEO plugin or define meta descriptions in your layout’s <head> section. You can also make sure that headings follow a logical hierarchy, which improves accessibility and readability for your visitors.

What comes after mastering layouts

Once you are comfortable with layouts, the next step is to explore the _includes folder. While layouts give you the big picture structure, includes allow you to reuse small code snippets across different layouts. The two work hand in hand to create a flexible, modular design system for your Jekyll site. Together, they will give you complete control over both the structure and the details of your GitHub Pages blog.

By practicing and experimenting with layouts, you will develop a deeper understanding of how design and content interact in Jekyll. This knowledge is a major step toward building professional, scalable websites on GitHub Pages.

Final Thoughts

The _layouts directory is the backbone of your Jekyll site’s design. By mastering how layouts work, choosing the right structure, and avoiding common mistakes, you can build a consistent and visually appealing blog. More importantly, layouts save time and effort, allowing you to focus on writing content while Jekyll handles presentation. With this skill, you are well on your way to creating a blog that not only looks great but also performs well in search engines.

What Should You Do Next

Try creating a new layout file inside the _layouts folder. Assign it to one of your posts and see how the design changes. Experiment with nested layouts to separate global design elements from section-specific ones. Once you are comfortable, move on to the _includes directory, where you will learn how to create reusable components like headers, footers, and navigation bars. This will give you even greater control over your site’s design and usability.