jekyll-category-pages 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 729a4240777ec89a28d3fe0b835dd735e9c14352
+  data.tar.gz: 96bbf4220a73525d2433b9e5646450ad9fccec14
+SHA512:
+  metadata.gz: e6733ba05be842bf0ebfa01e54345eb12802e467d782e5597c7ee4ffb0a356dbf4b6a2452d78117c838472996e62227bde4e2ae82a3ec23ae5a1219b8e169421
+  data.tar.gz: 075ad1385dac2cfcca6f10852a6fa0795f2fc378d00b20753eef1e4ec5fa9223cfb50c2ee3501d68b482fe5b93417b81372feff071e054d4a3d1bc5629d529e7

data/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) since 2017 by Tamanguu GmbH & Co KG
+Written by Dr. Wolfram Schroers <Wolfram.Schroers -at- tamanguu.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,184 @@
+# jekyll-category-pages
+
+[![Gem Version](https://img.shields.io/gem/v/jekyll-category-pages.svg)](https://rubygems.org/gems/jekyll-category-pages)
+[![Build Status](https://travis-ci.org/field-theory/jekyll-category-pages.png?branch=master)](https://travis-ci.org/field-theory/jekyll-category-pages)
+
+This plugin adds category index pages with and without pagination.  
+Benefits are:
+* Easy to setup and use, fully compatible with the default [pagination
+    plugin](https://github.com/jekyll/jekyll-paginate) (also cf. the
+    [official documenation](https://jekyllrb.com/docs/pagination/)).
+* Supports category keys with spaces and other special characters.
+* Complete documentation and a usage example.
+* Test coverage of key features.
+* Category index pages are generated based on a customizable template.
+
+## Usage
+
+Assign one or more categories in the YAML front matter of each page:
+```yaml
+categories: [Category Pages Plugin, jekyll]
+```
+Generate the site and the category pages are generated:
+```
+_site/category/
+├── Category%20Pages%20Plugin/
+│   └── index.html
+├── %E5%A5%BD%E7%9A%84%E4%B8%BB%E6%84%8F/
+│   └── index.html
+└── jekyll/
+    ├── index.html
+    ├── page2.html
+    └── page3.html
+```
+In this example there are three paginated index pages for the `jekyll`
+category (apparently, there are many posts for this category), a
+single index page for the `好的主意` category and another single index
+page for the `Category Pages Plugin` category.
+
+Note that the YAML `categories` entry should always use brackets `[]`
+to make it explicit that it is an array!
+
+You can find this example in the `example` directory of the [git
+repository](https://github.com/field-theory/jekyll-category-pages).
+
+### The example project
+
+The `example` directory contains a basic example project that
+demonstrates the different use cases. In order to run Jekyll on these
+examples use:
+```shell
+bundle install
+bundle exec rake example
+```
+The result is put in `example/_site`.
+
+## Installation and setup
+
+Installation is straightforward (like other plugins):
+1. Add the plugin to the site's `Gemfile` and configuration file:
+    ```ruby
+    group :jekyll_plugins do
+      gem "jekyll-category-pages"
+    end
+    ```
+    and run `bundle install`. If you want to use pagination, also
+    install the `jekyll-paginate` gem:
+    ```ruby
+    group :jekyll_plugins do
+      gem "jekyll-paginate"
+      gem "jekyll-category-pages"
+    end
+    ```
+2. Add the plugin to your site's `_config.yml`:
+    ```ruby
+    plugins:
+      - jekyll-category-pages
+    ```
+3. Configure any other options you need (see below).
+4. Add template for category pages (see below).
+5. Set appropriate `categories` tags on each blog post YAML front
+   matter.
+
+### Configuration
+
+The following options can be set in the Jekyll configuration file
+`_config.yml`:
+* `category_path`: Root directory for category index pages. Defaults
+    to `category` if unset.  
+    In the example this places the index file for category `jekyll` at
+    `example/_site/category/jekyll/index.html`.
+* `category_layout`: Basic category index template. Defaults to
+    `category_index.html`. The layout **must** reside in the standard
+    `_layouts` directory.  
+    In the example the layout is in
+    `example/_layouts/category_index.html`.
+* `paginate`: (Maximum) number of posts on each category index
+    page. This is the same for the regular (front page) pagination. If
+    absent, pagination is turned off and only single index pages are
+    generated.  
+    In the example `paginate` is set to 2.
+
+### Template for category pages
+
+The template for a category index page must be placed in the site's
+`_layouts` directory. The attribute `category` indicates the current
+category for which the page is generated. The page title also defaults
+to the current category. The other attributes are similar to the
+default Jekyll pagination plugin.
+
+If no pagination is enabled the following attributes are available:
+
+| Attribute     | Description                               |
+| ------------- | ----------------------------------------- |
+| `category`    | Current page category                     |
+| `posts`       | List of posts in current category         |
+| `total_posts` | Total number of posts in current category |
+
+If pagination is enabled (i.e., if setting `site.paginate` globally in
+`_config.yml`) then a `paginator` attribute is available which returns
+an object with the following attributes:
+
+| Attribute            | Description                                                                      |
+| -------------------- | -------------------------------------------------------------------------------- |
+| `page`               | Current page number                                                              |
+| `per_page`           | Number of posts per page                                                         |
+| `posts`              | List of posts on the current page                                                |
+| `total_posts`        | Total number of posts in current category                                        |
+| `total_pages`        | Total number of pagination pages for the current category                        |
+| `previous_page`      | Page number of the previous pagination page, or `nil` if no previous page exists |
+| `previous_page_path` | Path of previous pagination page, or `''` if no previous page exists             |
+| `next_page`          | Page number of the next pagination page, or `nil` if no subsequent page exists   |
+| `next_page_path`     | Path of next pagination page, or `''` if no subsequent page exists               |
+
+An example can be found in `example/_layouts/category_index.html`
+which demonstrates the various attributes and their use.
+
+### Category listing
+
+A category overview with a full listing of all categories can be
+created as follows:
+```html
+<ul>
+{% for category in site.categories %}
+<li><a href="{{ site.url }}/category/{{ category | first | url_encode }}/index.html">{{ category | first }}</a></li>
+{% endfor %}
+</ul>
+```
+Note that the category page paths are URL-encoded when generated by
+this plugin. Thus, you have to use `url_encode` when linking to each
+category. This saves you from problems with spaces or other special
+characters in category names.
+
+An example listing can be found in `example/index.html` which
+shows a full listing of categories with corresponding links.
+
+## Development
+
+This project contains a `Rakefile` that supports the following
+tasks:
+* `build`: Runs all tests and builds the resulting gem file.
+* `test`: Run all tests.
+* `example`: Run Jekyll for the example project.
+* `clean`: Clean up all transient files.
+
+To run all test cases use:
+```shell
+bundle exec rake test
+```
+The tests run different Jekyll configurations and produce output files
+that can be read by Ruby. These are then evaluted and validated using
+[Ruby RSpec](http://rspec.info).
+
+To build the gem use:
+```shell
+bundle exec rake build
+```
+The result is put in the current directory after all tests have been
+run.
+
+## License
+
+The gem is available as open source under the terms of the [MIT
+License](https://github.com/field-theory/jekyll-category-pages/blob/master/LICENSE).
+

data/lib/jekyll-category-pages.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+# Copyright: Since 2017 Tamanguu GmbH & Co KG - MIT License
+# Encoding: utf-8
+
+#
+# category_pages
+# Add category index pages with and without pagination.
+#
+# (c) since 2017 by Tamanguu GmbH & Co KG
+# Written by Dr. Wolfram Schroers <Wolfram.Schroers -at- tamanguu.com>
+#
+# See the accompanying file LICENSE for licensing conditions.
+#
+
+require "jekyll/category_pages"

data/lib/jekyll-category-pages/version.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+# Copyright: Since 2017 Tamanguu GmbH & Co KG - MIT License
+# Encoding: utf-8
+
+#
+# jekyll-category-pages
+# Add category index pages with and without pagination.
+#
+# (c) since 2017 by Tamanguu GmbH & Co KG
+# Written by Dr. Wolfram Schroers <Wolfram.Schroers -at- tamanguu.com>
+#
+# See the accompanying file LICENSE for licensing conditions.
+#
+
+module Jekyll
+  module CategoryPages
+    VERSION = "1.0.0".freeze
+  end
+end

data/lib/jekyll/category_pages.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+# Encoding: utf-8
+
+#
+# category_pages
+# Add category index pages with and without pagination.
+#
+# (c) since 2017 by Tamanguu GmbH & Co KG
+# Written by Dr. Wolfram Schroers <Wolfram.Schroers -at- tamanguu.com>
+#
+# Copyright: Since 2017 Tamanguu GmbH & Co KG - MIT License
+# See the accompanying file LICENSE for licensing conditions.
+#
+
+require 'jekyll'
+
+module Jekyll
+  module CategoryPages
+    INDEXFILE = 'index.html'
+
+    # Custom generator for generating all index pages based on a supplied layout.
+    #
+    # Note that this generator uses a layout instead of a regular page template, since
+    # it will generate a set of new pages, not merely variations of a single page like
+    # the blog index Paginator does.
+    class Pagination < Generator
+      # This generator is safe from arbitrary code execution.
+      safe true
+      priority :lowest
+
+      # Generate paginated category pages if necessary.
+      #
+      # site - The Site object.
+      def generate(site)
+        category_base_path = site.config['category_path'] || 'category'
+        category_layout_path = File.join('_layouts/', site.config['category_layout'] || 'category_index.html')
+
+        if Paginate::Pager.pagination_enabled?(site)
+          # Generate paginated category pages
+          generate_paginated_categories(site, category_base_path, category_layout_path)
+        else
+          # Generate category pages without pagination
+          generate_categories(site, category_base_path, category_layout_path)
+        end
+      end
+
+      # Sort the list of categories and remove duplicates.
+      #
+      # site - The Site object.
+      #
+      # Returns an array of strings containing the site's categories.
+      def sorted_categories(site)
+        categories = []
+        site.categories.each_pair do |category, pages|
+          categories.push(category)
+        end
+        categories.sort!.uniq!
+        return categories
+      end
+
+      # Generate the paginated category pages.
+      #
+      # site               - The Site object.
+      # category_base_path - String with the base path to the category index pages.
+      # category_layout    - The name of the basic category layout page.
+      def generate_paginated_categories(site, category_base_path, category_layout)
+        categories = sorted_categories site
+
+        # Generate the pages
+        for category in categories
+          posts_in_category = site.categories[category]
+          category_path = File.join(category_base_path, CGI.escape(category))
+          per_page = site.config['paginate']
+
+          page_number = CategoryPager.calculate_pages(posts_in_category, per_page)
+          page_paths = []
+          category_pages = []
+          (1..page_number).each do |current_page|
+            # Collect all paths in the first pass and generate the basic page templates.
+            page_name = current_page == 1 ? INDEXFILE : "page#{current_page}.html"
+            page_paths.push page_name
+            new_page = CategoryIndexPage.new(site, category_path, page_name, category, category_layout, posts_in_category, true)
+            category_pages.push new_page
+          end
+
+          (1..page_number).each do |current_page|
+            # Generate the paginator content in the second pass.
+            previous_link = current_page == 1 ? nil : page_paths[current_page - 2]
+            next_link = current_page == page_number ? nil : page_paths[current_page]
+            previous_page = current_page == 1 ? nil : (current_page - 1)
+            next_page = current_page == page_number ? nil : (current_page + 1)
+            category_pages[current_page - 1].add_paginator_relations(current_page, per_page, page_number,
+                                                                     previous_link, next_link, previous_page, next_page)
+          end
+
+          for page in category_pages
+            # Finally, add the new pages to the site in the third pass.
+            site.pages << page
+          end
+        end
+
+        Jekyll.logger.debug("Paginated categories", "Processed " + categories.size.to_s + " paginated category index pages")
+      end
+
+      # Generate the non-paginated category pages.
+      #
+      # site               - The Site object.
+      # category_base_path - String with the base path to the category index pages.
+      # category_layout    - The name of the basic category layout page.
+      def generate_categories(site, category_base_path, category_layout)
+        categories = sorted_categories site
+
+        # Generate the pages
+        for category in categories
+          posts_in_category = site.categories[category]
+          category_path = File.join(category_base_path, CGI.escape(category))
+
+          site.pages << CategoryIndexPage.new(site, category_path, INDEXFILE, category, category_layout, posts_in_category, false)
+        end
+
+        Jekyll.logger.debug("Categories", "Processed " + categories.size.to_s + " category index pages")
+      end
+
+    end
+  end
+
+  # Auto-generated page for a category index.
+  #
+  # When pagination is enabled, contains a CategoryPager object as paginator. The posts in the
+  # category are always available as posts, the total number of those is always total_posts.
+  class CategoryIndexPage < Page
+    # Attributes for Liquid templates.
+    ATTRIBUTES_FOR_LIQUID = %w(
+      category
+      paginator
+      posts
+      total_posts
+      content
+      dir
+      name
+      path
+      url
+    )
+
+    # Initialize a new category index page.
+    #
+    # site              - The Site object.
+    # dir               - Base directory for all category pages.
+    # page_name         - Name of this category page (either 'index.html' or 'page#.html').
+    # category          - Current category as a String.
+    # category_layout   - Name of the category index page layout (must reside in the '_layouts' directory).
+    # posts_in_category - Array with full list of Posts in the current category.
+    # use_paginator     - Whether a CategoryPager object shall be instantiated as 'paginator'.
+    def initialize(site, dir, page_name, category, category_layout, posts_in_category, use_paginator)
+      @site = site
+      @base = site.source
+      super(@site, @base, '', category_layout)
+      @dir = dir
+      @name = page_name
+
+      self.process @name
+
+      @category = category
+      @posts_in_category = posts_in_category
+      @my_paginator = nil
+
+      self.read_yaml(@base, category_layout)
+      self.data.merge!('title' => category)
+      if use_paginator
+        @my_paginator = CategoryPager.new
+        self.data.merge!('paginator' => @my_paginator)
+      end
+    end
+
+    # Add relations of this page to other pages handled by a CategoryPager.
+    #
+    # Note that this method SHALL NOT be called if the category pages are instantiated without pagination.
+    # This method SHALL be called if the category pages are instantiated with pagination.
+    #
+    # page               - Current page number.
+    # per_page           - Posts per page.
+    # total_pages        - Total number of pages.
+    # previous_page      - Number of previous page or nil.
+    # next_page          - Number of next page or nil.
+    # previous_page_path - String with path to previous page or nil.
+    # next_page_path     - String with path to next page or nil.
+    def add_paginator_relations(page, per_page, total_pages, previous_page_path, next_page_path, previous_page, next_page)
+      if @my_paginator
+        @my_paginator.add_relations(page, per_page, total_pages,
+                                    previous_page, next_page, previous_page_path, next_page_path)
+        @my_paginator.add_posts(page, per_page, @posts_in_category)
+      else
+        Jekyll.logger.warn("Categories", "add_relations does nothing since the category page has been initialized without pagination")
+      end
+    end
+
+    # Get the category name this index page refers to
+    #
+    # Returns a string.
+    def category
+      @category
+    end
+
+    # Get the paginator object describing the current index page.
+    #
+    # Returns a CategoryPager object or nil.
+    def paginator
+      @my_paginator
+    end
+
+    # Get all Posts in this category.
+    #
+    # Returns an Array of Posts.
+    def posts
+      @posts_in_category
+    end
+
+    # Get the number of posts in this category.
+    #
+    # Returns an Integer number of posts.
+    def total_posts
+      @posts_in_category.size
+    end
+  end
+
+  # Handle pagination of category index pages.
+  class CategoryPager
+    attr_reader :page, :per_page, :posts, :total_posts, :total_pages,
+                :previous_page, :previous_page_path, :next_page, :next_page_path
+
+    # Static: Calculate the number of pages.
+    #
+    # all_posts - The Array of all Posts.
+    # per_page  - The Integer of entries per page.
+    #
+    # Returns the Integer number of pages.
+    def self.calculate_pages(all_posts, per_page)
+      (all_posts.size.to_f / per_page.to_i).ceil
+    end
+
+    # Add numeric relationships of this page to other pages.
+    #
+    # page               - Current page number.
+    # per_page           - Posts per page.
+    # total_pages        - Total number of pages.
+    # previous_page      - Number of previous page or nil.
+    # next_page          - Number of next page or nil.
+    # previous_page_path - String with path to previous page or nil.
+    # next_page_path     - String with path to next page or nil.
+    def add_relations(page, per_page, total_pages, previous_page, next_page, previous_page_path, next_page_path)
+      @page = page
+      @per_page = per_page
+      @total_pages = total_pages
+      @previous_page = previous_page
+      @next_page = next_page
+      @previous_page_path = previous_page_path
+      @next_page_path = next_page_path
+    end
+
+    # Add page-specific post data.
+    #
+    # page              - Current page number.
+    # per_page          - Posts per page.
+    # posts_in_category - Array with full list of Posts in the current category.
+    def add_posts(page, per_page, posts_in_category)
+      total_posts = posts_in_category.size
+      init = (page - 1) * per_page
+      offset = (init + per_page - 1) >= total_posts ? total_posts : (init + per_page - 1)
+
+      @total_posts = total_posts
+      @posts = posts_in_category[init..offset]
+    end
+
+    # Convert this CategoryPager's data to a Hash suitable for use by Liquid.
+    #
+    # Returns the Hash representation of this CategoryPager.
+    def to_liquid
+      {
+          'page' => page,
+          'per_page' => per_page,
+          'posts' => posts,
+          'total_posts' => total_posts,
+          'total_pages' => total_pages,
+          'previous_page' => previous_page,
+          'previous_page_path' => previous_page_path,
+          'next_page' => next_page,
+          'next_page_path' => next_page_path
+      }
+    end
+  end
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-category-pages
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Dr. Wolfram Schroers
+- Tamanguu GmbH & Co KG
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-12-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+- !ruby/object:Gem::Dependency
+  name: jekyll-paginate
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: |
+  This plugin is for all authors that tag their pages using categories. It generates
+  category overview pages with a custom layout. Optionally, it also adds proper
+  pagination for these pages.
+
+  Please refer to the README.md file on the project homepage at
+  https://github.com/field-theory/jekyll-category-pages
+email: Wolfram.Schroers@tamanguu.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/jekyll-category-pages.rb
+- lib/jekyll-category-pages/version.rb
+- lib/jekyll/category_pages.rb
+homepage: https://github.com/field-theory/jekyll-category-pages
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.10
+signing_key: 
+specification_version: 4
+summary: Add category index pages with and without pagination.
+test_files: []