jekyll 3.10.0 → 4.0.0.pre.alpha1

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,14 @@ 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!
+      sort_docs!
     end
 
     # All the entries in this collection.
@@ -73,6 +74,7 @@ module Jekyll
     #   relative to the collection's directory
     def entries
       return [] unless exists?
+
       @entries ||=
         Utils.safe_glob(collection_dir, ["**", "*"], File::FNM_DOTMATCH).map do |entry|
           entry["#{collection_dir}/"] = ""
@@ -86,6 +88,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 +127,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 +153,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
@@ -207,17 +211,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.zero? || order.nil?
+          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,52 @@ 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 "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 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 RescueException
     end
   end
 end

data/lib/jekyll/commands/build.rb

@@ -15,7 +15,7 @@ module Jekyll
 
             c.action do |_, options|
               options["serving"] = false
-              Jekyll::Commands::Build.process(options)
+              process_with_graceful_fail(c, options, self)
             end
           end
         end
@@ -31,14 +31,14 @@ module Jekyll
 
           if options.fetch("skip_initial_build", false)
             Jekyll.logger.warn "Build Warning:", "Skipping the initial build." \
-                        " This may result in an out-of-date site."
+                               " This may result in an out-of-date site."
           else
             build(site, options)
           end
 
           if options.fetch("detach", false)
             Jekyll.logger.info "Auto-regeneration:",
-              "disabled when running server detached."
+                               "disabled when running server detached."
           elsif options.fetch("watch", false)
             watch(site, options)
           else
@@ -54,13 +54,13 @@ module Jekyll
         # Returns nothing.
         def build(site, options)
           t = Time.now
-          source      = options["source"]
-          destination = options["destination"]
+          source      = File.expand_path(options["source"])
+          destination = File.expand_path(options["destination"])
           incremental = options["incremental"]
           Jekyll.logger.info "Source:", source
           Jekyll.logger.info "Destination:", destination
           Jekyll.logger.info "Incremental build:",
-            (incremental ? "enabled" : "disabled. Enable with --incremental")
+                             (incremental ? "enabled" : "disabled. Enable with --incremental")
           Jekyll.logger.info "Generating..."
           process_site(site)
           Jekyll.logger.info "", "done in #{(Time.now - t).round(3)} seconds."
@@ -76,25 +76,16 @@ module Jekyll
           # Warn Windows users that they might need to upgrade.
           if Utils::Platforms.bash_on_windows?
             Jekyll.logger.warn "",
-              "Auto-regeneration may not work on some Windows versions."
+                               "Auto-regeneration may not work on some Windows versions."
             Jekyll.logger.warn "",
-              "Please see: https://github.com/Microsoft/BashOnWindows/issues/216"
+                               "Please see: https://github.com/Microsoft/BashOnWindows/issues/216"
             Jekyll.logger.warn "",
-              "If it does not work, please upgrade Bash on Windows or "\
-                "run Jekyll with --no-watch."
+                               "If it does not work, please upgrade Bash on Windows or "\
+                               "run Jekyll with --no-watch."
           end
 
           External.require_with_graceful_fail "jekyll-watch"
-          watch_method = Jekyll::Watcher.method(:watch)
-          if watch_method.parameters.size == 1
-            watch_method.call(
-              options
-            )
-          else
-            watch_method.call(
-              options, site
-            )
-          end
+          Jekyll::Watcher.watch(options, site)
         end
       end
     end

data/lib/jekyll/commands/clean.rb

@@ -22,10 +22,12 @@ module Jekyll
           options = configuration_from_options(options)
           destination = options["destination"]
           metadata_file = File.join(options["source"], ".jekyll-metadata")
+          cache_dir = File.join(options["source"], options["cache_dir"])
           sass_cache = ".sass-cache"
 
           remove(destination, :checker_func => :directory?)
           remove(metadata_file, :checker_func => :file?)
+          remove(cache_dir, :checker_func => :directory?)
           remove(sass_cache, :checker_func => :directory?)
         end
 

data/lib/jekyll/commands/doctor.rb

