Advanced Jekyll Plugins & Features Custom Post Types, Category Pages, Pagination, and More

Here at Divshot we're huge fans of Jekyll, the static CMS and blogging platform created by the folks at GitHub. We use Jekyll to power everything from our lander, blog, docs and upcoming support pages such as Q&A. It's a fantastic way to keep all of your content under version control and serve it up directly on Amazon S3. In this article I'm going to discuss some of the unique ways we've tweaked Jekyll to create an advanced blog with custom post types, post type pagination, post type filters and more. I'll introduce you to the plugins we use and share a few things I've written along the way.

Custom Post Types in Jekyll
Custom Post Type Category List Filter
Category Page Generator with Custom Post Types
Pagination with Category Pages and Custom Post Types
Post Excerpts
Instant Search
Sitemap Generator
Author Support with Rich Snippets
Asset Compilation
Jekyll on Amazon S3
Generator Sorting Utility
Styling Your Jekyll Blog Faster with Grunt
Wrapping Up

Custom Post Types in Jekyll

At its core, Jekyll is centered around pages and posts. Posts are blog entries that follow a permalink structure in your config file. You can organize your blog posts by category and date. In an effort to remain a simple blogging platform, going beyond Jekyll's default setup can be an interesting challenge compared to other alternatives such as WordPress. Let's say you want something like posts but you want to have different kinds of posts:

Blog Entries
Portfolio Items
Questions & Answers

There's several ways you could accomplish this task. If you wanted to store your custom posts in a different directory and have the ability to use filenames without dates, you could write your own generator. Going down this path isn't recommended. You'll have to extend and override Jekyll's internal classes to get your custom posts to behave exactly like posts. A much easier way is to use the post permalink and take advantage of categories to build separate directories for your post types. Here's my approach:

1) Edit _config.yml and change your permalink to permalink: /:categories/:title.

2) Create separate subdirectories inside your _posts/ directory to organize your post types, e.g. _posts/blog and _posts/questions.

3) Follow a similar file format for your custom posts. Use a date in the filename. Under categories for each post, specify a custom post type. Do this for every single post in the _posts/ directory based on the post type:

–––
layout: blog
title: Jake's Twitter Bootstrap Blog Post
categories:
– blog
– bootstrap
–––

–––
layout: question
title: What is Divshot?
categories:
– questions
– general
–––

My first category is always the custom post type and my second is the actual category for the post. When Jekyll compiles my site all of my blog posts will go under /blog and my questions will go under /questions. This approach covers the base functionality for custom post types. It's also easy to list all of the posts for a specific post type:

{% for post in site.categories['blog'] %}{% endfor %}

{% for post in site.categories['questions'] %} {% endfor %}

To list out categories for a specific post type we'll need to create a filter.

[top]

Custom Post Type Category List Filter

If we walk through each post via site.categories[post_type] to determine the categories we'll want to remove the post type categories such as blog and questions since they're not actually categories. Create a new Ruby file under _plugins/ and use the following filter:

module Jekyll module PostAndCategoryFilter RESTRICTED_CATEGORIES = ['blog', 'questions'] # Returns back all categories related to a primary category # e.g. "blog" or "questions" def filter_categories_by_primary_category(posts) filtered = [] for post in posts for post_category in post.categories filtered.push(post_category) unless RESTRICTED_CATEGORIES.include? post_category end end filtered.sort.uniq end end end Liquid::Template.register_filter(Jekyll::PostAndCategoryFilter)

After you added the filter file, go to the HTML file where you're listing out the categories. Add the following Liquid template tags to loop through the categories:

{% assign blog_categories = site.categories['blog'] | filter_categories_by_primary_category %}
{% for category in blog_categories %}{% endfor %}

We use the {% assign %} tag to create a variable with an array of categories we can print out. That's it! Next I'm going to show you a far more complicated feature that unfortunately doesn't come out of the box in Jekyll: Category pages.

[top]

Category Page Generator with Custom Post Types

Instead of writing my own generator from scratch, I used Dave Perrett's category page generator and tweaked the code to handle my own custom post types. I changed the write_category_index method under the Site class to only select posts with a specific category (my post types) and write the category views to different layout files based on the post type. I'll share an example and let you expand from there:

