getting-started

Includes Structure

Jekyll Theme Includes Structure

Overview

The _includes directory is a crucial part of Jekyll’s modular design, allowing you to break your site into reusable components. This documentation provides a comprehensive guide to the includes structure and usage.

Directory Structure

1. Components Directory

Reusable UI components for various site sections.

Subdirectories:

  • Breadcrumbs: Navigation aids showing current page location

    • Helps users understand site hierarchy
    • Improves navigation experience

  • Clients: Client logo and showcase components

    • Carousel and grid layouts
    • Responsive design for client logos

  • Contact: Contact-related components

    • Contact forms
    • Contact information displays
    • Interaction elements

  • Modals: Popup and modal window components

    • Various modal styles
    • Dynamic content loading
    • Responsive design

  • Portfolio: Portfolio display components

    • Grid and masonry layouts
    • Project filtering
    • Detail views

  • Shop: E-commerce related components

    • Product cards
    • Shopping cart elements
    • Product listing layouts

  • Team: Team member display components

    • Member cards
    • Team carousel
    • Social media integration

2. Core Directory

Essential site-wide foundational includes.

Subdirectories:

  • Head: HTML <head> related includes

    • Meta tags
    • SEO configurations
    • External resource links

  • Scripts: Core JavaScript includes

    • Site-wide script management
    • Performance optimization

  • Styles: Core CSS and styling includes

    • Global style configurations
    • Responsive design principles

3. Layouts Directory

Structural layout components.

Subdirectories:

  • Footer: Site footer variations

    • Multiple footer designs
    • Responsive layouts
    • Social media and contact links

  • Header: Site header components

    • Navigation integration
    • Responsive design
    • Logo and branding elements

  • Navigation: Navigation menu components

    • Dropdown menus
    • Mobile navigation
    • Accessibility features

  • Sidebar: Supplementary content areas

    • Blog sidebars
    • Widget containers
    • Responsive design

4. Posts Directory

Blog and post-related includes.

Files:

  • author.html: Author information display
  • carousel-layout.html: Post carousel component
  • gallery-layout.html: Post gallery display
  • gallery.html: Image gallery for posts
  • slider-posts.html: Post slider component
  • trending-posts.html: Trending posts display

5. Utilities Directory

Miscellaneous utility components.

Files:

  • analytics.html: Analytics tracking integration
  • cover.html: Page cover or hero section
  • disqus-comments.html: Disqus comment system
  • divider.html: Decorative divider
  • page-loading.html: Page loading animation
  • pagination.html: Content pagination
  • social-share.html: Social media sharing buttons
  • video.html: Video embedding utility

Portfolio Loop Includes

Fullscreen Portfolio Loop

File Location

_includes/components/portfolio/loops/fullscreen-loop.html

Purpose

Generates a responsive, filterable grid layout for portfolio items with a fullscreen grid design.

Key Features

  • Dynamic portfolio item filtering
  • Responsive grid layout
  • Overlay effects
  • Thumbnail and title display

Liquid Logic Breakdown

{% comment %} Fullscreen Portfolio Loop {% endcomment %}

{% assign items = site.portfolio | where:"grouped_by","fullscreen_grid" %}

{% for post in items %}
  <div class="item grid-sizer col-md-6 col-lg-6 col-xl-4 col-xxl-3 
       {% for filter in post.filters %} {{filter}} {% endfor %}">
    <figure class="overlay overlay1 rounded">
      <a href="{{post.url}}">
        <img src="{{post.thumbnail}}" alt="{{post.title}}" />
      </a>
      <figcaption>
        <h5 class="from-top mb-0">{{post.title}}</h5>
      </figcaption>
    </figure>
  </div>
{% endfor %}

Configuration Options

  • grouped_by: Filter portfolio items by specific group
  • filters: Additional CSS classes for filtering
  • thumbnail: Portfolio item preview image
  • title: Portfolio item title

Usage Example

{% include components/portfolio/loops/fullscreen-loop.html %}

Component Loops Documentation

Portfolio Loops

1. Fullscreen Loop

_includes/components/portfolio/loops/fullscreen-loop.html

  • Purpose: Generates fullscreen grid portfolio layout
  • Key Features:
    • Responsive grid design
    • Filtering by grouped_by attribute
    • Overlay effects
  • Usage: 
    {% include components/portfolio/loops/fullscreen-loop.html %}

2. Grid Loop

_includes/components/portfolio/loops/grid-loop.html

  • Purpose: Creates flexible grid-based portfolio display
  • Configurable Parameters:
    • layout_class: Grid column configuration
    • is_boxed: Optional boxed layout
    • hide_content: Toggle content visibility
  • Usage: 
    {% include components/portfolio/loops/grid-loop.html 
   layout_class='col-md-6 col-lg-4' 
   is_boxed=true 
%}

3. Masonry Loop

_includes/components/portfolio/loops/masonry-loop.html

  • Purpose: Generates masonry-style portfolio layout
  • Key Features:
    • Responsive masonry grid
    • Dynamic item sizing
    • Flexible filtering

4. Mosaic Loop

_includes/components/portfolio/loops/mosaic-loop.html

  • Purpose: Creates mosaic-style portfolio display
  • Characteristics:
    • Irregular grid layout
    • Unique item positioning
    • Visual variety

5. Portfolio Loop

_includes/components/portfolio/loops/portfolio-loop.html

  • Purpose: Generic portfolio item rendering
  • Flexibility:
    • Multiple layout options
    • Customizable display settings

Posts Loops

1. Post Loop

