jekyll-docs 3.6.0 → 3.6.1

data/lib/jekyll/converter.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Jekyll
+  class Converter < Plugin
+    # Public: Get or set the highlighter prefix. When an argument is specified,
+    # the prefix will be set. If no argument is specified, the current prefix
+    # will be returned.
+    #
+    # highlighter_prefix - The String prefix (default: nil).
+    #
+    # Returns the String prefix.
+    def self.highlighter_prefix(highlighter_prefix = nil)
+      unless defined?(@highlighter_prefix) && highlighter_prefix.nil?
+        @highlighter_prefix = highlighter_prefix
+      end
+      @highlighter_prefix
+    end
+
+    # Public: Get or set the highlighter suffix. When an argument is specified,
+    # the suffix will be set. If no argument is specified, the current suffix
+    # will be returned.
+    #
+    # highlighter_suffix - The String suffix (default: nil).
+    #
+    # Returns the String suffix.
+    def self.highlighter_suffix(highlighter_suffix = nil)
+      unless defined?(@highlighter_suffix) && highlighter_suffix.nil?
+        @highlighter_suffix = highlighter_suffix
+      end
+      @highlighter_suffix
+    end
+
+    # Initialize the converter.
+    #
+    # Returns an initialized Converter.
+    def initialize(config = {})
+      @config = config
+    end
+
+    # Get the highlighter prefix.
+    #
+    # Returns the String prefix.
+    def highlighter_prefix
+      self.class.highlighter_prefix
+    end
+
+    # Get the highlighter suffix.
+    #
+    # Returns the String suffix.
+    def highlighter_suffix
+      self.class.highlighter_suffix
+    end
+  end
+end

data/lib/jekyll/converters/identity.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Converters
+    class Identity < Converter
+      safe true
+
+      priority :lowest
+
+      def matches(_ext)
+        true
+      end
+
+      def output_ext(ext)
+        ext
+      end
+
+      def convert(content)
+        content
+      end
+    end
+  end
+end

data/lib/jekyll/converters/markdown.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Converters
+    class Markdown < Converter
+      highlighter_prefix "\n"
+      highlighter_suffix "\n"
+      safe true
+
+      def setup
+        return if @setup ||= false
+        unless (@parser = get_processor)
+          Jekyll.logger.error "Invalid Markdown processor given:", @config["markdown"]
+          if @config["safe"]
+            Jekyll.logger.info "", "Custom processors are not loaded in safe mode"
+          end
+          Jekyll.logger.error(
+            "",
+            "Available processors are: #{valid_processors.join(", ")}"
+          )
+          raise Errors::FatalException, "Bailing out; invalid Markdown processor."
+        end
+
+        @setup = true
+      end
+
+      # Rubocop does not allow reader methods to have names starting with `get_`
+      # To ensure compatibility, this check has been disabled on this method
+      #
+      # rubocop:disable Naming/AccessorMethodName
+      def get_processor
+        case @config["markdown"].downcase
+        when "redcarpet" then return RedcarpetParser.new(@config)
+        when "kramdown"  then return KramdownParser.new(@config)
+        when "rdiscount" then return RDiscountParser.new(@config)
+        else
+          custom_processor
+        end
+      end
+      # rubocop:enable Naming/AccessorMethodName
+
+      # Public: Provides you with a list of processors, the ones we
+      # support internally and the ones that you have provided to us (if you
+      # are not in safe mode.)
+
+      def valid_processors
+        %W(rdiscount kramdown redcarpet) + third_party_processors
+      end
+
+      # Public: A list of processors that you provide via plugins.
+      # This is really only available if you are not in safe mode, if you are
+      # in safe mode (re: GitHub) then there will be none.
+
+      def third_party_processors
+        self.class.constants - \
+          %w(KramdownParser RDiscountParser RedcarpetParser PRIORITIES).map(
+            &:to_sym
+          )
+      end
+
+      def extname_list
+        @extname_list ||= @config["markdown_ext"].split(",").map do |e|
+          ".#{e.downcase}"
+        end
+      end
+
+      def matches(ext)
+        extname_list.include?(ext.downcase)
+      end
+
+      def output_ext(_ext)
+        ".html"
+      end
+
+      def convert(content)
+        setup
+        @parser.convert(content)
+      end
+
+      private
+      def custom_processor
+        converter_name = @config["markdown"]
+        if custom_class_allowed?(converter_name)
+          self.class.const_get(converter_name).new(@config)
+        end
+      end
+
+      # Private: Determine whether a class name is an allowed custom
+      #   markdown class name.
+      #
+      # parser_name - the name of the parser class
+      #
+      # Returns true if the parser name contains only alphanumeric
+      # characters and is defined within Jekyll::Converters::Markdown
+
+      private
+      def custom_class_allowed?(parser_name)
+        parser_name !~ %r![^A-Za-z0-9_]! && self.class.constants.include?(
+          parser_name.to_sym
+        )
+      end
+    end
+  end
+end

