jekyll-docs 3.6.1.0 → 3.6.2

data/lib/jekyll/drops/url_drop.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Drops
+    class UrlDrop < Drop
+      extend Forwardable
+
+      mutable false
+
+      def_delegator :@obj, :cleaned_relative_path, :path
+      def_delegator :@obj, :output_ext, :output_ext
+
+      def collection
+        @obj.collection.label
+      end
+
+      def name
+        Utils.slugify(@obj.basename_without_ext)
+      end
+
+      def title
+        Utils.slugify(@obj.data["slug"], :mode => "pretty", :cased => true) ||
+          Utils.slugify(@obj.basename_without_ext, :mode => "pretty", :cased => true)
+      end
+
+      def slug
+        Utils.slugify(@obj.data["slug"]) || Utils.slugify(@obj.basename_without_ext)
+      end
+
+      def categories
+        category_set = Set.new
+        Array(@obj.data["categories"]).each do |category|
+          category_set << category.to_s.downcase
+        end
+        category_set.to_a.join("/")
+      end
+
+      def year
+        @obj.date.strftime("%Y")
+      end
+
+      def month
+        @obj.date.strftime("%m")
+      end
+
+      def day
+        @obj.date.strftime("%d")
+      end
+
+      def hour
+        @obj.date.strftime("%H")
+      end
+
+      def minute
+        @obj.date.strftime("%M")
+      end
+
+      def second
+        @obj.date.strftime("%S")
+      end
+
+      def i_day
+        @obj.date.strftime("%-d")
+      end
+
+      def i_month
+        @obj.date.strftime("%-m")
+      end
+
+      def short_month
+        @obj.date.strftime("%b")
+      end
+
+      def short_year
+        @obj.date.strftime("%y")
+      end
+
+      def y_day
+        @obj.date.strftime("%j")
+      end
+
+      private
+      def fallback_data
+        {}
+      end
+    end
+  end
+end

data/lib/jekyll/entry_filter.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Jekyll
+  class EntryFilter
+    attr_reader :site
+    SPECIAL_LEADING_CHARACTERS = [
+      ".", "_", "#", "~",
+    ].freeze
+
+    def initialize(site, base_directory = nil)
+      @site = site
+      @base_directory = derive_base_directory(
+        @site, base_directory.to_s.dup
+      )
+    end
+
+    def base_directory
+      @base_directory.to_s
+    end
+
+    def derive_base_directory(site, base_dir)
+      base_dir[site.source] = "" if base_dir.start_with?(site.source)
+      base_dir
+    end
+
+    def relative_to_source(entry)
+      File.join(
+        base_directory, entry
+      )
+    end
+
+    def filter(entries)
+      entries.reject do |e|
+        unless included?(e)
+          special?(e) || backup?(e) || excluded?(e) || symlink?(e)
+        end
+      end
+    end
+
+    def included?(entry)
+      glob_include?(site.include, entry) ||
+        glob_include?(site.include, File.basename(entry))
+    end
+
+    def special?(entry)
+      SPECIAL_LEADING_CHARACTERS.include?(entry[0..0]) ||
+        SPECIAL_LEADING_CHARACTERS.include?(File.basename(entry)[0..0])
+    end
+
+    def backup?(entry)
+      entry[-1..-1] == "~"
+    end
+
+    def excluded?(entry)
+      glob_include?(site.exclude, relative_to_source(entry)).tap do |excluded|
+        if excluded
+          Jekyll.logger.debug(
+            "EntryFilter:",
+            "excluded #{relative_to_source(entry)}"
+          )
+        end
+      end
+    end
+
+    # --
+    # Check if a file is a symlink.
+    # NOTE: This can be converted to allowing even in safe,
+    #   since we use Pathutil#in_path? now.
+    # --
+    def symlink?(entry)
+      site.safe && File.symlink?(entry) && symlink_outside_site_source?(entry)
+    end
+
+    # --
+    # NOTE: Pathutil#in_path? gets the realpath.
+    # @param [<Anything>] entry the entry you want to validate.
+    # Check if a path is outside of our given root.
+    # --
+    def symlink_outside_site_source?(entry)
+      !Pathutil.new(entry).in_path?(
+        site.in_source_dir
+      )
+    end
+
+    # --
+    # Check if an entry matches a specific pattern and return true,false.
+    # Returns true if path matches against any glob pattern.
+    # --
+    def glob_include?(enum, e)
+      entry = Pathutil.new(site.in_source_dir).join(e)
+      enum.any? do |exp|
+        # Users who send a Regexp knows what they want to
+        # exclude, so let them send a Regexp to exclude files,
+        # we will not bother caring if it works or not, it's
+        # on them at this point.
+
+        if exp.is_a?(Regexp)
+          entry =~ exp
+
+        else
+          item = Pathutil.new(site.in_source_dir).join(exp)
+
+          # If it's a directory they want to exclude, AKA
+          # ends with a "/" then we will go on to check and
+          # see if the entry falls within that path and
+          # exclude it if that's the case.
+
+          if e.end_with?("/")
+            entry.in_path?(
+              item
+            )
+
+          else
+            File.fnmatch?(item, entry) ||
+              entry.to_path.start_with?(
+                item
+              )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jekyll/errors.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Errors
+    FatalException = Class.new(::RuntimeError)
+
+    InvalidThemeName = Class.new(FatalException)
+
+    DropMutationException       = Class.new(FatalException)
+    InvalidPermalinkError       = Class.new(FatalException)
+    InvalidYAMLFrontMatterError = Class.new(FatalException)
+    MissingDependencyException  = Class.new(FatalException)
+
+    InvalidDateError            = Class.new(FatalException)
+    InvalidPostNameError        = Class.new(FatalException)
+    PostURLError                = Class.new(FatalException)
+    InvalidURLError             = Class.new(FatalException)
+    InvalidConfigurationError   = Class.new(FatalException)
+  end
+end