_includes/posts/loops/post-loop.html

  • Purpose: Flexible blog post rendering
  • Configurable Parameters:
    • title_length: Truncate post titles
    • excerpt_length: Control excerpt display
    • layout_class: Grid column configuration
    • is_boxed: Optional boxed layout
    • is_grid: Toggle grid display
  • Features:
    • Category badges
    • Responsive design
    • Customizable text alignment
  • Usage: 
    {% include posts/loops/post-loop.html 
   title_length=50 
   excerpt_length=30 
   layout_class='col-md-6' 
%}

Additional Portfolio Components

_includes/components/portfolio/related-projects.html

  • Purpose: Display related portfolio projects in a carousel
  • Key Features:
    • Responsive carousel layout
    • Filtered by grouped_by attribute
    • Lightbox image preview
  • Configuration:
    • Owl Carousel with responsive breakpoints
    • Customizable margin and autoplay
  • Usage: 
    {% include components/portfolio/related-projects.html %}

Additional Posts Components

_includes/posts/carousel-layout.html

  • Purpose: Create image carousel for posts
  • Configurable Parameters:
    • images: Custom image array or page gallery
    • Supports individual image captions
  • Features:
    • Lightbox integration
    • Responsive image display
    • Optional image captions
  • Usage: 
    {% include posts/carousel-layout.html 
   images=page.gallery 
%}

_includes/posts/trending-posts.html

  • Purpose: Display trending blog posts
  • Key Features:
    • Carousel of top posts
    • Limit posts by trending flag
    • Category badges
    • Responsive layout
  • Configurable Parameters:
    • Custom title
    • Post limit (default: 6)
    • Responsive breakpoints
  • Usage: 
    {% include posts/trending-posts.html 
   trending_post_title='Latest Trends' 
%}

3. Author Information

_includes/posts/author.html

  • Purpose: Display author details for blog posts
  • Features:
    • Author name and bio
    • Profile image
    • Social media links
  • Usage: 
    {% include posts/author.html %}

_includes/posts/gallery-layout.html

  • Purpose: Create gallery display for post images
  • Features:
    • Multiple image display
    • Responsive grid layout
    • Lightbox integration
  • Usage: 
    {% include posts/gallery-layout.html %}

5. Slider Posts

_includes/posts/slider-posts.html

  • Purpose: Create post slider component
  • Features:
    • Dynamic post slider
    • Configurable slide settings
    • Responsive design
  • Usage: 
    {% include posts/slider-posts.html %}

Shop Components

_includes/components/shop/products-carousel.html

  • Purpose: Display recommended shop products in a carousel
  • Key Features:
    • Responsive product grid
    • Product hover effects
    • Sale and new item labels
    • Wishlist and cart quick actions
  • Configuration:
    • Limit products (default: 6)
    • Responsive breakpoints
    • Product rating display
  • Usage: 
    {% include components/shop/products-carousel.html %}

2. Products Slider

_includes/components/shop/products_slider.html

  • Purpose: Create a dynamic product slider
  • Features:
    • Horizontal product display
    • Customizable slide settings
    • Responsive design
  • Usage: 
    {% include components/shop/products_slider.html %}

3. Shop Items List

_includes/components/shop/shop-items-list.html

  • Purpose: Generate a list of shop items
  • Features:
    • Flexible item rendering
    • Filterable by categories
    • Customizable layout
  • Usage: 
    {% include components/shop/shop-items-list.html %}

Team Components

_includes/components/team/teams-carousel.html

  • Purpose: Display team members in a carousel
  • Key Features:
    • Two display modes: Blob and Box
    • Responsive team member grid
    • Social media integration
  • Configuration Options:
    • page.teams_carousel.type:
      • 'blob': Circular image style
      • 'box': Boxed layout
    • Configurable carousel settings
  • Usage: 
    {% comment %}In page front matter{% endcomment %}
teams_carousel:
  type: 'blob'  # or 'box'

2. Team Members

_includes/components/team/team-members.html

  • Purpose: Display individual team member details
  • Features:
    • Member profile information
    • Flexible layout options
  • Usage: 
    {% include components/team/team-members.html %}

Dynamic Filtering

{% assign filtered_items = site.portfolio 
   | where:"category","web-design" 
   | sort: "date" 
%}

Conditional Rendering

{% if items.size > 0 %}
  {% for item in items %}
    <!-- Render items -->
  {% endfor %}
{% else %}
  <p>No items found.</p>
{% endif %}

Conclusion

The _includes directory provides a flexible, modular approach to building your Jekyll theme. By understanding and leveraging these components, you can create a highly customizable and maintainable website.

Advanced Component Techniques

Dynamic Content Filtering

{% assign trending_posts = site.posts 
   | where: "trending", true 
   | sort: "date" 
   | limit: 6 
%}

Conditional Rendering

{% if trending_posts.size > 0 %}
  {% for post in trending_posts %}
    <!-- Render trending posts -->
  {% endfor %}
{% else %}
  <p>No trending posts available.</p>
{% endif %}

Component Best Practices

  1. Use semantic HTML
  2. Implement responsive design
  3. Optimize image loading
  4. Provide fallback content
  5. Ensure accessibility
  6. Minimize external dependencies

Performance Optimization

  • Lazy load images and carousels
  • Use efficient Liquid filtering
  • Minimize JavaScript overhead
  • Implement caching strategies

Accessibility Considerations

  • Add meaningful alt text
  • Use ARIA labels
  • Ensure keyboard navigability
  • Provide text alternatives for visual content

Future Enhancements

  • Add more flexible filtering options
  • Create more granular component templates
  • Improve responsive design
  • Enhance accessibility features

Shop and Team Component Best Practices