# If category is with questions... if self.categories[index.data['category']].select { |post| post.categories[0] == 'questions' }.length != 0 # Specify a unique folder for /categories based on post type. In this case, /questions/categories target_dir = '/' + GenerateCategories.category_dir(self.config['category_question_dir'], category) # Use a unique layout file for this post type. In this case, question_category_index.html index = CategoryIndex.new(self, self.source, target_dir, category, 'question_category_index.html') # Add category page to queue for export if index.render? self.pages << index end end

You'll notice I'm referencing a custom config value from my _config.yml file. I set up a category_dir as mentioned in the category page generator file and another config value for my questions category directory (category_question_dir). This should give you enough code to work out your own solution if you decide to add category pages to your site and want them for your custom post types. One last thing: Similar to how we filtered out our post type categories using RESTRICTED_CATEGORIES under our PostAndCategoryFilter, we'll also want to do the same thing in the category page generator:

def write_category_indexes if self.layouts.key? 'blog_category_index' self.categories.keys.each do |category| next if RESTRICTED_CATEGORIES.include? category self.write_category_index(category) end # Throw an exception if the layout couldn't be found. else throw "No 'category_index' layout found." end end

[top]

Pagination with Category Pages and Custom Post Types

Although basic blog pagination is built into Jekyll I wanted to write my own generator to handle category pages and custom post types. I attached the entire generator here in full. The paginate method takes a category and will paginate any list of posts. For category pages I wrote a custom paginate_categories method. To loop through these posts in your HTML file you'll want to use the following template tag instead of referencing site.categories[post_type]:

{% for post in paginator.posts %}{% endfor %}

As promised, here's my pagination generator:

