jekyll-archives

To use jekyll-archives in your Jekyll project, you must add the gem to your Gemfile and register the plugin in your _config.yml file.

# Gemfile
gem 'jekyll-archives'

# _config.yml
plugins:
  - jekyll-archives

All configuration for the jekyll-archives plugin must be placed under the jekyll-archives key in your site's _config.yml file.

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

By default, tag and category archives are generated by slugifying their names. You can customize this behavior by setting the slug_mode key to any of the modes supported by the Jekyll slugify filter (e.g., latin).

slug_mode: latin

Use the enabled key to specify which archives should be generated. You can either set it to the string 'all' to enable every archive type, or provide an array containing a combination of year, month, day, categories, and tags.

enabled: all

# Or specify an array
enabled:
  - categories

enabled:
  - year
  - month
  - tags

The permalinks key allows you to define the URL structure for each archive type. The format follows standard Jekyll permalink syntax but uses specific variables:

• :year (for year archives)
• :year and :month (for month archives)
• :year, :month, and :day (for day archives)
• :name (for category and tag archives)

Note: You must include trailing slashes (e.g., '/path/') to ensure the archive is generated as an index.html file within a directory.

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

You can control which Jekyll layouts are used to render your archives using two different keys:

1. layout: Sets a global default layout for all archives. If a type-specific layout is not defined, the plugin falls back to this value.
2. layouts: A map that allows you to assign specific layouts to specific archive types (year, month, day, category, or tag).

# Set a global default
layout: archive

# Map specific types to specific layouts
layouts:
  year: year-archive
  month: month-archive
  day: day-archive
  category: category-archive
  tag: tag-archive

Archive generation behavior is controlled via the jekyll-archives key in your _config.yml file. This key allows you to define how archives are generated for different taxonomies (like dates, tags, or categories).

# _config.yml
jekyll-archives:
  # Configuration options go here

For month archives, use page.date to display the month and year. When processing the page.date object, ignore the day component.

<h1>Archive of posts from {{ page.date | date: "%B %Y" }}</h1>

<ul class="posts">
{% for post in page.posts %}
  <li>
    <span class="post-date">{{ post.date | date: "%b %-d, %Y" }}</span>
    <a class="post-link" href="{{ post.url | relative_url }}">{{ post.title }}</a>
  </li>
{% endfor %}
</ul>

For tag and category archives, use page.title to display the name of the tag/category and page.type to identify the archive type. Iterate over page.posts to list the posts.

<h1>Archive of posts with {{ page.type }} '{{ page.title }}'</h1>
<ul class="posts">
  {% for post in page.posts %}
    <li>
      <span class="post-date">{{ post.date | date: "%b %-d, %Y" }}</span>
      <a class="post-link" href="{{ post.url | relative_url }}">{{ post.title }}</a>
    </li>
  {% endfor %}
</ul>

For day archives, use page.date to display the full date (Month, Day, Year).

<h1>Archive of posts from {{ page.date | date: "%B %-d, %Y" }}</h1>

<ul class="posts">
{% for post in page.posts %}
  <li>
    <span class="post-date">{{ post.date | date: "%b %-d, %Y" }}</span>
    <a class="post-link" href="{{ post.url | relative_url }}">{{ post.title }}</a>
  </li>
{% endfor %}
</ul>

For year archives, use page.date to display the year. When processing the page.date object, ignore the month and day components.

<h1>Archive of posts from {{ page.date | date: "%Y" }}</h1>

<ul class="posts">
{% for post in page.posts %}
  <li>
    <span class="post-date">{{ post.date | date: "%b %-d, %Y" }}</span>
    <a class="post-link" href="{{ post.url | relative_url }}">{{ post.title }}</a>
  </li>
{% endfor %}
</ul>