jekyll-docs 3.6.0 → 3.6.1

data/lib/jekyll/command.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Jekyll
+  class Command
+    class << self
+      # A list of subclasses of Jekyll::Command
+      def subclasses
+        @subclasses ||= []
+      end
+
+      # Keep a list of subclasses of Jekyll::Command every time it's inherited
+      # Called automatically.
+      #
+      # base - the subclass
+      #
+      # Returns nothing
+      def inherited(base)
+        subclasses << base
+        super(base)
+      end
+
+      # Run Site#process and catch errors
+      #
+      # site - the Jekyll::Site object
+      #
+      # Returns nothing
+      def process_site(site)
+        site.process
+      rescue Jekyll::Errors::FatalException => e
+        Jekyll.logger.error "ERROR:", "YOUR SITE COULD NOT BE BUILT:"
+        Jekyll.logger.error "", "------------------------------------"
+        Jekyll.logger.error "", e.message
+        exit(1)
+      end
+
+      # Create a full Jekyll configuration with the options passed in as overrides
+      #
+      # options - the configuration overrides
+      #
+      # Returns a full Jekyll configuration
+      def configuration_from_options(options)
+        return options if options.is_a?(Jekyll::Configuration)
+        Jekyll.configuration(options)
+      end
+
+      # Add common options to a command for building configuration
+      #
+      # c - the Jekyll::Command to add these options to
+      #
+      # Returns nothing
+      # rubocop:disable Metrics/MethodLength
+      def add_build_options(c)
+        c.option "config", "--config CONFIG_FILE[,CONFIG_FILE2,...]",
+          Array, "Custom configuration file"
+        c.option "destination", "-d", "--destination DESTINATION",
+          "The current folder will be generated into DESTINATION"
+        c.option "source", "-s", "--source SOURCE", "Custom source directory"
+        c.option "future", "--future", "Publishes posts with a future date"
+        c.option "limit_posts", "--limit_posts MAX_POSTS", Integer,
+          "Limits the number of posts to parse and publish"
+        c.option "watch", "-w", "--[no-]watch", "Watch for changes and rebuild"
+        c.option "baseurl", "-b", "--baseurl URL",
+          "Serve the website from the given base URL"
+        c.option "force_polling", "--force_polling", "Force watch to use polling"
+        c.option "lsi", "--lsi", "Use LSI for improved related posts"
+        c.option "show_drafts", "-D", "--drafts", "Render posts in the _drafts folder"
+        c.option "unpublished", "--unpublished",
+          "Render posts that were marked as unpublished"
+        c.option "quiet", "-q", "--quiet", "Silence output."
+        c.option "verbose", "-V", "--verbose", "Print verbose output."
+        c.option "incremental", "-I", "--incremental", "Enable incremental rebuild."
+        c.option "strict_front_matter", "--strict_front_matter",
+          "Fail if errors are present in front matter"
+      end
+      # rubocop:enable Metrics/MethodLength
+    end
+  end
+end

data/lib/jekyll/commands/build.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Commands
+    class Build < Command
+      class << self
+        # Create the Mercenary command for the Jekyll CLI for this Command
+        def init_with_program(prog)
+          prog.command(:build) do |c|
+            c.syntax      "build [options]"
+            c.description "Build your site"
+            c.alias :b
+
+            add_build_options(c)
+
+            c.action do |_, options|
+              options["serving"] = false
+              Jekyll::Commands::Build.process(options)
+            end
+          end
+        end
+
+        # Build your jekyll site
+        # Continuously watch if `watch` is set to true in the config.
+        def process(options)
+          # Adjust verbosity quickly
+          Jekyll.logger.adjust_verbosity(options)
+
+          options = configuration_from_options(options)
+          site = Jekyll::Site.new(options)
+
+          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."
+          else
+            build(site, options)
+          end
+
+          if options.fetch("detach", false)
+            Jekyll.logger.info "Auto-regeneration:",
+              "disabled when running server detached."
+          elsif options.fetch("watch", false)
+            watch(site, options)
+          else
+            Jekyll.logger.info "Auto-regeneration:", "disabled. Use --watch to enable."
+          end
+        end
+
+        # Build your Jekyll site.
+        #
+        # site - the Jekyll::Site instance to build
+        # options - A Hash of options passed to the command
+        #
+        # Returns nothing.
+        def build(site, options)
+          t = Time.now
+          source      = options["source"]
+          destination = 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")
+          Jekyll.logger.info "Generating..."
+          process_site(site)
+          Jekyll.logger.info "", "done in #{(Time.now - t).round(3)} seconds."
+        end
+
+        # Private: Watch for file changes and rebuild the site.
+        #
+        # site - A Jekyll::Site instance
+        # options - A Hash of options passed to the command
+        #
+        # Returns nothing.
+        def watch(site, options)
+          # 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."
+            Jekyll.logger.warn "",
+              "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."
+          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
+        end
+      end # end of class << self
+    end
+  end
+end

