jekyll-docs 3.6.0 → 3.6.1

data/lib/jekyll/page.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Jekyll
+  class Page
+    include Convertible
+
+    attr_writer :dir
+    attr_accessor :site, :pager
+    attr_accessor :name, :ext, :basename
+    attr_accessor :data, :content, :output
+
+    alias_method :extname, :ext
+
+    FORWARD_SLASH = "/".freeze
+
+    # Attributes for Liquid templates
+    ATTRIBUTES_FOR_LIQUID = %w(
+      content
+      dir
+      name
+      path
+      url
+    ).freeze
+
+    # A set of extensions that are considered HTML or HTML-like so we
+    # should not alter them,  this includes .xhtml through XHTM5.
+
+    HTML_EXTENSIONS = %w(
+      .html
+      .xhtml
+      .htm
+    ).freeze
+
+    # Initialize a new Page.
+    #
+    # site - The Site object.
+    # base - The String path to the source.
+    # dir  - The String path between the source and the file.
+    # name - The String filename of the file.
+    def initialize(site, base, dir, name)
+      @site = site
+      @base = base
+      @dir  = dir
+      @name = name
+      @path = if site.in_theme_dir(base) == base # we're in a theme
+                site.in_theme_dir(base, dir, name)
+              else
+                site.in_source_dir(base, dir, name)
+              end
+
+      process(name)
+      read_yaml(File.join(base, dir), name)
+
+      data.default_proc = proc do |_, key|
+        site.frontmatter_defaults.find(File.join(dir, name), type, key)
+      end
+
+      Jekyll::Hooks.trigger :pages, :post_init, self
+    end
+
+    # The generated directory into which the page will be placed
+    # upon generation. This is derived from the permalink or, if
+    # permalink is absent, will be '/'
+    #
+    # Returns the String destination directory.
+    def dir
+      if url.end_with?(FORWARD_SLASH)
+        url
+      else
+        url_dir = File.dirname(url)
+        url_dir.end_with?(FORWARD_SLASH) ? url_dir : "#{url_dir}/"
+      end
+    end
+
+    # The full path and filename of the post. Defined in the YAML of the post
+    # body.
+    #
+    # Returns the String permalink or nil if none has been set.
+    def permalink
+      data.nil? ? nil : data["permalink"]
+    end
+
+    # The template of the permalink.
+    #
+    # Returns the template String.
+    def template
+      if !html?
+        "/:path/:basename:output_ext"
+      elsif index?
+        "/:path/"
+      else
+        Utils.add_permalink_suffix("/:path/:basename", site.permalink_style)
+      end
+    end
+
+    # The generated relative url of this page. e.g. /about.html.
+    #
+    # Returns the String url.
+    def url
+      @url ||= URL.new({
+        :template     => template,
+        :placeholders => url_placeholders,
+        :permalink    => permalink,
+      }).to_s
+    end
+
+    # Returns a hash of URL placeholder names (as symbols) mapping to the
+    # desired placeholder replacements. For details see "url.rb"
+    def url_placeholders
+      {
+        :path       => @dir,
+        :basename   => basename,
+        :output_ext => output_ext,
+      }
+    end
+
+    # Extract information from the page filename.
+    #
+    # name - The String filename of the page file.
+    #
+    # Returns nothing.
+    def process(name)
+      self.ext = File.extname(name)
+      self.basename = name[0..-ext.length - 1]
+    end
+
+    # Add any necessary layouts to this post
+    #
+    # layouts      - The Hash of {"name" => "layout"}.
+    # site_payload - The site payload Hash.
+    #
+    # Returns String rendered page.
+    def render(layouts, site_payload)
+      site_payload["page"] = to_liquid
+      site_payload["paginator"] = pager.to_liquid
+
+      do_layout(site_payload, layouts)
+    end
+
+    # The path to the source file
+    #
+    # Returns the path to the source file
+    def path
+      data.fetch("path") { relative_path }
+    end
+
+    # The path to the page source file, relative to the site source
+    def relative_path
+      File.join(*[@dir, @name].map(&:to_s).reject(&:empty?)).sub(%r!\A\/!, "")
+    end
+
+    # Obtain destination path.
+    #
+    # dest - The String path to the destination dir.
+    #
+    # Returns the destination file path String.
+    def destination(dest)
+      path = site.in_dest_dir(dest, URL.unescape_path(url))
+      path = File.join(path, "index") if url.end_with?("/")
+      path << output_ext unless path.end_with? output_ext
+      path
+    end
+
+    # Returns the object as a debug String.
+    def inspect
+      "#<Jekyll:Page @name=#{name.inspect}>"
+    end
+
+    # Returns the Boolean of whether this Page is HTML or not.
+    def html?
+      HTML_EXTENSIONS.include?(output_ext)
+    end
+
+    # Returns the Boolean of whether this Page is an index file or not.
+    def index?
+      basename == "index"
+    end
+
+    def trigger_hooks(hook_name, *args)
+      Jekyll::Hooks.trigger :pages, hook_name, self, *args
+    end
+
+    def write?
+      true
+    end
+  end
+end

