Published 2020-10-03. Last modified 2023-05-22.
Time to read: 3 minutes.

This page is part of the jekyll_plugins collection.

jekyll_all_collections

Jekyll_all_collections is a Jekyll plugin that adds a new property called all_collections to the Jekyll site variable. It also provides a new Jekyll tag called all_collections, which creates a formatted listing of all posts and documents from all collections, sorted by age, newest to oldest.

The collection consists of an array of objects with the following properties:

• content (HTML or Markdown)
• data (array)
• date (Ruby Date)
• description
• destination
• draft (Boolean)
• excerpt (HTML or Markdown)
• ext
• label
• last_modified or last_modified_at (Ruby Date)
• layout
• path
• relative_path
• tags
• title
• type
• url

Pages that are not in any collection are not included.

Installation

Add this line to your application's Gemfile:

Gemfile

group :jekyll_plugins do 
  gem 'jekyll_all_collections'
end 

And then execute:

Shell

$ bundle

Requirements

All the pages in the Jekyll website must have an implicit date (for example, all posts are automatically assigned this property by Jekyll), or an explicit date set in front matter, like this:

Front matter

---
date: 2022-01-01
---

If a front matter variable called last_modified or last_modified_at exists, its value will be converted to a Ruby Date:

HTML or markdown

---
last_modified: 2023-01-01
---

Or:

HTML or markdown

---
last_modified_at: 2023-01-01
---

Otherwise, if last_modified or last_modified_at is not present in the front matter for a page, the date value will be used last modified date value.

Usage

Site.all_collections

No explicit initialization or setup is required. Jekyll plugins can access the value of site.all_collections, however Liquid code in Jekyll pages and documents cannot.

CSS For the All_collections Tag

Add the following CSS to your stylesheet:

CSS

.posts {
  display: flex;
  flex-wrap: wrap;
  justify-content: space-between;
  line-height: 170%;
}

.posts > *:nth-child(odd) {
  width: 120px;
  font-family: Monaco,"Bitstream Vera Sans Mono", "Lucida Console", Terminal, monospace;
  font-stretch: semi-condensed;
  font-size: 10pt;
}

.posts > *:nth-child(even) {
  width: calc(100% - 120px);
}

Excluding Pages

Adding the following entry to a page's front matter causes that page to be excluded from the collection created by this plugin:

Front matter in HTML or markdown page

---
exclude_from_all: true
---

General Form

The general form of the Jekyll tag is:

Format in HTML or markdown

{% all_collections
  date_column='date|last_modified'
  heading='All Posts'
  id='asdf'
  sort_by='SORT_KEYS'
%}

Each of these attributes are explained below.

Date_column Attribute

One of two date columns can be displayed in the generated HTML: either date (when the article was originally written), or last_modified. The default value for the date_column attribute is date.

Heading Attribute

If no heading attribute is specified, a heading will automatically be generated, which contains the sort_by values, for example:

HTML or markdown

{% all_collections id='abcdef' sort_by="last_modified" %}

Generates a heading like:

HTML or markdown

<h2 id="abcdef">All Posts Sorted By last_modified</h2>

To suppress both a h2 heading (and the enclosed id) from being generated, specify an empty string for the value of heading:

HTML or markdown

{% all_collections heading='' %}

Id Attribute

If your Jekyll layout employs jekyll-toc, then id attributes are important. The jekyll-toc include checks for id attributes in h2 ... h6 HTML tags, and if found, and if the attribute value is enclosed in double quotes (id="my_id", not id='my_id'), then the heading is included in the table of contents.

To suppress an id from being generated, and thereby preventing the heading from appearing in the automatically generated table of contents from jekyll-toc, specify an empty string for the value of id, like this:

HTML or markdown

{% all_collections id='' %}

SORT_KEYS Values

SORT_KEYS specifies how to sort the collection. Values can include one or more of the following attributes: date, destination, draft, label, last_modified, last_modified_at, path, relative_path, title, type, and url. Ascending sorts are the default, however a descending sort can be achieved by prepending - before an attribute.

To specify more than one sort key, provide a comma-delimited string of values. Included spaces are ignored. For example, specify the primary sort key as draft, the secondary sort key as last_modified, and the tertiary key as label:

HTML or markdown

{% all_collections
  date_column='last_modified'
  heading='All Posts'
  id='asdf'
  sort_by='draft, last_modified, label'
%}

Usage Examples

Here is a short Jekyll page, including front matter, demonstrating this plugin being invoked with all default attribute values:

Sample HTML page

---
description: "
  Dump of all collections, sorted by date originally written, newest to oldest.
  The heading text will be <code>All Posts Sorted By -date</code>
"
layout: default
title: Testing, 1, 2, 3
---
{% all_collections %}

Following are examples of how to specify the sort parameters.

Explicitly express the default sort
(sort by the date originally written, newest to oldest):

HTML or markdown

{% all_collections sort_by="-date" %}

Sort by date, from oldest to newest:

HTML or markdown

{% all_collections sort_by="date" %}

Sort by the date last modified, oldest to newest:

HTML or markdown

{% all_collections sort_by="last_modified" %}

Sort by the date last modified, newest to oldest:

HTML or markdown

{% all_collections sort_by="-last_modified" %}

Several attributes can be specified as sort criteria
by passing them as a comma-delimited string. Included spaces are ignored:

HTML or markdown

{% all_collections sort_by="-last_modified, -date" %}
{% all_collections sort_by="-last_modified, title" %}
{% all_collections sort_by="-last_modified, -date, title" %}

The following two examples produce the same output:

HTML or markdown

{% all_collections sort_by="-last_modified,-date" %}
{% all_collections sort_by="-last_modified, -date" %}

Demo

The demo directory contains a demonstration website, which uses the plugin. To run, type:

Shell

$ demo/_bin/debug -r

Now point your web browser to localhost:4444.

Share to Twitter, Hacker News, LinkedIn.