data/lib/jekyll/commands/clean.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Commands
+    class Clean < Command
+      class << self
+        def init_with_program(prog)
+          prog.command(:clean) do |c|
+            c.syntax "clean [subcommand]"
+            c.description "Clean the site " \
+                  "(removes site output and metadata file) without building."
+
+            add_build_options(c)
+
+            c.action do |_, options|
+              Jekyll::Commands::Clean.process(options)
+            end
+          end
+        end
+
+        def process(options)
+          options = configuration_from_options(options)
+          destination = options["destination"]
+          metadata_file = File.join(options["source"], ".jekyll-metadata")
+          sass_cache = File.join(options["source"], ".sass-cache")
+
+          remove(destination, :checker_func => :directory?)
+          remove(metadata_file, :checker_func => :file?)
+          remove(sass_cache, :checker_func => :directory?)
+        end
+
+        def remove(filename, checker_func: :file?)
+          if File.public_send(checker_func, filename)
+            Jekyll.logger.info "Cleaner:", "Removing #{filename}..."
+            FileUtils.rm_rf(filename)
+          else
+            Jekyll.logger.info "Cleaner:", "Nothing to do for #{filename}."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jekyll/commands/doctor.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "addressable/uri"
+
+module Jekyll
+  module Commands
+    class Doctor < Command
+      class << self
+        def init_with_program(prog)
+          prog.command(:doctor) do |c|
+            c.syntax "doctor"
+            c.description "Search site and print specific deprecation warnings"
+            c.alias(:hyde)
+
+            c.option "config", "--config CONFIG_FILE[,CONFIG_FILE2,...]", Array,
+                            "Custom configuration file"
+
+            c.action do |_, options|
+              Jekyll::Commands::Doctor.process(options)
+            end
+          end
+        end
+
+        def process(options)
+          site = Jekyll::Site.new(configuration_from_options(options))
+          site.reset
+          site.read
+          site.generate
+
+          if healthy?(site)
+            Jekyll.logger.info "Your test results", "are in. Everything looks fine."
+          else
+            abort
+          end
+        end
+
+        def healthy?(site)
+          [
+            fsnotify_buggy?(site),
+            !deprecated_relative_permalinks(site),
+            !conflicting_urls(site),
+            !urls_only_differ_by_case(site),
+            proper_site_url?(site),
+          ].all?
+        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
+          end
+        end
+
+        def conflicting_urls(site)
+          conflicting_urls = false
+          urls = {}
+          urls = collect_urls(urls, site.pages, site.dest)
+          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(", ")}"
+          end
+          conflicting_urls
+        end
+
+        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
+              operating system, you can read https://github.com/thibaudgg/rb-fsevent/wiki/no-fsevents-fired-(OSX-bug)
+              for possible work arounds or you can work around it immediately
+              with `--force-polling`.
+            STR
+
+            false
+          end
+
+          true
+        end
+
+        def urls_only_differ_by_case(site)
+          urls_only_differ_by_case = false
+          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" \
+              " will be overwritten by the other: #{real_urls.join(", ")}"
+          end
+          urls_only_differ_by_case
+        end
+
+        def proper_site_url?(site)
+          url = site.config["url"]
+          [
+            url_exists?(url),
+            url_valid?(url),
+            url_absolute(url),
+          ].all?
+        end
+
+        private
+        def collect_urls(urls, things, destination)
+          things.each do |thing|
+            dest = thing.destination(destination)
+            if urls[dest]
+              urls[dest] << thing.path
+            else
+              urls[dest] = [thing.path]
+            end
+          end
+          urls
+        end
+
+        def case_insensitive_urls(things, destination)
+          things.each_with_object({}) do |thing, memo|
+            dest = thing.destination(destination)
+            (memo[dest.downcase] ||= []) << dest
+          end
+        end
+
+        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
+        end
+
+        def url_valid?(url)
+          Addressable::URI.parse(url)
+          true
+        rescue
+          Jekyll.logger.warn "Warning:", "The site URL does not seem to be valid, "\
+              "check the value of `url` in your config file."
+          false
+        end
+
+        def url_absolute(url)
+          return true if 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
+        end
+      end
+    end
+  end
+end