data/lib/jekyll/plugin.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Jekyll
+  class Plugin
+    PRIORITIES = {
+      :low     => -10,
+      :highest => 100,
+      :lowest  => -100,
+      :normal  => 0,
+      :high    => 10,
+    }.freeze
+
+    #
+
+    def self.inherited(const)
+      return catch_inheritance(const) do |const_|
+        catch_inheritance(const_)
+      end
+    end
+
+    #
+
+    def self.catch_inheritance(const)
+      const.define_singleton_method :inherited do |const_|
+        (@children ||= Set.new).add const_
+        if block_given?
+          yield const_
+        end
+      end
+    end
+
+    #
+
+    def self.descendants
+      @children ||= Set.new
+      out = @children.map(&:descendants)
+      out << self unless superclass == Plugin
+      Set.new(out).flatten
+    end
+
+    # Get or set the priority of this plugin. When called without an
+    # argument it returns the priority. When an argument is given, it will
+    # set the priority.
+    #
+    # priority - The Symbol priority (default: nil). Valid options are:
+    #            :lowest, :low, :normal, :high, :highest
+    #
+    # Returns the Symbol priority.
+    def self.priority(priority = nil)
+      @priority ||= nil
+      if priority && PRIORITIES.key?(priority)
+        @priority = priority
+      end
+      @priority || :normal
+    end
+
+    # Get or set the safety of this plugin. When called without an argument
+    # it returns the safety. When an argument is given, it will set the
+    # safety.
+    #
+    # safe - The Boolean safety (default: nil).
+    #
+    # Returns the safety Boolean.
+    def self.safe(safe = nil)
+      unless defined?(@safe) && safe.nil?
+        @safe = safe
+      end
+      @safe || false
+    end
+
+    # Spaceship is priority [higher -> lower]
+    #
+    # other - The class to be compared.
+    #
+    # Returns -1, 0, 1.
+    def self.<=>(other)
+      PRIORITIES[other.priority] <=> PRIORITIES[self.priority]
+    end
+
+    # Spaceship is priority [higher -> lower]
+    #
+    # other - The class to be compared.
+    #
+    # Returns -1, 0, 1.
+    def <=>(other)
+      self.class <=> other.class
+    end
+
+    # Initialize a new plugin. This should be overridden by the subclass.
+    #
+    # config - The Hash of configuration options.
+    #
+    # Returns a new instance.
+    def initialize(config = {})
+      # no-op for default
+    end
+  end
+end

