Plugins Reference

This document describes all Jekyll plugins used by the site.

Plugin Configuration

Plugins are configured in two places:

_config.yml

plugins:
  - jekyll-paginate
  - jekyll-sitemap
  - jekyll-gist
  - jekyll-feed
  - jemoji
  - jekyll-include-cache
  - jekyll-redirect-from

Gemfile

group :jekyll_plugins do
  gem "jekyll-paginate"
  gem "jekyll-sitemap"
  gem "jekyll-gist"
  gem "jekyll-feed"
  gem "jemoji"
  gem "jekyll-include-cache"
  gem "jekyll-algolia"
  gem "jekyll-redirect-from"
  gem "kramdown"
  gem "liquid"
end

Active Plugins

jekyll-paginate

Purpose: Splits blog posts across multiple pages.

Configuration:

paginate: 7              # Posts per page
paginate_path: /page:num/  # URL pattern

Output:

• / - First page (posts 1-7)
• /page2/ - Second page (posts 8-14)
• etc.

Usage in Templates:

Paginator Object: | Property | Description | |———-|————-| | paginator.posts | Posts on current page | | paginator.page | Current page number | | paginator.total_pages | Total number of pages | | paginator.previous_page | Previous page number | | paginator.next_page | Next page number |

jekyll-sitemap

Purpose: Automatically generates sitemap.xml for search engines.

Configuration: No configuration needed.

Output: /sitemap.xml

Excluding Pages:

---
sitemap: false
---

jekyll-gist

Purpose: Embed GitHub Gists in content.

Usage:

<script src="https://gist.github.com/username/gist_id.js"> </script>
<script src="https://gist.github.com/username/gist_id.js?file=file.rb"> </script>

Example:

<script src="https://gist.github.com/hwschuur/abc123def456.js"> </script>

jekyll-feed

Purpose: Generates Atom feed for RSS readers.

Configuration:

atom_feed:
  hide: true    # Hide feed link in footer

Output: /feed.xml

Customization:

feed:
  path: atom.xml           # Custom path
  excerpt_only: true       # Only excerpts
  posts_limit: 20          # Limit posts

jemoji

Purpose: GitHub-style emoji support.

Usage:

This is great! :+1:
I love Jekyll :heart:

Common Emojis: | Code | Emoji | |——|——-| | :+1: | | | :heart: | | | :rocket: | | | :star: | | | :warning: | |

Full List: Emoji Cheat Sheet

jekyll-include-cache

Purpose: Caches include files for faster builds.

Usage:

    <div class="masthead">
      <div class="masthead__inner-wrap">
        <div class="masthead__menu">
          <nav id="site-nav" class="greedy-nav">
            <a class="site-title" href="/">
              Henk van der Schuur</a>
            <ul class="visible-links"><li class="masthead__menu-item">
                  <a href="/">Home</a>
                </li><li class="masthead__menu-item">
                  <a href="/work/">Work</a>
                </li><li class="masthead__menu-item">
                  <a href="/contact/">Contact</a>
                </li></ul>
            
            <button class="greedy-nav__toggle hidden" type="button">
              <span class="visually-hidden">Toggle menu</span>
              <div class="navicon"></div>
            </button>
            <ul class="hidden-links hidden"></ul>
          </nav>
        </div>
      </div>
    </div>

When to Use:

• Static includes that don’t change per page
• Performance-critical includes

When NOT to Use:

• Includes that use page-specific variables
• Dynamic content

jekyll-redirect-from

Purpose: Creates redirects from old URLs to new ones.

Redirect TO another page:

---
permalink: /old-url/
redirect_to: /new-url/
---

Redirect FROM old URLs:

---
permalink: /new-url/
title: "My Page"
redirect_from:
  - /old-url/
  - /another-old-url/
  - /legacy/path/
---

How it Works:

• Creates HTML files with meta refresh
• Works without server configuration

Available But Not Active

jekyll-algolia

Purpose: Algolia search integration.

Status: Listed in Gemfile but not configured.

To Enable:

1. Create Algolia account
2. Add to _config.yml:

   algolia:
     application_id: YOUR_APP_ID
     index_name: YOUR_INDEX_NAME
     search_only_api_key: YOUR_SEARCH_KEY
   

3. Run indexing:

   ALGOLIA_API_KEY=your_admin_key bundle exec jekyll algolia
   

GitHub Pages Compatibility

Only certain plugins work with GitHub Pages’ built-in build:

Supported Plugins

• jekyll-coffeescript
• jekyll-default-layout
• jekyll-feed
• jekyll-gist
• jekyll-github-metadata
• jekyll-include-cache
• jekyll-optional-front-matter
• jekyll-paginate
• jekyll-readme-index
• jekyll-redirect-from
• jekyll-relative-links
• jekyll-remote-theme
• jekyll-sass-converter
• jekyll-seo-tag
• jekyll-sitemap
• jekyll-titles-from-headings
• jemoji

Not Supported (Require Custom Build)

• jekyll-archives
• jekyll-paginate-v2
• jekyll-algolia (indexing)
• Custom plugins

Plugin Management

Installing New Plugins

1. Add to Gemfile:

   group :jekyll_plugins do
     gem "new-plugin-name"
   end
   

2. Add to _config.yml:

   plugins:
     - new-plugin-name
   

3. Run:

   bundle install
   

Updating Plugins

bundle update

Or update specific plugin:

bundle update jekyll-feed

Checking Plugin Versions

bundle list | grep jekyll

Troubleshooting

Plugin Not Loading

1. Verify it’s in both Gemfile and _config.yml
2. Run bundle install
3. Restart Jekyll server

Plugin Not Compatible

If a plugin doesn’t work with GitHub Pages:

• Use GitHub Actions for custom builds
• Or use alternative deployment (Netlify, Vercel)

Plugin Conflicts

Check for version conflicts:

bundle exec gem dependency jekyll-plugin-name