plugins blogging

Overview

The jekyll-archives plugin let’s you generate pages which list posts by their categories, tags or date. This site uses jekyll-archives to organise tutorials by their category.

Installation

  1. Create a Gemfile if you don’t already have one.
  2. Add jekyll-archives to the jekyll_plugins group in your Gemfile: 
    source 'https://rubygems.org'

gem 'jekyll', '3.3.1'

group :jekyll_plugins do
  gem 'jekyll-archives'
end
  3. Run bundle install

Configuration

All configuration is set in _config.yml under the archives key. The default configuration is set to this:

jekyll-archives:
  enabled: []
  layout: 'archive'
  permalinks:
    year: '/:year/'
    month: '/:year/:month/'
    day: '/:year/:month/:day/'
    tag: '/tag/:name/'
    category: '/category/:name/'

Enabled

Describes which archives types are enabled. The options are ‘all’ or an array of any combination of year, month, day, categories, tags.

enabled: all

enabled:
  - categories

enabled:
  - year
  - month
  - tags

Layout

The layout to use if no type specific layout is set.

layout: archive

Type specific layout

Layouts for specific types of archives.

layouts:
  year: year-archive
  month: month-archive
  day: day-archive
  tag: tag-archive-layout

Customise the permalink format of the archive pages.

permalinks:
  year: '/archives/year/:year/'
  month: '/archives/month/:year-:month/'
  tag: '/archives/tag/:name/`

Check out the configuration documentation for in-depth information.

Usage

Once the plugin is set up you can link to the permalink you’ve set up. On this site, there’s a category called jekyll-plugins so I can link to it like this:

<a href="/categories/jekyll-plugins/">Plugins</a>

You can output all the categories and links to their archive pages by looping of site.categories:

<ul>
{% for category in site.categories %}
  {% assign category_name = category[0] %}
  <li>
    <a href="/category/{{ category_name | slugify }}/">{{ category_name | replace: "-", " " }}</a>
  </li>
{% endfor %}

I always replace spaces with hyphens in my category names to avoid having %20 in the URLs making them a little nicer to read. If you do this you can just replace - with a space when you output the actual name like I have above.