data/lib/jekyll/plugin_manager.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Jekyll
+  class PluginManager
+    attr_reader :site
+
+    # Create an instance of this class.
+    #
+    # site - the instance of Jekyll::Site we're concerned with
+    #
+    # Returns nothing
+    def initialize(site)
+      @site = site
+    end
+
+    # Require all the plugins which are allowed.
+    #
+    # Returns nothing
+    def conscientious_require
+      require_theme_deps if site.theme
+      require_plugin_files
+      require_gems
+      deprecation_checks
+    end
+
+    # Require each of the gem plugins specified.
+    #
+    # Returns nothing.
+    def require_gems
+      Jekyll::External.require_with_graceful_fail(
+        site.gems.select { |plugin| plugin_allowed?(plugin) }
+      )
+    end
+
+    # Require each of the runtime_dependencies specified by the theme's gemspec.
+    #
+    # Returns false only if no dependencies have been specified, otherwise nothing.
+    def require_theme_deps
+      return false unless site.theme.runtime_dependencies
+      site.theme.runtime_dependencies.each do |dep|
+        next if dep.name == "jekyll"
+        External.require_with_graceful_fail(dep.name) if plugin_allowed?(dep.name)
+      end
+    end
+
+    def self.require_from_bundler
+      if !ENV["JEKYLL_NO_BUNDLER_REQUIRE"] && File.file?("Gemfile")
+        require "bundler"
+
+        Bundler.setup
+        required_gems = Bundler.require(:jekyll_plugins)
+        message = "Required #{required_gems.map(&:name).join(", ")}"
+        Jekyll.logger.debug("PluginManager:", message)
+        ENV["JEKYLL_NO_BUNDLER_REQUIRE"] = "true"
+
+        true
+      else
+        false
+      end
+    end
+
+    # Check whether a gem plugin is allowed to be used during this build.
+    #
+    # plugin_name - the name of the plugin
+    #
+    # Returns true if the plugin name is in the whitelist or if the site is not
+    #   in safe mode.
+    def plugin_allowed?(plugin_name)
+      !site.safe || whitelist.include?(plugin_name)
+    end
+
+    # Build an array of allowed plugin gem names.
+    #
+    # Returns an array of strings, each string being the name of a gem name
+    #   that is allowed to be used.
+    def whitelist
+      @whitelist ||= Array[site.config["whitelist"]].flatten
+    end
+
+    # Require all .rb files if safe mode is off
+    #
+    # Returns nothing.
+    def require_plugin_files
+      unless site.safe
+        plugins_path.each do |plugin_search_path|
+          plugin_files = Utils.safe_glob(plugin_search_path, File.join("**", "*.rb"))
+          Jekyll::External.require_with_graceful_fail(plugin_files)
+        end
+      end
+    end
+
+    # Public: Setup the plugin search path
+    #
+    # Returns an Array of plugin search paths
+    def plugins_path
+      if site.config["plugins_dir"].eql? Jekyll::Configuration::DEFAULTS["plugins_dir"]
+        [site.in_source_dir(site.config["plugins_dir"])]
+      else
+        Array(site.config["plugins_dir"]).map { |d| File.expand_path(d) }
+      end
+    end
+
+    def deprecation_checks
+      pagination_included = (site.config["plugins"] || []).include?("jekyll-paginate") ||
+        defined?(Jekyll::Paginate)
+      if site.config["paginate"] && !pagination_included
+        Jekyll::Deprecator.deprecation_message "You appear to have pagination " \
+          "turned on, but you haven't included the `jekyll-paginate` gem. " \
+          "Ensure you have `plugins: [jekyll-paginate]` in your configuration file."
+      end
+    end
+  end
+end

data/lib/jekyll/publisher.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Jekyll
+  class Publisher
+    def initialize(site)
+      @site = site
+    end
+
+    def publish?(thing)
+      can_be_published?(thing) && !hidden_in_the_future?(thing)
+    end
+
+    def hidden_in_the_future?(thing)
+      thing.respond_to?(:date) && !@site.future && thing.date.to_i > @site.time.to_i
+    end
+
+    private
+
+    def can_be_published?(thing)
+      thing.data.fetch("published", true) || @site.unpublished
+    end
+  end
+end

