jekyll 3.9.3 → 4.4.1

data/README.markdown

@@ -1,19 +1,12 @@
 # [Jekyll](https://jekyllrb.com/)
 
 [![Gem Version](https://img.shields.io/gem/v/jekyll.svg)][ruby-gems]
-[![Linux Build Status](https://img.shields.io/travis/jekyll/jekyll/master.svg?label=Linux%20build)][travis]
-[![Windows Build status](https://img.shields.io/appveyor/ci/jekyll/jekyll/master.svg?label=Windows%20build)][appveyor]
-[![Maintainability](https://api.codeclimate.com/v1/badges/8ba0cb5b17bb9848e128/maintainability)](codeclimate)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/8ba0cb5b17bb9848e128/test_coverage)](coverage)
-[![Dependency Status](https://img.shields.io/gemnasium/jekyll/jekyll.svg)][gemnasium]
-[![Security](https://hakiri.io/github/jekyll/jekyll/master.svg)][hakiri]
+[![Build Status](https://github.com/jekyll/jekyll/workflows/Continuous%20Integration/badge.svg)][ci-workflow]
+[![Backers on Open Collective](https://opencollective.com/jekyll/backers/badge.svg)](#backers)
+[![Sponsors on Open Collective](https://opencollective.com/jekyll/sponsors/badge.svg)](#sponsors)
 
 [ruby-gems]: https://rubygems.org/gems/jekyll
-[gemnasium]: https://gemnasium.com/jekyll/jekyll
-[codeclimate]: https://codeclimate.com/github/jekyll/jekyll
-[coverage]: https://codeclimate.com/github/jekyll/jekyll/coverage
-[hakiri]: https://hakiri.io/github/jekyll/jekyll/master
-[travis]: https://travis-ci.org/jekyll/jekyll
+[ci-workflow]: https://github.com/jekyll/jekyll/actions?query=workflow%3A%22Continuous+Integration%22+branch%3Amaster
 [appveyor]: https://ci.appveyor.com/project/jekyll/jekyll/branch/master
 
 Jekyll is a simple, blog-aware, static site generator perfect for personal, project, or organization sites. Think of it like a file-based CMS, without all the complexity. Jekyll takes your content, renders Markdown and Liquid templates, and spits out a complete, static website ready to be served by Apache, Nginx or another web server. Jekyll is the engine behind [GitHub Pages](https://pages.github.com), which you can use to host sites right from your GitHub repositories.
@@ -22,39 +15,67 @@ Jekyll is a simple, blog-aware, static site generator perfect for personal, proj
 
 Jekyll does what you tell it to do — no more, no less. It doesn't try to outsmart users by making bold assumptions, nor does it burden them with needless complexity and configuration. Put simply, Jekyll gets out of your way and allows you to concentrate on what truly matters: your content.
 
-See: https://jekyllrb.com/philosophy
-
-## Having trouble?
-
-See: https://jekyllrb.com/docs/troubleshooting/
+See: [https://jekyllrb.com/philosophy](https://jekyllrb.com/philosophy)
 
 ## Getting Started
 
 * [Install](https://jekyllrb.com/docs/installation/) the gem
 * Read up about its [Usage](https://jekyllrb.com/docs/usage/) and [Configuration](https://jekyllrb.com/docs/configuration/)
-* Take a gander at some existing [Sites](https://wiki.github.com/jekyll/jekyll/sites)
+* Take a gander at some existing [Sites](https://github.com/jekyll/jekyll/wiki/sites)
 * [Fork](https://github.com/jekyll/jekyll/fork) and [Contribute](https://jekyllrb.com/docs/contributing/) your own modifications
-* Have questions? Check out our official forum community [Jekyll Talk](https://talk.jekyllrb.com/) or [`#jekyll` on irc.freenode.net](https://botbot.me/freenode/jekyll/)
+* Have questions? Check out our official forum community [Jekyll Talk](https://talk.jekyllrb.com/) and [`#jekyll` Channel on Libera IRC](https://libera.chat)
+
+## Diving In
+
+* [Migrate](https://import.jekyllrb.com/docs/home/) from your previous system
+* Learn how [Front Matter](https://jekyllrb.com/docs/front-matter/) works
+* Put information on your site with [Variables](https://jekyllrb.com/docs/variables/)
+* Customize the [Permalinks](https://jekyllrb.com/docs/permalinks/) your posts are generated with
+* Use the built-in [Liquid Extensions](https://jekyllrb.com/docs/templates/) to make your life easier
+* Use custom [Plugins](https://jekyllrb.com/docs/plugins/) to generate content specific to your site
+* Watch [video tutorials from Giraffe Academy](https://jekyllrb.com/tutorials/video-walkthroughs/)
+
+## Need help?
+
+If you don't find the answer to your problem in our [docs](https://jekyllrb.com/docs/), or in the [troubleshooting section](https://jekyllrb.com/docs/troubleshooting/), ask the [community](https://jekyllrb.com/docs/community/) for help.
 
 ## Code of Conduct
 
 In order to have a more open and welcoming community, Jekyll adheres to a
-[code of conduct](CODE_OF_CONDUCT.markdown) adapted from the Ruby on Rails code of
+[code of conduct](https://jekyllrb.com/docs/conduct/) adapted from the Ruby on Rails code of
 conduct.
 
 Please adhere to this code of conduct in any interactions you have in the
 Jekyll community. It is strictly enforced on all official Jekyll
 repositories, websites, and resources. If you encounter someone violating
-these terms, please let one of our core team members [Olivia](mailto:olivia@jekyllrb.com?subject=Jekyll%20CoC%20Violation), [Pat](mailto:pat@jekyllrb.com?subject=Jekyll%20CoC%20Violation), [Matt](mailto:matt@jekyllrb.com?subject=Jekyll%20CoC%20Violation) or [Parker](mailto:parker@jekyllrb.com?subject=Jekyll%20CoC%20Violation) know and we will address it as soon as possible.
+these terms, please let one of our [core team members](https://jekyllrb.com/team/#core-team) know and we will address it as soon as possible.
 
-## Diving In
+## Credits
 
-* [Migrate](http://import.jekyllrb.com/docs/home/) from your previous system
-* Learn how the [YAML Front Matter](https://jekyllrb.com/docs/frontmatter/) works
-* Put information on your site with [Variables](https://jekyllrb.com/docs/variables/)
-* Customize the [Permalinks](https://jekyllrb.com/docs/permalinks/) your posts are generated with
-* Use the built-in [Liquid Extensions](https://jekyllrb.com/docs/templates/) to make your life easier
-* Use custom [Plugins](https://jekyllrb.com/docs/plugins/) to generate content specific to your site
+### Sponsors
+
+Support this project by becoming a sponsor. Your logo will show up in this README with a link to your website. [Become a sponsor!](https://opencollective.com/jekyll#sponsor)
+[![Jekyll Sponsor 0](https://opencollective.com/jekyll/sponsor/0/avatar.svg)](https://opencollective.com/jekyll/sponsor/0/website)
+[![Jekyll Sponsor 1](https://opencollective.com/jekyll/sponsor/1/avatar.svg)](https://opencollective.com/jekyll/sponsor/1/website)
+[![Jekyll Sponsor 2](https://opencollective.com/jekyll/sponsor/2/avatar.svg)](https://opencollective.com/jekyll/sponsor/2/website)
+[![Jekyll Sponsor 3](https://opencollective.com/jekyll/sponsor/3/avatar.svg)](https://opencollective.com/jekyll/sponsor/3/website)
+[![Jekyll Sponsor 4](https://opencollective.com/jekyll/sponsor/4/avatar.svg)](https://opencollective.com/jekyll/sponsor/4/website)
+[![Jekyll Sponsor 5](https://opencollective.com/jekyll/sponsor/5/avatar.svg)](https://opencollective.com/jekyll/sponsor/5/website)
+[![Jekyll Sponsor 6](https://opencollective.com/jekyll/sponsor/6/avatar.svg)](https://opencollective.com/jekyll/sponsor/6/website)
+[![Jekyll Sponsor 7](https://opencollective.com/jekyll/sponsor/7/avatar.svg)](https://opencollective.com/jekyll/sponsor/7/website)
+[![Jekyll Sponsor 8](https://opencollective.com/jekyll/sponsor/8/avatar.svg)](https://opencollective.com/jekyll/sponsor/8/website)
+[![Jekyll Sponsor 9](https://opencollective.com/jekyll/sponsor/9/avatar.svg)](https://opencollective.com/jekyll/sponsor/9/website)
+
+### Contributors
+
+This project exists thanks to all the people who contribute.
+[![Jekyll Contributors](https://opencollective.com/jekyll/contributors.svg?width=890&button=false)](../../graphs/contributors)
+
+### Backers
+
+Thank you to all our backers! 🙏 [Become a backer](https://opencollective.com/jekyll#backer)
+
+[![Jekyll Backers](https://opencollective.com/jekyll/backers.svg?width=890)](https://opencollective.com/jekyll#backers)
 
 ## License
 

data/lib/blank_template/_config.yml

@@ -0,0 +1,3 @@
+url: "" # the base hostname & protocol for your site, e.g. http://example.com
+baseurl: "" # the subpath of your site, e.g. /blog
+title: "" # the name of your site, e.g. ACME Corp.

data/lib/blank_template/_layouts/default.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="{{ site.lang | default: "en-US" }}">
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta charset="utf-8">
+    <title>{{ page.title }} - {{ site.title }}</title>
+    <link rel="stylesheet" href="{{ "/assets/css/main.css" | relative_url }}">
+  </head>
+  <body>
+    {{ content }}
+  </body>
+</html>

data/lib/blank_template/_sass/base.scss

@@ -0,0 +1,9 @@
+$backgroundColor: #ffffff;
+$bodyColor: #000000;
+$bodyFont: -apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol";
+
+body {
+  background: $backgroundColor;
+  color: $bodyColor;
+  font-family: $bodyFont;
+}

data/lib/blank_template/assets/css/main.scss

@@ -0,0 +1,4 @@
+---
+---
+
+@import "base";

data/lib/blank_template/index.md

@@ -0,0 +1,8 @@
+---
+layout: default
+title: "Happy Jekylling!"
+---
+
+## You're ready to go!
+
+Start developing your Jekyll website.

data/lib/jekyll/cache.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Jekyll
+  class Cache
+    # class-wide base cache
+    @base_cache = {}
+
+    # class-wide directive to write cache to disk is enabled by default
+    @disk_cache_enabled = true
+
+    class << self
+      attr_accessor :cache_dir # class-wide cache location
+
+      attr_reader :base_cache, # class-wide base cache reader
+                  :disk_cache_enabled # class-wide directive to write cache to disk
+
+      # Disable Marshaling cached items to disk
+      def disable_disk_cache!
+        @disk_cache_enabled = false
+      end
+
+      # Clear all caches
+      def clear
+        delete_cache_files
+        base_cache.each_value(&:clear)
+      end
+
+      # Compare the current config to the cached config
+      # If they are different, clear all caches
+      #
+      # Returns nothing.
+      def clear_if_config_changed(config)
+        config = config.inspect
+        cache = Jekyll::Cache.new "Jekyll::Cache"
+        return if cache.key?("config") && cache["config"] == config
+
+        clear
+        cache = Jekyll::Cache.new "Jekyll::Cache"
+        cache["config"] = config
+        nil
+      end
+
+      private
+
+      # Delete all cached items from all caches
+      #
+      # Returns nothing.
+      def delete_cache_files
+        FileUtils.rm_rf(@cache_dir) if disk_cache_enabled
+      end
+    end
+
+    #
+
+    # Get an existing named cache, or create a new one if none exists
+    #
+    # name - name of the cache
+    #
+    # Returns nothing.
+    def initialize(name)
+      @cache = Jekyll::Cache.base_cache[name] ||= {}
+      @name = name.gsub(%r![^\w\s-]!, "-")
+    end
+
+    # Clear this particular cache
+    def clear
+      delete_cache_files
+      @cache.clear
+    end
+
+    # Retrieve a cached item
+    # Raises if key does not exist in cache
+    #
+    # Returns cached value
+    def [](key)
+      return @cache[key] if @cache.key?(key)
+
+      path = path_to(hash(key))
+      if disk_cache_enabled? && File.file?(path) && File.readable?(path)
+        @cache[key] = load(path)
+      else
+        raise
+      end
+    end
+
+    # Add an item to cache
+    #
+    # Returns nothing.
+    def []=(key, value)
+      @cache[key] = value
+      return unless disk_cache_enabled?
+
+      path = path_to(hash(key))
+      value = new Hash(value) if value.is_a?(Hash) && !value.default.nil?
+      dump(path, value)
+    rescue TypeError
+      Jekyll.logger.debug "Cache:", "Cannot dump object #{key}"
+    end
+
+    # If an item already exists in the cache, retrieve it.
+    # Else execute code block, and add the result to the cache, and return that result.
+    def getset(key)
+      self[key]
+    rescue StandardError
+      value = yield
+      self[key] = value
+      value
+    end
+
+    # Remove one particular item from the cache
+    #
+    # Returns nothing.
+    def delete(key)
+      @cache.delete(key)
+      File.delete(path_to(hash(key))) if disk_cache_enabled?
+    end
+
+    # Check if `key` already exists in this cache
+    #
+    # Returns true if key exists in the cache, false otherwise
+    def key?(key)
+      # First, check if item is already cached in memory
+      return true if @cache.key?(key)
+      # Otherwise, it might be cached on disk
+      # but we should not consider the disk cache if it is disabled
+      return false unless disk_cache_enabled?
+
+      path = path_to(hash(key))
+      File.file?(path) && File.readable?(path)
+    end
+
+    def disk_cache_enabled?
+      !!Jekyll::Cache.disk_cache_enabled
+    end
+
+    private
+
+    # Given a hashed key, return the path to where this item would be saved on disk.
+    def path_to(hash = nil)
+      @base_dir ||= File.join(Jekyll::Cache.cache_dir, @name)
+      return @base_dir if hash.nil?
+
+      File.join(@base_dir, hash[0..1], hash[2..-1]).freeze
+    end
+
+    # Given a key, return a SHA2 hash that can be used for caching this item to disk.
+    def hash(key)
+      Digest::SHA2.hexdigest(key).freeze
+    end
+
+    # Remove all this caches items from disk
+    #
+    # Returns nothing.
+    def delete_cache_files
+      FileUtils.rm_rf(path_to) if disk_cache_enabled?
+    end
+
+    # Load `path` from disk and return the result.
+    # This MUST NEVER be called in Safe Mode
+    # rubocop:disable Security/MarshalLoad
+    def load(path)
+      raise unless disk_cache_enabled?
+
+      cached_file = File.open(path, "rb")
+      value = Marshal.load(cached_file)
+      cached_file.close
+      value
+    end
+    # rubocop:enable Security/MarshalLoad
+
+    # Given a path and a value, save value to disk at path.
+    # This should NEVER be called in Safe Mode
+    #
+    # Returns nothing.
+    def dump(path, value)
+      return unless disk_cache_enabled?
+
+      FileUtils.mkdir_p(File.dirname(path))
+      File.open(path, "wb") do |cached_file|
+        Marshal.dump(value, cached_file)
+      end
+    end
+  end
+end

data/lib/jekyll/cleaner.rb

@@ -3,7 +3,7 @@
 module Jekyll
   # Handles the cleanup of a site's destination before it is built.
   class Cleaner
-    HIDDEN_FILE_REGEX = %r!\/\.{1,2}$!
+    HIDDEN_FILE_REGEX = %r!/\.{1,2}$!.freeze
     attr_reader :site
 
     def initialize(site)
@@ -29,7 +29,7 @@ module Jekyll
 
     # Private: The metadata file storing dependency tree and build history
     #
-    # Returns an Array with the metdata file as the only item
+    # Returns an Array with the metadata file as the only item
     def metadata_file
       [site.regenerator.metadata_file]
     end
@@ -44,7 +44,8 @@ module Jekyll
       dirs = keep_dirs
 
       Utils.safe_glob(site.in_dest_dir, ["**", "*"], File::FNM_DOTMATCH).each do |file|
-        next if file =~ HIDDEN_FILE_REGEX || file =~ regex || dirs.include?(file)
+        next if HIDDEN_FILE_REGEX.match?(file) || regex.match?(file) || dirs.include?(file)
+
         files << file
       end
 
@@ -65,7 +66,7 @@ module Jekyll
     #
     # Returns a Set with the directory paths
     def new_dirs
-      @new_dirs ||= new_files.map { |file| parent_dirs(file) }.flatten.to_set
+      @new_dirs ||= new_files.flat_map { |file| parent_dirs(file) }.to_set
     end
 
     # Private: The list of parent directories of a given file
@@ -76,7 +77,7 @@ module Jekyll
       if parent_dir == site.dest
         []
       else
-        [parent_dir] + parent_dirs(parent_dir)
+        parent_dirs(parent_dir).unshift(parent_dir)
       end
     end
 
@@ -93,7 +94,7 @@ module Jekyll
     #
     # Returns a Set with the directory paths
     def keep_dirs
-      site.keep_files.map { |file| parent_dirs(site.in_dest_dir(file)) }.flatten.to_set
+      site.keep_files.flat_map { |file| parent_dirs(site.in_dest_dir(file)) }.to_set
     end
 
     # Private: Creates a regular expression from the config's keep_files array
@@ -104,7 +105,7 @@ module Jekyll
     #
     # Returns the regular expression
     def keep_file_regex
-      %r!\A#{Regexp.quote(site.dest)}\/(#{Regexp.union(site.keep_files).source})!
+      %r!\A#{Regexp.quote(site.dest)}/(#{Regexp.union(site.keep_files).source})!
     end
   end
 end

data/lib/jekyll/collection.rb

@@ -35,7 +35,7 @@ module Jekyll
     def method_missing(method, *args, &blck)
       if docs.respond_to?(method.to_sym)
         Jekyll.logger.warn "Deprecation:",
-          "#{label}.#{method} should be changed to #{label}.docs.#{method}."
+                           "#{label}.#{method} should be changed to #{label}.docs.#{method}."
         Jekyll.logger.warn "", "Called by #{caller(0..0)}."
         docs.public_send(method.to_sym, *args, &blck)
       else
@@ -58,13 +58,15 @@ module Jekyll
       filtered_entries.each do |file_path|
         full_path = collection_dir(file_path)
         next if File.directory?(full_path)
+
         if Utils.has_yaml_header? full_path
           read_document(full_path)
         else
           read_static_file(file_path, full_path)
         end
       end
-      docs.sort!
+      site.static_files.concat(files) unless files.empty?
+      sort_docs!
     end
 
     # All the entries in this collection.
@@ -73,11 +75,14 @@ module Jekyll
     #   relative to the collection's directory
     def entries
       return [] unless exists?
-      @entries ||=
+
+      @entries ||= begin
+        collection_dir_slash = "#{collection_dir}/"
         Utils.safe_glob(collection_dir, ["**", "*"], File::FNM_DOTMATCH).map do |entry|
-          entry["#{collection_dir}/"] = ""
+          entry[collection_dir_slash] = ""
           entry
         end
+      end
     end
 
     # Filtered version of the entries in this collection.
@@ -86,6 +91,7 @@ module Jekyll
     # Returns a list of filtered entry paths.
     def filtered_entries
       return [] unless exists?
+
       @filtered_entries ||=
         Dir.chdir(directory) do
           entry_filter.filter(entries).reject do |f|
@@ -124,6 +130,7 @@ module Jekyll
     #   is stored on the filesystem.
     def collection_dir(*files)
       return directory if files.empty?
+
       site.in_source_dir(container, relative_directory, *files)
     end
 
@@ -149,7 +156,7 @@ module Jekyll
     #
     # Returns the inspect string
     def inspect
-      "#<Jekyll::Collection @label=#{label} docs=#{docs}>"
+      "#<#{self.class} @label=#{label} docs=#{docs}>"
     end
 
     # Produce a sanitized label name
@@ -160,7 +167,7 @@ module Jekyll
     #
     # Returns a sanitized version of the label.
     def sanitize_label(label)
-      label.gsub(%r![^a-z0-9_\-\.]!i, "")
+      label.gsub(%r![^a-z0-9_\-.]!i, "")
     end
 
     # Produce a representation of this Collection for use in Liquid.
@@ -207,17 +214,83 @@ module Jekyll
       @container ||= site.config["collections_dir"]
     end
 
-    private
-
     def read_document(full_path)
       doc = Document.new(full_path, :site => site, :collection => self)
       doc.read
-      if site.unpublished || doc.published?
-        docs << doc
+      docs << doc if site.unpublished || doc.published?
+    end
+
+    def sort_docs!
+      if metadata["order"].is_a?(Array)
+        rearrange_docs!
+      elsif metadata["sort_by"].is_a?(String)
+        sort_docs_by_key!
+      else
+        docs.sort!
       end
     end
 
-    private
+    # A custom sort function based on Schwartzian transform
+    # Refer https://byparker.com/blog/2017/schwartzian-transform-faster-sorting/ for details
+    def sort_docs_by_key!
+      meta_key = metadata["sort_by"]
+      # Modify `docs` array to cache document's property along with the Document instance
+      docs.map! { |doc| [doc.data[meta_key], doc] }.sort! do |apples, olives|
+        order = determine_sort_order(meta_key, apples, olives)
+
+        # Fall back to `Document#<=>` if the properties were equal or were non-sortable
+        # Otherwise continue with current sort-order
+        if order.nil? || order.zero?
+          apples[-1] <=> olives[-1]
+        else
+          order
+        end
+
+        # Finally restore the `docs` array with just the Document objects themselves
+      end.map!(&:last)
+    end
+
+    def determine_sort_order(sort_key, apples, olives)
+      apple_property, apple_document = apples
+      olive_property, olive_document = olives
+
+      if apple_property.nil? && !olive_property.nil?
+        order_with_warning(sort_key, apple_document, 1)
+      elsif !apple_property.nil? && olive_property.nil?
+        order_with_warning(sort_key, olive_document, -1)
+      else
+        apple_property <=> olive_property
+      end
+    end
+
+    def order_with_warning(sort_key, document, order)
+      Jekyll.logger.warn "Sort warning:", "'#{sort_key}' not defined in #{document.relative_path}"
+      order
+    end
+
+    # Rearrange documents within the `docs` array as listed in the `metadata["order"]` array.
+    #
+    # Involves converting the two arrays into hashes based on relative_paths as keys first, then
+    # merging them to remove duplicates and finally retrieving the Document instances from the
+    # merged array.
+    def rearrange_docs!
+      docs_table   = {}
+      custom_order = {}
+
+      # pre-sort to normalize default array across platforms and then proceed to create a Hash
+      # from that sorted array.
+      docs.sort.each do |doc|
+        docs_table[doc.relative_path] = doc
+      end
+
+      metadata["order"].each do |entry|
+        custom_order[File.join(relative_directory, entry)] = nil
+      end
+
+      result = Jekyll::Utils.deep_merge_hashes(custom_order, docs_table).values
+      result.compact!
+      self.docs = result
+    end
 
     def read_static_file(file_path, full_path)
       relative_dir = Jekyll.sanitized_path(

data/lib/jekyll/command.rb

@@ -40,6 +40,7 @@ module Jekyll
       # Returns a full Jekyll configuration
       def configuration_from_options(options)
         return options if options.is_a?(Jekyll::Configuration)
+
         Jekyll.configuration(options)
       end
 
@@ -51,28 +52,54 @@ module Jekyll
       # rubocop:disable Metrics/MethodLength
       def add_build_options(cmd)
         cmd.option "config", "--config CONFIG_FILE[,CONFIG_FILE2,...]",
-          Array, "Custom configuration file"
+                   Array, "Custom configuration file"
         cmd.option "destination", "-d", "--destination DESTINATION",
-          "The current folder will be generated into DESTINATION"
+                   "The current folder will be generated into DESTINATION"
         cmd.option "source", "-s", "--source SOURCE", "Custom source directory"
         cmd.option "future", "--future", "Publishes posts with a future date"
         cmd.option "limit_posts", "--limit_posts MAX_POSTS", Integer,
-          "Limits the number of posts to parse and publish"
+                   "Limits the number of posts to parse and publish"
         cmd.option "watch", "-w", "--[no-]watch", "Watch for changes and rebuild"
         cmd.option "baseurl", "-b", "--baseurl URL",
-          "Serve the website from the given base URL"
+                   "Serve the website from the given base URL"
         cmd.option "force_polling", "--force_polling", "Force watch to use polling"
         cmd.option "lsi", "--lsi", "Use LSI for improved related posts"
         cmd.option "show_drafts", "-D", "--drafts", "Render posts in the _drafts folder"
         cmd.option "unpublished", "--unpublished",
-          "Render posts that were marked as unpublished"
+                   "Render posts that were marked as unpublished"
+        cmd.option "disable_disk_cache", "--disable-disk-cache",
+                   "Disable caching to disk in non-safe mode"
         cmd.option "quiet", "-q", "--quiet", "Silence output."
         cmd.option "verbose", "-V", "--verbose", "Print verbose output."
         cmd.option "incremental", "-I", "--incremental", "Enable incremental rebuild."
         cmd.option "strict_front_matter", "--strict_front_matter",
-          "Fail if errors are present in front matter"
+                   "Fail if errors are present in front matter"
       end
       # rubocop:enable Metrics/MethodLength
+
+      # Run ::process method in a given set of Jekyll::Command subclasses and suggest
+      # re-running the associated command with --trace switch to obtain any additional
+      # information or backtrace regarding the encountered Exception.
+      #
+      # cmd     - the Jekyll::Command to be handled
+      # options - configuration overrides
+      # klass   - an array of Jekyll::Command subclasses associated with the command
+      #
+      # Note that all exceptions are rescued..
+      # rubocop: disable Lint/RescueException
+      def process_with_graceful_fail(cmd, options, *klass)
+        klass.each { |k| k.process(options) if k.respond_to?(:process) }
+      rescue Exception => e
+        raise e if cmd.trace
+
+        msg = " Please append `--trace` to the `#{cmd.name}` command "
+        dashes = "-" * msg.length
+        Jekyll.logger.error "", dashes
+        Jekyll.logger.error "Jekyll #{Jekyll::VERSION} ", msg
+        Jekyll.logger.error "", " for any additional information or backtrace. "
+        Jekyll.logger.abort_with "", dashes
+      end
+      # rubocop: enable Lint/RescueException
     end
   end
 end