Home

Awesome

jekyll_all_collections Gem Version

Jekyll_all_collections is a Jekyll plugin that adds a new property called all_collections to site. 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, and url.

Pages that are not in any collection are not included.

Installation

Add this line to your application's Gemfile:

group :jekyll_plugins do
  gem 'jekyll_all_collections'
end

And then execute:

$ bundle

Requirements

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

---
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:

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

Or:

---
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.

Plugin Usage

Jekyll generators and tags receive an enhanced version of the site Jekyll variable. A new array of APage instance called all_collections is added, one for each Jekyll document and page. Examine APage.rb to see the available properties. One particularly useful property is url, which is difficult to obtain from Jekyll.

All Jekyll::Pages and Jekyll:Documents can be processed with the following sample code:

(@site.all_collections + @site.pages).each do |page_or_apage|
  do_something_with page_or_apage
end

All_collections Tag

Add the following CSS to your stylesheet:

.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:

---
exclude_from_all: true
---

General Form

The general form of the Jekyll tag is:

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

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:

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

Generates a heading like:

<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:

{% 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 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:

{% 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:

{% 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:

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

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

{% all_collections sort_by="-date" %}

Sort by date, from oldest to newest:

{% all_collections sort_by="date" %}

Sort by the date last modified, oldest to newest:

{% all_collections sort_by="last_modified" %}

Sort by the date last modified, newest to oldest:

{% 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:

{% 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:

{% 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:

$ demo/_bin/debug -r

Now point your web browser to http://localhost:4444

Debugging

You can control the verbosity of log output by adding the following to _config.yml in your Jekyll project:

plugin_loggers:
  AllCollectionsTag::AllCollectionsTag: warn

  1. You have two options for initiating a debug session:

    1. Run demo/_bin/debug, without the -r options shown above.

      ... lots of output as bundle update runs...
Bundle updated!

INFO PluginMetaLogger: Loaded AllCollectionsHooks v0.2.0 :site, :pre_render, :normal hook plugin.
INFO PluginMetaLogger: Loaded DraftFilter plugin.
INFO PluginMetaLogger: Loaded all_collections v0.2.0 tag plugin.
Configuration file: /mnt/_/work/jekyll/my_plugins/jekyll_all_collections/demo/_config.yml
          Cleaner: Removing /mnt/_/work/jekyll/my_plugins/jekyll_all_collections/demo/_site...
          Cleaner: Removing /mnt/_/work/jekyll/my_plugins/jekyll_all_collections/demo/.jekyll-metadata...
          Cleaner: Removing /mnt/_/work/jekyll/my_plugins/jekyll_all_collections/demo/.jekyll-cache...
          Cleaner: Nothing to do for .sass-cache.
Fast Debugger (ruby-debug-ide 0.7.3, debase 0.2.5.beta2, file filtering is supported) listens on 0.0.0.0:1234

    2. Run bin/attach and pass the directory name of a Jekyll website that has a suitable script called _bin/debug. The demo subdirectory fits this description.

      $ bin/attach demo
Successfully uninstalled jekyll_all_collections-0.1.2
jekyll_all_collections 0.1.2 built to pkg/jekyll_all_collections-0.1.2.gem.
jekyll_all_collections (0.1.2) installed.
Fast Debugger (ruby-debug-ide 0.7.3, debase 0.2.4.1, file filtering is supported) listens on 0.0.0.0:1234

  2. Set breakpoints in Ruby code.

  3. Attach to the debugger process. This git repo includes a Visual Studio Code launcher for this purpose labeled Listen for rdebug-ide.

  4. Point your web browser to http://localhost:4444

Additional Information

More information is available on Mike Slinn's website about Jekyll plugins.

Development

After checking out the repo, run bin/setup to install dependencies.

You can also run bin/console for an interactive prompt that will allow you to experiment.

Build and Install Locally

To build and install this gem onto your local machine, run:

$ bundle exec rake install
jekyll_all_collections 0.1.0 built to pkg/jekyll_all_collections-0.1.0.gem.
jekyll_all_collections (0.1.0) installed.

Examine the newly built gem:

$ gem info jekyll_all_collections

*** LOCAL GEMS ***

jekyll_all_collections (0.1.0)
    Author: Mike Slinn
    Homepage: https://www.mslinn.com/blog/2020/12/30/jekyll-plugin-template-collection.html
    License: MIT
    Installed at: /home/mslinn/.rbenv/versions/3.1.0/lib/ruby/gems/3.1.0

    Provides a collection of all collections in site.all_collections.

Build and Push to RubyGems

To release a new version,

  1. Update the version number in version.rb.

  2. Commit all changes to git; if you don't the next step might fail with an unexplainable error message.

  3. Run the following:

    $ bundle exec rake release

    The above creates a git tag for the version, commits the created tag, and pushes the new .gem file to RubyGems.org.

Contributing

  1. Fork the project
  2. Create a descriptively named feature branch
  3. Add your feature
  4. Submit a pull request

License

The gem is available as open source under the terms of the MIT License.