data/lib/jekyll/commands/help.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Commands
+    class Help < Command
+      class << self
+        def init_with_program(prog)
+          prog.command(:help) do |c|
+            c.syntax "help [subcommand]"
+            c.description "Show the help message, optionally for a given subcommand."
+
+            c.action do |args, _|
+              cmd = (args.first || "").to_sym
+              if args.empty?
+                puts prog
+              elsif prog.has_command? cmd
+                puts prog.commands[cmd]
+              else
+                invalid_command(prog, cmd)
+                abort
+              end
+            end
+          end
+        end
+
+        def invalid_command(prog, cmd)
+          Jekyll.logger.error "Error:",
+                "Hmm... we don't know what the '#{cmd}' command is."
+          Jekyll.logger.info  "Valid commands:", prog.commands.keys.join(", ")
+        end
+      end
+    end
+  end
+end

data/lib/jekyll/commands/new.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module Jekyll
+  module Commands
+    class New < Command
+      class << self
+        def init_with_program(prog)
+          prog.command(:new) do |c|
+            c.syntax "new PATH"
+            c.description "Creates a new Jekyll site scaffold in PATH"
+
+            c.option "force", "--force", "Force creation even if PATH already exists"
+            c.option "blank", "--blank", "Creates scaffolding but with empty files"
+            c.option "skip-bundle", "--skip-bundle", "Skip 'bundle install'"
+
+            c.action do |args, options|
+              Jekyll::Commands::New.process(args, options)
+            end
+          end
+        end
+
+        def process(args, options = {})
+          raise ArgumentError, "You must specify a path." if args.empty?
+
+          new_blog_path = File.expand_path(args.join(" "), Dir.pwd)
+          FileUtils.mkdir_p new_blog_path
+          if preserve_source_location?(new_blog_path, options)
+            Jekyll.logger.abort_with "Conflict:",
+                      "#{new_blog_path} exists and is not empty."
+          end
+
+          if options["blank"]
+            create_blank_site new_blog_path
+          else
+            create_site new_blog_path
+          end
+
+          after_install(new_blog_path, options)
+        end
+
+        def create_blank_site(path)
+          Dir.chdir(path) do
+            FileUtils.mkdir(%w(_layouts _posts _drafts))
+            FileUtils.touch("index.html")
+          end
+        end
+
+        def scaffold_post_content
+          ERB.new(File.read(File.expand_path(scaffold_path, site_template))).result
+        end
+
+        # Internal: Gets the filename of the sample post to be created
+        #
+        # Returns the filename of the sample post, as a String
+        def initialized_post_name
+          "_posts/#{Time.now.strftime("%Y-%m-%d")}-welcome-to-jekyll.markdown"
+        end
+
+        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 does not include zoneinfo files, so bundle the tzinfo-data gem
+gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw, :jruby]
+
+RUBY
+        end
+
+        def create_site(new_blog_path)
+          create_sample_files new_blog_path
+
+          File.open(File.expand_path(initialized_post_name, new_blog_path), "w") do |f|
+            f.write(scaffold_post_content)
+          end
+
+          File.open(File.expand_path("Gemfile", new_blog_path), "w") do |f|
+            f.write(gemfile_contents)
+          end
+        end
+
+        def preserve_source_location?(path, options)
+          !options["force"] && !Dir["#{path}/**/*"].empty?
+        end
+
+        def create_sample_files(path)
+          FileUtils.cp_r site_template + "/.", path
+          FileUtils.chmod_R "u+w", path
+          FileUtils.rm File.expand_path(scaffold_path, path)
+        end
+
+        def site_template
+          File.expand_path("../../site_template", __dir__)
+        end
+
+        def scaffold_path
+          "_posts/0000-00-00-welcome-to-jekyll.markdown.erb"
+        end
+
+        # After a new blog has been created, print a success notification and
+        # then automatically execute bundle install from within the new blog dir
+        # unless the user opts to generate a blank blog or skip 'bundle install'.
+
+        def after_install(path, options = {})
+          unless options["blank"] || options["skip-bundle"]
+            begin
+              require "bundler"
+              bundle_install path
+            rescue LoadError
+              Jekyll.logger.info "Could not load Bundler. Bundle install skipped."
+            end
+          end
+
+          Jekyll.logger.info "New jekyll site installed in #{path.cyan}."
+          Jekyll.logger.info "Bundle install skipped." if options["skip-bundle"]
+        end
+
+        def bundle_install(path)
+          Jekyll.logger.info "Running bundle install in #{path.cyan}..."
+          Dir.chdir(path) do
+            process, output = Jekyll::Utils::Exec.run("bundle", "install")
+            output.to_s.each_line do |line|
+              Jekyll.logger.info("Bundler:".green, line.strip) unless line.to_s.empty?
+            end
+            raise SystemExit unless process.success?
+          end
+        end
+      end
+    end
+  end
+end