data/lib/jekyll/reader.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "csv"
+
+module Jekyll
+  class Reader
+    attr_reader :site
+
+    def initialize(site)
+      @site = site
+    end
+
+    # Read Site data from disk and load it into internal data structures.
+    #
+    # Returns nothing.
+    def read
+      @site.layouts = LayoutReader.new(site).read
+      read_directories
+      sort_files!
+      @site.data = DataReader.new(site).read(site.config["data_dir"])
+      CollectionReader.new(site).read
+      ThemeAssetsReader.new(site).read
+    end
+
+    # Sorts posts, pages, and static files.
+    def sort_files!
+      site.collections.each_value { |c| c.docs.sort! }
+      site.pages.sort_by!(&:name)
+      site.static_files.sort_by!(&:relative_path)
+    end
+
+    # Recursively traverse directories to find pages and static files
+    # that will become part of the site according to the rules in
+    # filter_entries.
+    #
+    # dir - The String relative path of the directory to read. Default: ''.
+    #
+    # Returns nothing.
+    def read_directories(dir = "")
+      base = site.in_source_dir(dir)
+
+      return unless File.directory?(base)
+
+      dot = Dir.chdir(base) { filter_entries(Dir.entries("."), base) }
+      dot_dirs = dot.select { |file| File.directory?(@site.in_source_dir(base, file)) }
+      dot_files = (dot - dot_dirs)
+      dot_pages = dot_files.select do |file|
+        Utils.has_yaml_header?(@site.in_source_dir(base, file))
+      end
+      dot_static_files = dot_files - dot_pages
+
+      retrieve_posts(dir)
+      retrieve_dirs(base, dir, dot_dirs)
+      retrieve_pages(dir, dot_pages)
+      retrieve_static_files(dir, dot_static_files)
+    end
+
+    # Retrieves all the posts(posts/drafts) from the given directory
+    # and add them to the site and sort them.
+    #
+    # dir - The String representing the directory to retrieve the posts from.
+    #
+    # Returns nothing.
+    def retrieve_posts(dir)
+      site.posts.docs.concat(PostReader.new(site).read_posts(dir))
+      site.posts.docs.concat(PostReader.new(site).read_drafts(dir)) if site.show_drafts
+    end
+
+    # Recursively traverse directories with the read_directories function.
+    #
+    # base - The String representing the site's base directory.
+    # dir - The String representing the directory to traverse down.
+    # dot_dirs - The Array of subdirectories in the dir.
+    #
+    # Returns nothing.
+    def retrieve_dirs(_base, dir, dot_dirs)
+      dot_dirs.each do |file|
+        dir_path = site.in_source_dir(dir, file)
+        rel_path = File.join(dir, file)
+        unless @site.dest.sub(%r!/$!, "") == dir_path
+          @site.reader.read_directories(rel_path)
+        end
+      end
+    end
+
+    # Retrieve all the pages from the current directory,
+    # add them to the site and sort them.
+    #
+    # dir - The String representing the directory retrieve the pages from.
+    # dot_pages - The Array of pages in the dir.
+    #
+    # Returns nothing.
+    def retrieve_pages(dir, dot_pages)
+      site.pages.concat(PageReader.new(site, dir).read(dot_pages))
+    end
+
+    # Retrieve all the static files from the current directory,
+    # add them to the site and sort them.
+    #
+    # dir - The directory retrieve the static files from.
+    # dot_static_files - The static files in the dir.
+    #
+    # Returns nothing.
+    def retrieve_static_files(dir, dot_static_files)
+      site.static_files.concat(StaticFileReader.new(site, dir).read(dot_static_files))
+    end
+
+    # Filter out any files/directories that are hidden or backup files (start
+    # with "." or "#" or end with "~"), or contain site content (start with "_"),
+    # or are excluded in the site configuration, unless they are web server
+    # files such as '.htaccess'.
+    #
+    # entries - The Array of String file/directory entries to filter.
+    # base_directory - The string representing the optional base directory.
+    #
+    # Returns the Array of filtered entries.
+    def filter_entries(entries, base_directory = nil)
+      EntryFilter.new(site, base_directory).filter(entries)
+    end
+
+    # Read the entries from a particular directory for processing
+    #
+    # dir - The String representing the relative path of the directory to read.
+    # subfolder - The String representing the directory to read.
+    #
+    # Returns the list of entries to process
+    def get_entries(dir, subfolder)
+      base = site.in_source_dir(dir, subfolder)
+      return [] unless File.exist?(base)
+      entries = Dir.chdir(base) { filter_entries(Dir["**/*"], base) }
+      entries.delete_if { |e| File.directory?(site.in_source_dir(base, e)) }
+    end
+  end
+end