data/lib/jekyll/excerpt.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Jekyll
+  class Excerpt
+    extend Forwardable
+
+    attr_accessor :doc
+    attr_accessor :content, :ext
+    attr_writer   :output
+
+    def_delegators :@doc, :site, :name, :ext, :relative_path, :extname,
+                          :render_with_liquid?, :collection, :related_posts,
+                          :url, :next_doc, :previous_doc
+
+    # Initialize this Excerpt instance.
+    #
+    # doc - The Document.
+    #
+    # Returns the new Excerpt.
+    def initialize(doc)
+      self.doc = doc
+      self.content = extract_excerpt(doc.content)
+    end
+
+    # Fetch YAML front-matter data from related doc, without layout key
+    #
+    # Returns Hash of doc data
+    def data
+      @data ||= doc.data.dup
+      @data.delete("layout")
+      @data.delete("excerpt")
+      @data
+    end
+
+    def trigger_hooks(*); end
+
+    # 'Path' of the excerpt.
+    #
+    # Returns the path for the doc this excerpt belongs to with #excerpt appended
+    def path
+      File.join(doc.path, "#excerpt")
+    end
+
+    # Check if excerpt includes a string
+    #
+    # Returns true if the string passed in
+    def include?(something)
+      (output && output.include?(something)) || content.include?(something)
+    end
+
+    # The UID for this doc (useful in feeds).
+    # e.g. /2008/11/05/my-awesome-doc
+    #
+    # Returns the String UID.
+    def id
+      "#{doc.id}#excerpt"
+    end
+
+    def to_s
+      output || content
+    end
+
+    def to_liquid
+      Jekyll::Drops::ExcerptDrop.new(self)
+    end
+
+    # Returns the shorthand String identifier of this doc.
+    def inspect
+      "<Excerpt: #{self.id}>"
+    end
+
+    def output
+      @output ||= Renderer.new(doc.site, self, site.site_payload).run
+    end
+
+    def place_in_layout?
+      false
+    end
+
+    protected
+
+    # Internal: Extract excerpt from the content
+    #
+    # By default excerpt is your first paragraph of a doc: everything before
+    # the first two new lines:
+    #
+    #     ---
+    #     title: Example
+    #     ---
+    #
+    #     First paragraph with [link][1].
+    #
+    #     Second paragraph.
+    #
+    #     [1]: http://example.com/
+    #
+    # This is fairly good option for Markdown and Textile files. But might cause
+    # problems for HTML docs (which is quite unusual for Jekyll). If default
+    # excerpt delimiter is not good for you, you might want to set your own via
+    # configuration option `excerpt_separator`. For example, following is a good
+    # alternative for HTML docs:
+    #
+    #     # file: _config.yml
+    #     excerpt_separator: "<!-- more -->"
+    #
+    # Notice that all markdown-style link references will be appended to the
+    # excerpt. So the example doc above will have this excerpt source:
+    #
+    #     First paragraph with [link][1].
+    #
+    #     [1]: http://example.com/
+    #
+    # Excerpts are rendered same time as content is rendered.
+    #
+    # Returns excerpt String
+    def extract_excerpt(doc_content)
+      head, _, tail = doc_content.to_s.partition(doc.excerpt_separator)
+
+      if tail.empty?
+        head
+      else
+        head.to_s.dup << "\n\n" << tail.scan(%r!^ {0,3}\[[^\]]+\]:.+$!).join("\n")
+      end
+    end
+  end
+end