@@ -11,7 +11,7 @@ module Jekyll
             c.alias(:hyde)
 
             c.option "config", "--config CONFIG_FILE[,CONFIG_FILE2,...]", Array,
-                            "Custom configuration file"
+                     "Custom configuration file"
 
             c.action do |_, options|
               Jekyll::Commands::Doctor.process(options)
@@ -45,22 +45,23 @@ module Jekyll
 
         def properly_gathered_posts?(site)
           return true if site.config["collections_dir"].empty?
+
           posts_at_root = site.in_source_dir("_posts")
           return true unless File.directory?(posts_at_root)
+
           Jekyll.logger.warn "Warning:",
-            "Detected '_posts' directory outside custom `collections_dir`!"
+                             "Detected '_posts' directory outside custom `collections_dir`!"
           Jekyll.logger.warn "",
-            "Please move '#{posts_at_root}' into the custom directory at " \
+                             "Please move '#{posts_at_root}' into the custom directory at " \
             "'#{site.in_source_dir(site.config["collections_dir"])}'"
           false
         end
 
         def deprecated_relative_permalinks(site)
           if site.config["relative_permalinks"]
-            Jekyll::Deprecator.deprecation_message "Your site still uses relative" \
-                                " permalinks, which was removed in" \
-                                " Jekyll v3.0.0."
-            return true
+            Jekyll::Deprecator.deprecation_message "Your site still uses relative permalinks," \
+                                                   " which was removed in Jekyll v3.0.0."
+            true
           end
         end
 
@@ -71,6 +72,7 @@ module Jekyll
           urls = collect_urls(urls, site.posts.docs, site.dest)
           urls.each do |url, paths|
             next unless paths.size > 1
+
             conflicting_urls = true
             Jekyll.logger.warn "Conflict:", "The URL '#{url}' is the destination" \
               " for the following pages: #{paths.join(", ")}"
@@ -80,6 +82,7 @@ module Jekyll
 
         def fsnotify_buggy?(_site)
           return true unless Utils::Platforms.osx?
+
           if Dir.pwd != `pwd`.strip
             Jekyll.logger.error "  " + <<-STR.strip.gsub(%r!\n\s+!, "\n  ")
               We have detected that there might be trouble using fsevent on your
@@ -99,6 +102,7 @@ module Jekyll
           urls = case_insensitive_urls(site.pages + site.docs_to_write, site.dest)
           urls.each_value do |real_urls|
             next unless real_urls.uniq.size > 1
+
             urls_only_differ_by_case = true
             Jekyll.logger.warn "Warning:", "The following URLs only differ" \
               " by case. On a case-insensitive file system one of the URLs" \
@@ -117,6 +121,7 @@ module Jekyll
         end
 
         private
+
         def collect_urls(urls, things, destination)
           things.each do |thing|
             dest = thing.destination(destination)
@@ -138,6 +143,7 @@ module Jekyll
 
         def url_exists?(url)
           return true unless url.nil? || url.empty?
+
           Jekyll.logger.warn "Warning:", "You didn't set an URL in the config file, "\
               "you may encounter problems with some plugins."
           false
@@ -155,7 +161,8 @@ module Jekyll
         end
 
         def url_absolute(url)
-          return true if Addressable::URI.parse(url).absolute?
+          return true if url.is_a?(String) && Addressable::URI.parse(url).absolute?
+
           Jekyll.logger.warn "Warning:", "Your site URL does not seem to be absolute, "\
               "check the value of `url` in your config file."
           false

data/lib/jekyll/commands/help.rb

@@ -25,7 +25,7 @@ module Jekyll
 
         def invalid_command(prog, cmd)
           Jekyll.logger.error "Error:",
-                "Hmm... we don't know what the '#{cmd}' command is."
+                              "Hmm... we don't know what the '#{cmd}' command is."
           Jekyll.logger.info  "Valid commands:", prog.commands.keys.join(", ")
         end
       end

data/lib/jekyll/commands/new.rb

