Published 2020-10-03. Last modified 2025-01-08.
Time to read: 4 minutes.

This page is part of the jekyll_plugins collection.

The version described in this article has not been released yet. Performance is not where I want it to be yet. You can build it as documented, or wait a week or two, and it will probably become available.

jekyll_all_collections

Jekyll_all_collections is a Jekyll plugin that includes a generator triggered by a high-priority hook and a block tag called all_collections. Taken together, the three new attributes of the Jekyll site variable reference all the files that are likely to be processed in a Jekyll website.

These three attributes can be referenced as site.everything, site.all_collections and site.all_documents.

Why Do This?

Jekyll provides inconsistent attributes for site.pages, site.posts and site.static_files.

• While the url attribute of items in site.posts and site.pages start with a slash (/), site.static_files items do not have a url attribute.
• Static files have a relative_path attribute, which starts with a slash (/), but although that attribute is also provided in site.posts and site.pages, those values do not start with a slash.
• Paths ending with a slash (/) imply that a file called index.html should be fetched.
• HTML redirect files created by the jekyll-redirect-from Jekyll plugin, which are included in site.static_files, should be ignored.

These inconsistencies mean that combining the standard three collections of files provided as site attributes will create a new collection that is difficult to process consistently:

Ruby code in a plugin

# This pseudocode creates `oops`, which is problematic to process consistently
oops = site.all_collections + site.pages + site.static_files

Oops, above, is difficult to process because of inconsistencies in the provided attributes and how the attributes are constructed.

Solving The Problem

The generator normalizes these inconsistencies by utilizing the AllCollectionsHooks::APage class and filtering out HTML redirect files.

AllCollectionsHooks::APage is used by other plugins based on jekyll_plugin_support, in particular jekyll_href.

The all_collections collection contains APage representations of site.collections.

The all_documents collection contains APage representations of site.pages.

The everything collection contains APage representations of:

Pseudocode

site.collections + site.pages + site.static_files - HTML_redirect_files

The APage Class

The site.all_collections, site.all_documents and site.everything attributes consist of arrays of APage instances.

The APage class has the following attributes:

• content (HTML or Markdown)
• data (array)
• date (Ruby Date)
• description
• destination
• draft (Boolean)
• ext
• href always starts with a slash. This value is consistent with a href values in website HTML. Paths ending with a slash (/) have index.html appended so the path specifies an actual file.
• label
• last_modified or last_modified_at (Ruby Date)
• layout
• origin indicates the original source of the item. Possible values are collection, individual_page and static_file. Knowing the origin of each item allows code to process each type of item appropriately.
• path
• relative_path
• tags
• title
• type
• url

All_collections Block Tag

The all_collections block tag creates a formatted listing of Jekyll files. The ordering is configurable; by default, the listing is sorted by date, newest to oldest. The all_collections tag has a data_source parameter that specifies which new property to report on (all_collections, all_documents, or everything).

Installation

Installing In A Jekyll Website

1. Add the CSS found in demo/assets/css/jekyll_all_collections.css to your Jekyll layout(s).
2. Add the following to your Jekyll website's Gemfile, within the jekyll_plugins group:
   Gemfile

   group :jekyll_plugins do
     gem 'jekyll_all_collections', '>= 0.3.8'
     gem 'jekyll_draft', '>=2.1.0'
   end

3. Type:
   Shell

   $ bundle

Installing As a Gem Dependency

Add the following to your gem’s .gemspec:

Gemfile

group :jekyll_plugins do 
  spec.add_dependency 'jekyll_all_collections', '>= 0.3.8'
  spec.add_dependency 'jekyll_draft', '>=2.1.0'
end 

And then execute:

Shell

$ bundle

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.

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.

Excluding Pages

There are two ways to exclude files from the new site attributes

1. The exclude entry in _config.yml can be used as it normally would.
2. 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
   ---

Plugin Usage

Jekyll generators and tags receive an enhanced version of the Jekyll site variable.

From a Custom Plugin

In the following example of how to use the all_collections plugin in a custom plugin, the do_something_with function processes all Jekyll::Pages, Jekyll:Documents, and static files.

Ruby code

@site.everything.each do |apage|
  do_something_with apage
end

Using the Block Tag

The general form of the Jekyll tag, including all options, 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'
%}

Liquid 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" %}

Share to Twitter, Hacker News, LinkedIn.