data/lib/jekyll/converters/markdown/kramdown_parser.rb

@@ -0,0 +1,123 @@
+# Frozen-string-literal: true
+# Encoding: utf-8
+
+module Jekyll
+  module Converters
+    class Markdown
+      class KramdownParser
+        CODERAY_DEFAULTS = {
+          "css"               => "style",
+          "bold_every"        => 10,
+          "line_numbers"      => "inline",
+          "line_number_start" => 1,
+          "tab_width"         => 4,
+          "wrap"              => "div",
+        }.freeze
+
+        def initialize(config)
+          Jekyll::External.require_with_graceful_fail "kramdown"
+          @main_fallback_highlighter = config["highlighter"] || "rouge"
+          @config = config["kramdown"] || {}
+          @highlighter = nil
+          setup
+        end
+
+        # Setup and normalize the configuration:
+        #   * Create Kramdown if it doesn't exist.
+        #   * Set syntax_highlighter, detecting enable_coderay and merging
+        #       highlighter if none.
+        #   * Merge kramdown[coderay] into syntax_highlighter_opts stripping coderay_.
+        #   * Make sure `syntax_highlighter_opts` exists.
+
+        def setup
+          @config["syntax_highlighter"] ||= highlighter
+          @config["syntax_highlighter_opts"] ||= {}
+          @config["coderay"] ||= {} # XXX: Legacy.
+          modernize_coderay_config
+          make_accessible
+        end
+
+        def convert(content)
+          Kramdown::Document.new(content, @config).to_html
+        end
+
+        private
+        # rubocop:disable Performance/HashEachMethods
+        def make_accessible(hash = @config)
+          hash.keys.each do |key|
+            hash[key.to_sym] = hash[key]
+            make_accessible(hash[key]) if hash[key].is_a?(Hash)
+          end
+        end
+        # rubocop:enable Performance/HashEachMethods
+
+        # config[kramdown][syntax_higlighter] >
+        #   config[kramdown][enable_coderay] >
+        #   config[highlighter]
+        # Where `enable_coderay` is now deprecated because Kramdown
+        # supports Rouge now too.
+
+        private
+        def highlighter
+          return @highlighter if @highlighter
+
+          if @config["syntax_highlighter"]
+            return @highlighter = @config[
+              "syntax_highlighter"
+            ]
+          end
+
+          @highlighter = begin
+            if @config.key?("enable_coderay") && @config["enable_coderay"]
+              Jekyll::Deprecator.deprecation_message(
+                "You are using 'enable_coderay', " \
+                "use syntax_highlighter: coderay in your configuration file."
+              )
+
+              "coderay"
+            else
+              @main_fallback_highlighter
+            end
+          end
+        end
+
+        private
+        def strip_coderay_prefix(hash)
+          hash.each_with_object({}) do |(key, val), hsh|
+            cleaned_key = key.to_s.gsub(%r!\Acoderay_!, "")
+
+            if key != cleaned_key
+              Jekyll::Deprecator.deprecation_message(
+                "You are using '#{key}'. Normalizing to #{cleaned_key}."
+              )
+            end
+
+            hsh[cleaned_key] = val
+          end
+        end
+
+        # If our highlighter is CodeRay we go in to merge the CodeRay defaults
+        # with your "coderay" key if it's there, deprecating it in the
+        # process of you using it.
+
+        private
+        def modernize_coderay_config
+          unless @config["coderay"].empty?
+            Jekyll::Deprecator.deprecation_message(
+              "You are using 'kramdown.coderay' in your configuration, " \
+              "please use 'syntax_highlighter_opts' instead."
+            )
+
+            @config["syntax_highlighter_opts"] = begin
+              strip_coderay_prefix(
+                @config["syntax_highlighter_opts"] \
+                  .merge(CODERAY_DEFAULTS) \
+                  .merge(@config["coderay"])
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jekyll/converters/markdown/rdiscount_parser.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Converters
+    class Markdown
+      class RDiscountParser
+        def initialize(config)
+          Jekyll::External.require_with_graceful_fail "rdiscount"
+          @config = config
+          @rdiscount_extensions = @config["rdiscount"]["extensions"].map(&:to_sym)
+        end
+
+        def convert(content)
+          rd = RDiscount.new(content, *@rdiscount_extensions)
+          html = rd.to_html
+          if @config["rdiscount"]["toc_token"]
+            html = replace_generated_toc(rd, html, @config["rdiscount"]["toc_token"])
+          end
+          html
+        end
+
+        private
+        def replace_generated_toc(rd, html, toc_token)
+          if rd.generate_toc && html.include?(toc_token)
+            utf8_toc = rd.toc_content
+            utf8_toc.force_encoding("utf-8") if utf8_toc.respond_to?(:force_encoding)
+            html.gsub(toc_token, utf8_toc)
+          else
+            html
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jekyll/converters/markdown/redcarpet_parser.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+class Jekyll::Converters::Markdown::RedcarpetParser
+  module CommonMethods
+    def add_code_tags(code, lang)
+      code = code.to_s
+      code = code.sub(
+        %r!<pre>!,
+        "<pre><code class=\"language-#{lang}\" data-lang=\"#{lang}\">"
+      )
+      code = code.sub(%r!</pre>!, "</code></pre>")
+      code
+    end
+  end
+
+  module WithPygments
+    include CommonMethods
+    def block_code(code, lang)
+      Jekyll::External.require_with_graceful_fail("pygments")
+      lang = lang && lang.split.first || "text"
+      add_code_tags(
+        Pygments.highlight(
+          code,
+          {
+            :lexer   => lang,
+            :options => { :encoding => "utf-8" },
+          }
+        ),
+        lang
+      )
+    end
+  end
+
+  module WithoutHighlighting
+    require "cgi"
+
+    include CommonMethods
+
+    def code_wrap(code)
+      "<figure class=\"highlight\"><pre>#{CGI.escapeHTML(code)}</pre></figure>"
+    end
+
+    def block_code(code, lang)
+      lang = lang && lang.split.first || "text"
+      add_code_tags(code_wrap(code), lang)
+    end
+  end
+
+  module WithRouge
+    def block_code(code, lang)
+      code = "<pre>#{super}</pre>"
+
+      "<div class=\"highlight\">#{add_code_tags(code, lang)}</div>"
+    end
+
+    protected
+    def rouge_formatter(_lexer)
+      Jekyll::Utils::Rouge.html_formatter(:wrap => false)
+    end
+  end
+
+  def initialize(config)
+    Jekyll::External.require_with_graceful_fail("redcarpet")
+    @config = config
+    @redcarpet_extensions = {}
+    @config["redcarpet"]["extensions"].each do |e|
+      @redcarpet_extensions[e.to_sym] = true
+    end
+
+    @renderer ||= class_with_proper_highlighter(@config["highlighter"])
+  end
+
+  def class_with_proper_highlighter(highlighter)
+    Class.new(Redcarpet::Render::HTML) do
+      case highlighter
+      when "pygments"
+        include WithPygments
+      when "rouge"
+        Jekyll::External.require_with_graceful_fail(%w(
+          rouge rouge/plugins/redcarpet
+        ))
+
+        unless Gem::Version.new(Rouge.version) > Gem::Version.new("1.3.0")
+          abort "Please install Rouge 1.3.0 or greater and try running Jekyll again."
+        end
+
+        include Rouge::Plugins::Redcarpet
+        include CommonMethods
+        include WithRouge
+      else
+        include WithoutHighlighting
+      end
+    end
+  end
+
+  def convert(content)
+    @redcarpet_extensions[:fenced_code_blocks] = \
+      !@redcarpet_extensions[:no_fenced_code_blocks]
+    if @redcarpet_extensions[:smart]
+      @renderer.send :include, Redcarpet::Render::SmartyPants
+    end
+    markdown = Redcarpet::Markdown.new(
+      @renderer.new(@redcarpet_extensions),
+      @redcarpet_extensions
+    )
+    markdown.render(content)
+  end
+end