@@ -41,10 +41,16 @@ module Jekyll
           after_install(new_blog_path, options)
         end
 
+        def blank_template
+          File.expand_path("../../blank_template", __dir__)
+        end
+
         def create_blank_site(path)
+          FileUtils.cp_r blank_template + "/.", path
+          FileUtils.chmod_R "u+w", path
+
           Dir.chdir(path) do
-            FileUtils.mkdir(%w(_layouts _posts _drafts))
-            FileUtils.touch("index.html")
+            FileUtils.mkdir(%w(_data _drafts _includes _posts))
           end
         end
 
@@ -62,49 +68,38 @@ module Jekyll
         private
 
         def gemfile_contents
-          <<-RUBY
-source "https://rubygems.org"
-
-# Hello! This is where you manage which Jekyll version is used to run.
-# When you want to use a different version, change it below, save the
-# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
-#
-#     bundle exec jekyll serve
-#
-# This will help ensure the proper Jekyll version is running.
-# Happy Jekylling!
-gem "jekyll", "~> #{Jekyll::VERSION}"
-
-# This is the default theme for new Jekyll sites. You may change this to anything you like.
-gem "minima", "~> 2.0"
-
-# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
-# uncomment the line below. To upgrade, run `bundle update github-pages`.
-# gem "github-pages", group: :jekyll_plugins
-
-# If you have any plugins, put them here!
-group :jekyll_plugins do
-  gem "jekyll-feed", "~> 0.6"
-end
-
-# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
-# and associated library.
-platforms :mingw, :x64_mingw, :mswin, :jruby do
-  gem "tzinfo", ">= 1", "< 3"
-  gem "tzinfo-data"
-end
+          <<~RUBY
+            source "https://rubygems.org"
+            # Hello! This is where you manage which Jekyll version is used to run.
+            # When you want to use a different version, change it below, save the
+            # file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
+            #
+            #     bundle exec jekyll serve
+            #
+            # This will help ensure the proper Jekyll version is running.
+            # Happy Jekylling!
+            gem "jekyll", "~> #{Jekyll::VERSION}"
+            # This is the default theme for new Jekyll sites. You may change this to anything you like.
+            gem "minima", "~> 2.0"
+            # If you want to use GitHub Pages, remove the "gem "jekyll"" above and
+            # uncomment the line below. To upgrade, run `bundle update github-pages`.
+            # gem "github-pages", group: :jekyll_plugins
+            # If you have any plugins, put them here!
+            group :jekyll_plugins do
+              gem "jekyll-feed", "~> 0.6"
+            end
 
-# Performance-booster for watching directories on Windows
-gem "wdm", "~> 0.1.0", :install_if => Gem.win_platform?
+            # Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
+            # and associated library.
+            install_if -> { RUBY_PLATFORM =~ %r!mingw|mswin|java! } do
+              gem "tzinfo", "~> 1.2"
+              gem "tzinfo-data"
+            end
 
-# kramdown v2 ships without the gfm parser by default. If you're using
-# kramdown v1, comment out this line.
-gem "kramdown-parser-gfm"
+            # Performance-booster for watching directories on Windows
+            gem "wdm", "~> 0.1.1", :install_if => Gem.win_platform?
 
-# Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds since newer versions of the gem
-# do not have a Java counterpart.
-gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby]
-RUBY
+          RUBY
         end
 
         def create_site(new_blog_path)

data/lib/jekyll/commands/new_theme.rb

@@ -2,39 +2,41 @@
 
 require "erb"
 
-class Jekyll::Commands::NewTheme < Jekyll::Command
-  class << self
-    def init_with_program(prog)
-      prog.command(:"new-theme") do |c|
-        c.syntax "new-theme NAME"
-        c.description "Creates a new Jekyll theme scaffold"
-        c.option "code_of_conduct", \
-          "-c", "--code-of-conduct", \
-          "Include a Code of Conduct. (defaults to false)"
+module Jekyll
+  module Commands
+    class NewTheme < Jekyll::Command
+      class << self
+        def init_with_program(prog)
+          prog.command(:"new-theme") do |c|
+            c.syntax "new-theme NAME"
+            c.description "Creates a new Jekyll theme scaffold"
+            c.option "code_of_conduct", \
+                     "-c", "--code-of-conduct", \
+                     "Include a Code of Conduct. (defaults to false)"
 