data/lib/jekyll/external.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module External
+    class << self
+      #
+      # Gems that, if installed, should be loaded.
+      # Usually contain subcommands.
+      #
+      def blessed_gems
+        %w(
+          jekyll-docs
+          jekyll-import
+        )
+      end
+
+      #
+      # Require a gem or file if it's present, otherwise silently fail.
+      #
+      # names - a string gem name or array of gem names
+      #
+      def require_if_present(names)
+        Array(names).each do |name|
+          begin
+            require name
+          rescue LoadError
+            Jekyll.logger.debug "Couldn't load #{name}. Skipping."
+            yield(name, version_constraint(name)) if block_given?
+            false
+          end
+        end
+      end
+
+      #
+      # The version constraint required to activate a given gem.
+      # Usually the gem version requirement is "> 0," because any version
+      # will do. In the case of jekyll-docs, however, we require the exact
+      # same version as Jekyll.
+      #
+      # Returns a String version constraint in a parseable form for
+      # RubyGems.
+      def version_constraint(gem_name)
+        return "= #{Jekyll::VERSION}" if gem_name.to_s.eql?("jekyll-docs")
+        "> 0"
+      end
+
+      #
+      # Require a gem or gems. If it's not present, show a very nice error
+      # message that explains everything and is much more helpful than the
+      # normal LoadError.
+      #
+      # names - a string gem name or array of gem names
+      #
+      def require_with_graceful_fail(names)
+        Array(names).each do |name|
+          begin
+            Jekyll.logger.debug "Requiring:", name.to_s
+            require name
+          rescue LoadError => e
+            Jekyll.logger.error "Dependency Error:", <<-MSG
+Yikes! It looks like you don't have #{name} or one of its dependencies installed.
+In order to use Jekyll as currently configured, you'll need to install this gem.
+
+The full error message from Ruby is: '#{e.message}'
+
+If you run into trouble, you can find helpful resources at https://jekyllrb.com/help/!
+            MSG
+            raise Jekyll::Errors::MissingDependencyException, name
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jekyll/filters.rb

