jekyll-archive

Jekyll plugin to create a set of archive pages.

Jekyll Archive Generator

Deprecation notice: There is now an official archive plugin, Jekyll Archives. To avoid confusion and duplication of effort, 0.4.0 is planned to be the final release of Jekyll Archive Generator and you should probably use Jekyll Archives instead.

This plugin creates a set of archive pages for a Jekyll website.

Oddly, Jekyll doesn't include a date-based archive for posts out of the box. For example, if you have a permalink structure like blog/2014/01/01/title, URL hacking won't work because going to blog/2014 will return 404 Page Not Found.

Jekyll Archive Generator fixes that by generating all the necessary archive pages for each part of your blog URL structure.

Installation

This plugin is provided as a gem:

gem install jekyll-itafroma-archive

Once the gem is installed, include it in your Jekyll site's configuration:

gems: ['jekyll/itafroma/archive']

Configuration

This plugin's configuration is contained within the archive key and supports multiple archives:

archive:
    - path: /blog/:year
      layout: archive_blog
      title: Blog archive — :year
      include:
        tags: ['PHP']
      exclude:
        categories: ['news']
        tags: ['drafts']
    - path: /blog/:year/:month
      layout: archive_blog
      title: Blog archive — :month :year
      include:
        tags: ['PHP']
      exclude:
        categories: ['news']
        tags: ['drafts']
    - path: /blog/:year/:month/:day
      layout: archive_blog
      title: Blog archive — :month :day, :year
      include:
        tags: ['PHP']
      exclude:
        categories: ['news']
        tags: ['drafts']

Directives

All directives are optional.

path

The tokenized path where the archive should be generated. For example, /blog/:year will generate a set of archive pages corresponding to post years: /blog/2010, /blog/2011, and so on. The following tokens are available:

year: four-digit year
short_year: two-digit year
month: month with leading zeros
i_month: month without leading zeros
short_month: three-letter, capitalized month name (e.g. "Jan")
long_month: full, capitalized month name (e.g. "January")
day: day with leading zeros
i_day: day without leading zeros
y_day: day of the year (e.g. 252)

Default value: /

layout

The name of the layout to use for the archive pages. An example layout named archive.html is included in this repository. See Usage below for more information.

Default value: archive

title

The tokenized title of the archive pages. This uses the same tokens available for the path directive above. For example, Blog archive — :year will generate archive page titles like Blog Archive — 2010, Blog Archive — 2011, and so on.

Default value: Blog archive

include

A mapping of front matter keys used to "whitelist" posts for the archive. Each key in the mapping is an array of strings for that specific key to include. This is conjunctive: if a post matches at least one condition, it will be included in the archive.

For example, categories: ['foo', 'bar'] will ensure that only posts in the foo or bar categories will be included in the archive.

If include is not present, all posts will be included in the archive.

Default value: empty (all posts will be included)

exclude

A mapping of front matter keys used to exclude posts from the archive. Each key in the sequence is an array of strings for that specific key to exclude.

For example, categories: ['foo', 'bar'] will exclude any post that has the foo or bar category.

Exclusion filters are run after inclusion criteria specified by the include directive.

Default value: empty (no posts will be excluded)

Usage

An example layout named archive.html is included in this repository. Two variables are exposed to the archive layout:

page.archive.posts

The collection of posts for the specific time period in the archive. For example, page.archive.posts will only contain posts from May 2014 in the May 2014 archive page.

page.archive.paginator

A paginator to navigate between archive pages at a specific date "resolution". For example, on the archive page for May 2014, the paginator will let you navigate between months. On the archive page for May 26, 2014, the paginator will let you navigate between days.

This paginator contains many of the same values found in Jekyll's native paginator (description of variables copied from that page):

page.archive.paginator.page: the current page number
page.archive.paginator.total_pages: the number of pagination pages
page.archive.paginator.previous_page: the page number of the previous pagination page, or nil if no previous page exists
page.archive.paginator.previous_page_path: the path of previous pagination page, or nil if no previous page exists
page.archive.paginator.next_page: the page number of the next pagination page, or nil if no subsequent page exists
page.archive.paginator.next_page_path: the path of next pagination page, or nil if no subsequent page exists

Acknowledgments

This plug is inspired by the work done by Nicholas Lindley:

And by Ilkka Laukkanen:

Copyright and license