module Jekyll class Page attr_accessor :dir end module Generators class Pagination < Generator # This generator is safe from arbitrary code execution. safe true # Generate paginated pages if necessary. # # site - The Site. # # Returns nothing. def generate(site) paginate(site, '/blog/index.html', 'blog') paginate_categories(site, '/blog/categories', 'blog_category_index.html', site.categories['blog']) paginate_categories(site, '/questions/categories', 'question_category_index.html', site.categories['questions']) end # Paginates the blog's posts. Renders the index.html file into paginated # directories, e.g.: page2/index.html, page3/index.html, etc and adds more # site-wide data. # # site - The Site. # page - The index.html Page that requires pagination. # # {"paginator" => { "page" => <Number>, # "per_page" => <Number>, # "posts" => [<Post>], # "total_posts" => <Number>, # "total_pages" => <Number>, # "previous_page" => <Number>, # "next_page" => <Number> }} def paginate(site, page_path, category) all_posts = site.site_payload['site']['categories'][category] page = site.pages.select do |page| path = page.dir + "/" + page.name path == page_path end.first pages = Pager.calculate_pages(all_posts, site.config['custom_paginate'].to_i) (1..pages).each do |num_page| pager = Pager.new(site, num_page, all_posts, pages, page) if num_page > 1 newpage = Page.new(site, site.source, page.dir, page.name) newpage.pager = pager newpage.dir = File.join(page.dir, "page#{num_page}") site.pages << newpage else page.pager = pager end end end def paginate_categories(site, category_path, category_layout, posts) categories = [] restricted_categories = ['blog', 'questions'] for post in posts for post_category in post.categories categories.push(post_category) unless restricted_categories.include? post_category end end categories.sort!.uniq! for category in categories all_posts = site.site_payload['site']['categories'][category] page = site.pages.select do |page| path = page.dir + "/" + page.name path == category_path + "/" + category + "/index.html" end.first pages = Pager.calculate_pages(all_posts, site.config['custom_paginate'].to_i) (1..pages).each do |num_page| pager = Pager.new(site, num_page, all_posts, pages, page) if num_page > 1 newpage = CategoryIndex.new(site, site.source, page.dir, category, category_layout) newpage.pager = pager newpage.dir = File.join(page.dir, "page#{num_page}") site.pages << newpage else page.pager = pager end end end end end end class Pager attr_reader :page, :per_page, :posts, :total_posts, :total_pages, :previous_page, :previous_page_path, :next_page, :next_page_path # Calculate the number of pages. # # all_posts - The Array of all Posts. # per_page - The Integer of entries per page. # # Returns the Integer number of pages. def self.calculate_pages(all_posts, per_page) (all_posts.size.to_f / per_page.to_i).ceil end # Determine if the subdirectories of the two paths are the same relative to source # # source - the site source # page_dir - the directory of the Jekyll::Page # paginate_path - the absolute paginate path (from root of FS) # # Returns whether the subdirectories are the same relative to source def self.in_hierarchy(source, page_dir, paginate_path) return false if paginate_path == File.dirname(paginate_path) return false if paginate_path == Pathname.new(source).parent page_dir == paginate_path || in_hierarchy(source, page_dir, File.dirname(paginate_path)) end # Static: Return the pagination path of the page # # site - the Jekyll::Site object # num_page - the pagination page number # target_page - the page where pagination is occurring # # Returns the pagination path as a string def self.paginate_path(site, num_page, target_page) return nil if num_page.nil? return target_page.url if num_page <= 1 format = site.config['paginate_path'] format = format.sub(':num', num_page.to_s) ensure_leading_slash(format) end # Static: Return a String version of the input which has a leading slash. # If the input already has a forward slash in position zero, it will be # returned unchanged. # # path - a String path # # Returns the path with a leading slash def self.ensure_leading_slash(path) path[0..0] == "/" ? path : "/#{path}" end # Static: Return a String version of the input without a leading slash. # # path - a String path # # Returns the input without the leading slash def self.remove_leading_slash(path) ensure_leading_slash(path)[1..-1] end # Initialize a new Pager. # # config - The Hash configuration of the site. # page - The Integer page number. # all_posts - The Array of all the site's Posts. # num_pages - The Integer number of pages or nil if you'd like the number # of pages calculated. def initialize(site, page, all_posts, num_pages = nil, target_page) @page = page @per_page = site.config['custom_paginate'].to_i @total_pages = num_pages || Pager.calculate_pages(all_posts, @per_page) if @page > @total_pages raise RuntimeError, "page number can't be greater than total pages: #{@page} > #{@total_pages}" end init = (@page - 1) * @per_page offset = (init + @per_page - 1) >= all_posts.size ? all_posts.size : (init + @per_page - 1) @total_posts = all_posts.size @posts = all_posts[init..offset] @previous_page = @page != 1 ? @page - 1 : nil @previous_page_path = Pager.paginate_path(site, @previous_page, target_page) @next_page = @page != @total_pages ? @page + 1 : nil @next_page_path = Pager.paginate_path(site, @next_page, target_page) end # Convert this Pager's data to a Hash suitable for use by Liquid. # # Returns the Hash representation of this Pager. def to_liquid { 'page' => page, 'per_page' => per_page, 'posts' => posts, 'total_posts' => total_posts, 'total_pages' => total_pages, 'previous_page' => previous_page, 'previous_page_path' => previous_page_path, 'next_page' => next_page, 'next_page_path' => next_page_path } end end end

[top]

Post Excerpts

Post excerpts allow you to provide a small preview of content before taking the user to the full post. Some plugins limit the excerpt to a certain amount of characters but I prefer specifying the excerpt cut-off with a  comment in my post files similar to WordPress. I use the following plugin found in a Gist after looking around:

module Jekyll class Post alias_method :original_to_liquid, :to_liquid def to_liquid original_to_liquid.deep_merge({ 'excerpt' => content.match('') ? content.split('').first : nil }) end end module Filters def mark_excerpt(content) content.gsub('', '<p><span id="more"></span></p>') end end end

[top]

Instant Search

Since your Jekyll website is completely static you'll either need to use a JavaScript-based search plugin or embed Google Web Search in your layout. I opted for the former and used an excellent search plugin powered by Lunr. When Jekyll compiles your site, a search.json file is generated with an index of all your posts for instant searching.

[top]

Sitemap Generator