-        c.action do |args, opts|
-          Jekyll::Commands::NewTheme.process(args, opts)
+            c.action do |args, opts|
+              Jekyll::Commands::NewTheme.process(args, opts)
+            end
+          end
         end
-      end
-    end
 
-    # rubocop:disable Metrics/AbcSize
-    def process(args, opts)
-      if !args || args.empty?
-        raise Jekyll::Errors::InvalidThemeName, "You must specify a theme name."
-      end
+        # rubocop:disable Metrics/AbcSize
+        def process(args, opts)
+          if !args || args.empty?
+            raise Jekyll::Errors::InvalidThemeName, "You must specify a theme name."
+          end
 
-      new_theme_name = args.join("_")
-      theme = Jekyll::ThemeBuilder.new(new_theme_name, opts)
-      if theme.path.exist?
-        Jekyll.logger.abort_with "Conflict:", "#{theme.path} already exists."
-      end
+          new_theme_name = args.join("_")
+          theme = Jekyll::ThemeBuilder.new(new_theme_name, opts)
+          Jekyll.logger.abort_with "Conflict:", "#{theme.path} already exists." if theme.path.exist?
 
-      theme.create!
-      Jekyll.logger.info "Your new Jekyll theme, #{theme.name.cyan}," \
-        " is ready for you in #{theme.path.to_s.cyan}!"
-      Jekyll.logger.info "For help getting started, read #{theme.path}/README.md."
+          theme.create!
+          Jekyll.logger.info "Your new Jekyll theme, #{theme.name.cyan}," \
+                             " is ready for you in #{theme.path.to_s.cyan}!"
+          Jekyll.logger.info "For help getting started, read #{theme.path}/README.md."
+        end
+        # rubocop:enable Metrics/AbcSize
+      end
     end
-    # rubocop:enable Metrics/AbcSize
   end
 end

data/lib/jekyll/commands/serve/live_reload_reactor.rb

@@ -58,7 +58,7 @@ module Jekyll
               EM.add_shutdown_hook { @stopped_event.set }
 
               Jekyll.logger.info "LiveReload address:",
-                "http://#{opts["host"]}:#{opts["livereload_port"]}"
+                                 "http://#{opts["host"]}:#{opts["livereload_port"]}"
             end
           end
           @thread.abort_on_exception = true
@@ -68,11 +68,11 @@ module Jekyll
         # http://feedback.livereload.com/knowledgebase/articles/86174-livereload-protocol
         def reload(pages)
           pages.each do |p|
-            json_message = JSON.dump({
+            json_message = JSON.dump(
               :command => "reload",
               :path    => p.url,
-              :liveCSS => true,
-            })
+              :liveCSS => true
+            )
 
             Jekyll.logger.debug "LiveReload:", "Reloading #{p.url}"
             Jekyll.logger.debug "", json_message
@@ -81,6 +81,7 @@ module Jekyll
         end
 
         private
+
         def connect(websocket, handshake)
           @connections_count += 1
           if @connections_count == 1
@@ -99,22 +100,17 @@ module Jekyll
           @websockets << websocket
         end
 
-        private
         def disconnect(websocket)
           @websockets.delete(websocket)
         end
 
-        private
         def print_message(json_message)
           msg = JSON.parse(json_message)
           # Not sure what the 'url' command even does in LiveReload.  The spec is silent
           # on its purpose.
-          if msg["command"] == "url"
-            Jekyll.logger.info "LiveReload:", "Browser URL: #{msg["url"]}"
-          end
+          Jekyll.logger.info "LiveReload:", "Browser URL: #{msg["url"]}" if msg["command"] == "url"
         end
 
-        private
         def log_error(error)
           Jekyll.logger.error "LiveReload experienced an error. " \
             "Run with --trace for more information."