@@ -0,0 +1,430 @@
+# frozen_string_literal: true
+
+require "addressable/uri"
+require "json"
+require "date"
+require "liquid"
+
+require_all "jekyll/filters"
+
+module Jekyll
+  module Filters
+    include URLFilters
+    include GroupingFilters
+
+    # Convert a Markdown string into HTML output.
+    #
+    # input - The Markdown String to convert.
+    #
+    # Returns the HTML formatted String.
+    def markdownify(input)
+      site = @context.registers[:site]
+      converter = site.find_converter_instance(Jekyll::Converters::Markdown)
+      converter.convert(input.to_s)
+    end
+
+    # Convert quotes into smart quotes.
+    #
+    # input - The String to convert.
+    #
+    # Returns the smart-quotified String.
+    def smartify(input)
+      site = @context.registers[:site]
+      converter = site.find_converter_instance(Jekyll::Converters::SmartyPants)
+      converter.convert(input.to_s)
+    end
+
+    # Convert a Sass string into CSS output.
+    #
+    # input - The Sass String to convert.
+    #
+    # Returns the CSS formatted String.
+    def sassify(input)
+      site = @context.registers[:site]
+      converter = site.find_converter_instance(Jekyll::Converters::Sass)
+      converter.convert(input)
+    end
+
+    # Convert a Scss string into CSS output.
+    #
+    # input - The Scss String to convert.
+    #
+    # Returns the CSS formatted String.
+    def scssify(input)
+      site = @context.registers[:site]
+      converter = site.find_converter_instance(Jekyll::Converters::Scss)
+      converter.convert(input)
+    end
+
+    # Slugify a filename or title.
+    #
+    # input - The filename or title to slugify.
+    # mode - how string is slugified
+    #
+    # Returns the given filename or title as a lowercase URL String.
+    # See Utils.slugify for more detail.
+    def slugify(input, mode = nil)
+      Utils.slugify(input, :mode => mode)
+    end
+
+    # Format a date in short format e.g. "27 Jan 2011".
+    #
+    # date - the Time to format.
+    #
+    # Returns the formatting String.
+    def date_to_string(date)
+      time(date).strftime("%d %b %Y")
+    end
+
+    # Format a date in long format e.g. "27 January 2011".
+    #
+    # date - The Time to format.
+    #
+    # Returns the formatted String.
+    def date_to_long_string(date)
+      return date if date.to_s.empty?
+      time(date).strftime("%d %B %Y")
+    end
+
+    # Format a date for use in XML.
+    #
+    # date - The Time to format.
+    #
+    # Examples
+    #
+    #   date_to_xmlschema(Time.now)
+    #   # => "2011-04-24T20:34:46+08:00"
+    #
+    # Returns the formatted String.
+    def date_to_xmlschema(date)
+      return date if date.to_s.empty?
+      time(date).xmlschema
+    end
+
+    # Format a date according to RFC-822
+    #
+    # date - The Time to format.
+    #
+    # Examples
+    #
+    #   date_to_rfc822(Time.now)
+    #   # => "Sun, 24 Apr 2011 12:34:46 +0000"
+    #
+    # Returns the formatted String.
+    def date_to_rfc822(date)
+      return date if date.to_s.empty?
+      time(date).rfc822
+    end
+
+    # XML escape a string for use. Replaces any special characters with
+    # appropriate HTML entity replacements.
+    #
+    # input - The String to escape.
+    #
+    # Examples
+    #
+    #   xml_escape('foo "bar" <baz>')
+    #   # => "foo &quot;bar&quot; &lt;baz&gt;"
+    #
+    # Returns the escaped String.
+    def xml_escape(input)
+      input.to_s.encode(:xml => :attr).gsub(%r!\A"|"\Z!, "")
+    end
+
+    # CGI escape a string for use in a URL. Replaces any special characters
+    # with appropriate %XX replacements.
+    #
+    # input - The String to escape.
+    #
+    # Examples
+    #
+    #   cgi_escape('foo,bar;baz?')
+    #   # => "foo%2Cbar%3Bbaz%3F"
+    #
+    # Returns the escaped String.
+    def cgi_escape(input)
+      CGI.escape(input)
+    end
+
+    # URI escape a string.
+    #
+    # input - The String to escape.
+    #
+    # Examples
+    #
+    #   uri_escape('foo, bar \\baz?')
+    #   # => "foo,%20bar%20%5Cbaz?"
+    #
+    # Returns the escaped String.
+    def uri_escape(input)
+      Addressable::URI.normalize_component(input)
+    end
+
+    # Replace any whitespace in the input string with a single space
+    #
+    # input - The String on which to operate.
+    #
+    # Returns the formatted String
+    def normalize_whitespace(input)
+      input.to_s.gsub(%r!\s+!, " ").strip
+    end
+
+    # Count the number of words in the input string.
+    #
+    # input - The String on which to operate.
+    #
+    # Returns the Integer word count.
+    def number_of_words(input)
+      input.split.length
+    end
+
+    # Join an array of things into a string by separating with commas and the
+    # word "and" for the last one.
+    #
+    # array - The Array of Strings to join.
+    # connector - Word used to connect the last 2 items in the array
+    #
+    # Examples
+    #
+    #   array_to_sentence_string(["apples", "oranges", "grapes"])
+    #   # => "apples, oranges, and grapes"
+    #
+    # Returns the formatted String.
+    def array_to_sentence_string(array, connector = "and")
+      case array.length
+      when 0
+        ""
+      when 1
+        array[0].to_s
+      when 2
+        "#{array[0]} #{connector} #{array[1]}"
+      else
+        "#{array[0...-1].join(", ")}, #{connector} #{array[-1]}"
+      end
+    end
+
+    # Convert the input into json string
+    #
+    # input - The Array or Hash to be converted
+    #
+    # Returns the converted json string
+    def jsonify(input)
+      as_liquid(input).to_json
+    end
+
+    # Filter an array of objects
+    #
+    # input - the object array
+    # property - property within each object to filter by
+    # value - desired value
+    #
+    # Returns the filtered array of objects
+    def where(input, property, value)
+      return input unless input.respond_to?(:select)
+      input = input.values if input.is_a?(Hash)
+      input.select do |object|
+        Array(item_property(object, property)).map(&:to_s).include?(value.to_s)
+      end || []
+    end
+
+    # Filters an array of objects against an expression
+    #
+    # input - the object array
+    # variable - the variable to assign each item to in the expression
+    # expression - a Liquid comparison expression passed in as a string
+    #
+    # Returns the filtered array of objects
+    def where_exp(input, variable, expression)
+      return input unless input.respond_to?(:select)
+      input = input.values if input.is_a?(Hash) # FIXME
+
+      condition = parse_condition(expression)
+      @context.stack do
+        input.select do |object|
+          @context[variable] = object
+          condition.evaluate(@context)
+        end
+      end || []
+    end
+
+    # Convert the input into integer
+    #
+    # input - the object string
+    #
+    # Returns the integer value
+    def to_integer(input)
+      return 1 if input == true
+      return 0 if input == false
+      input.to_i
+    end
+
+    # Sort an array of objects
+    #
+    # input - the object array
+    # property - property within each object to filter by
+    # nils ('first' | 'last') - nils appear before or after non-nil values
+    #
+    # Returns the filtered array of objects
+    def sort(input, property = nil, nils = "first")
+      if input.nil?
+        raise ArgumentError, "Cannot sort a null object."
+      end
+      if property.nil?
+        input.sort
+      else
+        if nils == "first"
+          order = - 1
+        elsif nils == "last"
+          order = + 1
+        else
+          raise ArgumentError, "Invalid nils order: " \
+            "'#{nils}' is not a valid nils order. It must be 'first' or 'last'."
+        end
+
+        sort_input(input, property, order)
+      end
+    end
+
+    def pop(array, num = 1)
+      return array unless array.is_a?(Array)
+      num = Liquid::Utils.to_integer(num)
+      new_ary = array.dup
+      new_ary.pop(num)
+      new_ary
+    end
+
+    def push(array, input)
+      return array unless array.is_a?(Array)
+      new_ary = array.dup
+      new_ary.push(input)
+      new_ary
+    end
+
+    def shift(array, num = 1)
+      return array unless array.is_a?(Array)
+      num = Liquid::Utils.to_integer(num)
+      new_ary = array.dup
+      new_ary.shift(num)
+      new_ary
+    end
+
+    def unshift(array, input)
+      return array unless array.is_a?(Array)
+      new_ary = array.dup
+      new_ary.unshift(input)
+      new_ary
+    end
+
+    def sample(input, num = 1)
+      return input unless input.respond_to?(:sample)
+      num = Liquid::Utils.to_integer(num) rescue 1
+      if num == 1
+        input.sample
+      else
+        input.sample(num)
+      end
+    end
+
+    # Convert an object into its String representation for debugging
+    #
+    # input - The Object to be converted
+    #
+    # Returns a String representation of the object.
+    def inspect(input)
+      xml_escape(input.inspect)
+    end
+
+    private
+
+    # Sort the input Enumerable by the given property.
+    # If the property doesn't exist, return the sort order respective of
+    # which item doesn't have the property.
+    # We also utilize the Schwartzian transform to make this more efficient.
+    def sort_input(input, property, order)
+      input.map { |item| [item_property(item, property), item] }
+        .sort! do |apple_info, orange_info|
+          apple_property = apple_info.first
+          orange_property = orange_info.first
+
+          if !apple_property.nil? && orange_property.nil?
+            - order
+          elsif apple_property.nil? && !orange_property.nil?
+            + order
+          else
+            apple_property <=> orange_property
+          end
+        end
+        .map!(&:last)
+    end
+
+    private
+    def time(input)
+      date = Liquid::Utils.to_date(input)
+      unless date.respond_to?(:to_time)
+        raise Errors::InvalidDateError,
+          "Invalid Date: '#{input.inspect}' is not a valid datetime."
+      end
+      date.to_time.dup.localtime
+    end
+
+    private
+    def item_property(item, property)
+      if item.respond_to?(:to_liquid)
+        property.to_s.split(".").reduce(item.to_liquid) do |subvalue, attribute|
+          subvalue[attribute]
+        end
+      elsif item.respond_to?(:data)
+        item.data[property.to_s]
+      else
+        item[property.to_s]
+      end
+    end
+
+    private
+    def as_liquid(item)
+      case item
+      when Hash
+        pairs = item.map { |k, v| as_liquid([k, v]) }
+        Hash[pairs]
+      when Array
+        item.map { |i| as_liquid(i) }
+      else
+        if item.respond_to?(:to_liquid)
+          liquidated = item.to_liquid
+          # prevent infinite recursion for simple types (which return `self`)
+          if liquidated == item
+            item
+          else
+            as_liquid(liquidated)
+          end
+        else
+          item
+        end
+      end
+    end
+
+    # Parse a string to a Liquid Condition
+    private
+    def parse_condition(exp)
+      parser = Liquid::Parser.new(exp)
+      left_expr = parser.expression
+      operator = parser.consume?(:comparison)
+      condition =
+        if operator
+          Liquid::Condition.new(Liquid::Expression.parse(left_expr),
+                                operator,
+                                Liquid::Expression.parse(parser.expression))
+        else
+          Liquid::Condition.new(Liquid::Expression.parse(left_expr))
+        end
+      parser.consume(:end_of_string)
+
+      condition
+    end
+
+  end
+end
+
+Liquid::Template.register_filter(
+  Jekyll::Filters
+)