Nested Layouts for Clean Architecture

Nested Layouts for Clean Architecture

Why Layout Architecture Matters in Static Sites

As your Jekyll site grows in complexity—adding blog posts, documentation, landing pages, and custom sections—your layout files can become bloated. Nested layouts allow you to separate concerns, improve reuse, and scale your HTML templates with a modular approach.

The Concept of Layout Inheritance

Jekyll allows layouts to inherit from other layouts using the layout key in the front matter of a layout file. This means you can define a base layout that handles your global HTML scaffolding, and then child layouts that insert their own structure or components.

Example: Building a Modular Layout Hierarchy

Imagine a site that has:

A universal base layout with the doctype, head, and body wrapper
A page layout for general pages
A blog layout for articles with metadata and timestamps
A docs layout that adds a sidebar and TOC

Step 1: Create a Base Layout



<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>{{ page.title }} - {{ site.title }}</title>
  <link rel="stylesheet" href="/assets/css/main.css">
</head>
<body>

  {% include shared/header.html %}

  <main class="main-content">
    {{ content }}
  </main>

  {% include shared/footer-widgets.html %}

</body>
</html>

Step 2: Define a Page Layout



---
layout: base
---

<section class="page-wrapper">
  {{ content }}
</section>

Step 3: Create a Blog Post Layout



---
layout: base
---

<article class="post-container">
  <h2>{{ page.title }}</h2>
  <p class="meta">Posted on {{ page.date | date: "%B %d, %Y" }}</p>

  <div class="post-body">
    {{ content }}
  </div>
</article>

Step 4: Create a Docs Layout



---
layout: base
---

<div class="docs-layout">
  <aside class="sidebar">
    {% include docs/sidebar.html %}
  </aside>

  <div class="docs-content">
    {{ content }}
  </div>
</div>

Why Nested Layouts Are Powerful

Separation of concerns: Base layout handles global structure. Others focus on specific content areas.
Performance boost: Less redundancy means faster build times.
Scalability: You can add new layouts for new sections without touching the global markup.

Real-World Use Case: Multi-Language Docs Site

In a multilingual site using Jekyll, each language section can have its own layout extending from the same base. You might create:

_layouts/docs-en.html → layout: base
_layouts/docs-fr.html → layout: base

Each pulls the correct localized sidebar and TOC structure, while reusing shared HTML from the base layout.

How to Test Nested Layouts

Create a test layout and set its parent using layout: in the front matter.
Render a page with that test layout and observe the combined output.
Use browser developer tools to confirm block-level output and structure.

Build Tree Example


page.md
→ layout: post
  → layout: base

Jekyll recursively renders from the top (base) to the innermost layout (post), placing {{ content }} at each level accordingly.

Best Practices for Layout Composition

1. Always Use a Base Layout

Even if your site is small, a base layout ensures consistency across all pages and makes future refactoring easier.

2. Avoid Deep Nesting

Try not to nest more than 2–3 levels of layouts. Too many levels make debugging harder and increase cognitive load.

3. Document Your Layout Tree

In your internal wiki or repository, include a visual representation or list of which layout extends from what.

Fallbacks and Defaults

When no layout is specified, Jekyll skips layout rendering. To apply a base by default, add it in your collection config:


defaults:
  - scope:
      path: ""
    values:
      layout: base

Performance Considerations

Nested layouts are resolved at build time, so there's minimal runtime cost
Builds are faster when using includes inside layouts versus repeating HTML across pages
Smaller diffs in version control when structure is centralized

Conclusion

Nested layouts provide a flexible, scalable, and maintainable structure for any Jekyll project hosted on GitHub Pages. By creating a clear hierarchy—from base to post or page layouts—you future-proof your design system and simplify collaboration.

What’s Next

In the next article, we’ll explore conditional includes and logic in layouts—how to make your templates dynamic without JavaScript or external tooling.