To help Google spider all of our pages (including the category and pagination pages we're generating), I used another generator by Dave Perrett for sitemap generation. You can find all of his plugins available on GitHub.

The nice thing is that you can specify the changefreq and priority page variables directly in the _layouts/ template files without having to add them one-by-one to each custom post.

I tweaked the entry method to only provide a <lastmod> if a last-modified date is available for a specific page. For category and pagination files, the last-modified date is always the Jekyll compilation date since these files are created from scratch. In this case we won't add <lastmod to sitemap.xml.

def entry(path, date, attrs, site) # Remove the trailing slash from the baseurl if it is present, for consistency. baseurl = site.config['url'] baseurl = baseurl[0..-2] if baseurl=~/\/$/ entry = "\n\t<url>\n\t\t<loc>#{baseurl}#{path}</loc>\n" entry += "\t\t<lastmod>#{date.strftime("%Y-%m-%d")}</lastmod>\n" unless date.nil? entry += attrs.map { |k,v| "\t\t<#{k}>#{v}</#{k}>" }.join("\n") + "\n\t</url>\n" end

[top]

Author Support with Rich Snippets

Similar to using a JSON file for search, I'm also using a JSON file to store author metadata to display author info in our blog posts using a Jekyll tag plugin. At compilation time I parse the JSON file with Ruby and render the data in the post.html layout file.

Here's the author tag plugin:

module Jekyll class AuthorTag < Liquid::Tag def initialize(tag_name, attribute, tokens) super @attribute = attribute end def render(context) authors = JSON.parse(IO.read('authors.json'))['authors'] author_name = context.environments.first['page']['author'] selected_author = authors.select { |author| author['name'] == author_name } selected_author[0][@attribute.strip!] end end end Liquid::Template.register_tag('render_author', Jekyll::AuthorTag)

Here's how I add the author metadata to the layout file in a vCard:

<div class="byline author vcard"> <a class="photo" href="{% render_author url %}"> <img src="{% render_author avatar %}" alt="{{ page.author }}" title="{{ page.author }}"> </a> <h2>{{ page.author }}</h2> <div class="author-bio"> <p>{% render_author bio %}</p> </div> </div>

[top]

Asset Compilation

Whether it's Sprockets or another asset bundling manager like Grunt or Hem, we absolutely need a way to compile our assets on the fly. That's where Jekyll Assets comes in. All of our CoffeeScript, Sass, and vendor plugins used throughout our Jekyll instances use the jekyll-assets gem to compile everything into a central JavaScript and CSS file. After adding jekyll-assets to your Gemfile, edit your _config.yml like this:

assets:
  sources:
    – _assets/images
    – _assets/javascripts
    – _assets/stylesheets
    – _vendor/stylesheets
    – _vendor/javascripts

When you start your Jekyll server, the assets should be compiled immediately upon file save. If you're only editing a stylesheet, you may want to look into my research on Grunt integration below. It speeds things up dramatically.

[top]

Jekyll on Amazon S3

If you'd like to deploy your Jekyll website to Amazon S3, I recommend the s3_website plugin to get started. Check it out on GitHub.

[top]

Generator Sorting Utility

After creating so many generators of my own, one issue I ran into was specifying the order of generators called when compiling my Jekyll website. My sitemap generator would trigger before my category page generator, so the category pages wouldn't appear in the sitemap.

[top]

Styling Your Jekyll Blog Faster with Grunt

When using a Jekyll assets pipeline such as jekyll-asset or jekyll-asset-pipeline, saving CSS files and waiting for Jekyll to compile can quickly become frustrating when you're using something like LiveReload for live CSS editing.

Fortunately, Thanasis Polychronakis has written a useful Gruntfile for Jekyll and LiveReload to play nicely together. Check it out!

[top]

Wrapping Up

That covers most of the advanced plugins and features we use here at Divshot.

Once you spend some time learning how to create generators, filters, and tags, Jekyll becomes an extremely powerful tool for creating blogs and websites. It may not have the turnkey versatility of WordPress and its plugin ecosystem, but if you want a simple solution that outputs static HTML files then Jekyll is perfect for your needs.

Advanced Jekyll Plugins & Features - Custom Post Types, Category Pages, Pagination, and More

Custom Post Types in Jekyll

Custom Post Type Category List Filter

Category Page Generator with Custom Post Types

Pagination with Category Pages and Custom Post Types

Post Excerpts

Instant Search

Sitemap Generator

Author Support with Rich Snippets

Asset Compilation

Jekyll on Amazon S3

Generator Sorting Utility

Styling Your Jekyll Blog Faster with Grunt

Wrapping Up

Jake Johnson