Minimize Repetition with Shared Blocks

The Cost of Repetition in Static Sites

When building a Jekyll site, especially one that evolves over time, repetition can quickly become your enemy. Copying and pasting similar HTML structures across pages or layouts bloats your codebase, increases maintenance overhead, and negatively impacts build times. One change might require multiple edits, and that’s an opportunity for human error.

Introducing Shared Blocks

Shared blocks are reusable pieces of content—either HTML or Markdown—that serve the same purpose across multiple layouts, pages, or posts. By extracting them into dedicated includes, you dramatically reduce repetition while keeping your templates clean and modular.

Common Repetitive Patterns to Refactor

1. Call to Action Buttons

Instead of copying the same CTA code snippet across every post or section, move it to a shared include:

<div class="cta-banner">
  <p>Enjoying the content?</p>
  <a href="/subscribe/" class="cta-button">Subscribe Now</a>
</div>

{% include shared/cta-default.html %}

2. Page Footers with Repetitive Widgets

Footers often contain repeated sections: social links, copyright, newsletter box.

<footer class="site-footer">
  <div class="social">
    <a href="https://x.com">X</a>
    <a href="https://github.com">GitHub</a>
  </div>
  <p>© {{ site.time | date: "%Y" }} {{ site.title }}</p>
</footer>

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

Designing a Shared Block Strategy

Start by identifying repeated structures. Then group them into logical categories such as:

• cta – call-to-action banners
• nav – navigation headers and sidebars
• meta – post meta info
• widgets – newsletter boxes, recent posts, etc

Organize by Purpose

Use subfolders in _includes/ like _includes/shared/, _includes/components/ to keep your includes logically structured.

Use Parameterized Includes

Pass parameters to customize content without creating duplicates.

{% include shared/cta.html message="Download our guide" link="/guide/" label="Get It Free" %}

Case Study: Refactoring a Documentation Site

Original Structure

• 4 layout files all contained hardcoded “next page” buttons
• 7 different places included identical newsletter signup forms

Refactoring Actions

• Created _includes/shared/next-page.html and _includes/shared/newsletter-form.html
• Used one-liner includes in all layouts instead of duplication

Result

• Reduced ~180 lines of HTML across the site
• Improved readability and structure for contributors
• Future updates became centralized

Best Practices for Shared Blocks

1. Document Each Block

Especially when using parameters, it’s helpful to include documentation in a README.md or in a pattern library page on the site itself.

2. Keep Blocks Purpose-Specific

Don’t try to make one partial do everything. Instead, keep them small and single-purpose. For example, separate “CTA Primary” and “CTA Minimal.”

3. Version Your Shared Components

For large teams or multi-version docs, consider versioning or namespacing shared blocks.

/_includes/v1/shared/
/_includes/v2/shared/

Advanced Example: Configurable Alert Banner

<div class="alert {{ include.type }}">
  <strong>{{ include.title }}</strong>
  <p>{{ include.message }}</p>
</div>

{% include shared/alert.html type="warning" title="Notice" message="This section is being updated." %}

Visual Maintenance Using Includes

One benefit of using shared blocks is visual predictability. When each component has one source of truth, your site maintains consistent design regardless of content.

Shared blocks act as your visual system components. You don’t need a design system framework—just structured includes and clear class names.

When Not to Use Shared Blocks

• When the block is extremely unique per page
• When the include becomes too nested and hard to debug
• If shared logic introduces layout-specific problems

Transitioning Legacy Layouts to Shared Blocks

If you inherit a large codebase, use this workflow:

1. Identify repeated chunks using browser dev tools or pattern search (e.g., grep or VS Code's Find)
2. Extract each into _includes/shared
3. Test new includes on staging URLs or branches
4. Iterate and progressively enhance

Conclusion

Shared blocks are a simple yet powerful way to reduce repetition and streamline your Jekyll site. From CTAs to footers and meta data, shared includes promote modularity, easier maintenance, and scalable performance for your GitHub Pages projects.

What’s Next

Next, we’ll explore how to combine includes and layouts using nested layout structures to create an even more powerful and reusable templating system in Jekyll.