Upgrade kramdown dependency to v2.x (#7492)

Merge pull request 7492

Gemfile

@@ -63,14 +63,13 @@ end
 #
 
 group :jekyll_optional_dependencies do
-  gem "coderay", "~> 1.1.0"
   gem "jekyll-coffeescript"
   gem "jekyll-docs", :path => "../docs" if Dir.exist?("../docs") && ENV["JEKYLL_VERSION"]
   gem "jekyll-feed", "~> 0.9"
   gem "jekyll-gist"
   gem "jekyll-paginate"
   gem "jekyll-redirect-from"
-  gem "kramdown", "~> 1.14"
+  gem "kramdown-syntax-coderay"
   gem "mime-types", "~> 3.0"
   gem "rdoc", "~> 6.0"
   gem "tomlrb", "~> 1.2"

docs/_docs/upgrading/3-to-4.md

@@ -91,4 +91,51 @@ present in the generated site.
 
 ---
 
+### kramdown v2
+
+Jekyll has dropped support for `kramdown-1.x` entirely.
+
+From [`v2.0` onwards](https://kramdown.gettalong.org/news.html#kramdown-200-released) kramdown requires
+specific extensions to be additionally installed to use certain features are desired outside of kramdown's
+core functionality.
+
+Out of all the extensions listed in the report linked above, gem `kramdown-parser-gfm` is automatically
+installed along with Jekyll 4.0. The remaining extensions will have to be manually installed by the user
+depending on desired funtionality, by listing the extension's gem-name in their `Gemfile`.
+
+Notes:
+  * `kramdown-converter-pdf` will be ignored by Jekyll Core. To have Jekyll convert Markdown to PDF
+    you'll have to depend on a plugin that subclasses `Jekyll::Converter` with the
+    [required methods]({% link _docs/plugins/converters.md %}).
+
+    For example:
+
+    ```ruby
+    module Jekyll
+      External.require_with_graceful_fail "kramdown-converter-pdf"
+
+      class Markdown2PDF < Converter
+        safe true
+        priority :low
+
+        def matches(ext)
+          # match only files that have an extension exactly ".markdown"
+          ext =~ /^\.markdown$/
+        end
+
+        def convert(content)
+          Kramdown::Document.new(content).to_pdf
+        end
+
+        def output_ext
+          ".pdf"
+        end
+      end
+    end
+    ```
+  * Vendors that provide a versioned Jekyll Environment Image (e.g. Docker Image, GitHub Pages, etc)
+    will have to manually whitelist kramdown's extension gems in their distributions for Jekyll 4.0.
+
+---
+
 *Did we miss something? Please click "Improve this page" above and add a section. Thanks!*

features/collections.feature

@@ -393,6 +393,21 @@ Feature: Collections
     Then the _site directory should exist
     And I should see "Second document's output: <p>Use <code class=\"highlighter-rouge\">Jekyll.configuration</code> to build a full configuration for use w/Jekyll.</p>\n\n<p>Whatever: foo.bar</p>" in "_site/index.html"
 
+  Scenario: Documents have an output attribute, which is the converted HTML based on site.config
+    Given I have an "index.html" page that contains "Second document's output: {{ site.documents[2].output }}"
+    And I have fixture collections
+    And I have a "_config.yml" file with content:
+    """
+    kramdown:
+      guess_lang: false
+    collections:
+    - methods
+    """
+    When I run jekyll build
+    Then I should get a zero exit status
+    Then the _site directory should exist
+    And I should see "Second document's output: <p>Use <code>Jekyll.configuration</code> to build a full configuration for use w/Jekyll.</p>\n\n<p>Whatever: foo.bar</p>" in "_site/index.html"
+
   Scenario: Filter documents by where
     Given I have an "index.html" page that contains "{% assign items = site.methods | where: 'whatever','foo.bar' %}Item count: {{ items.size }}"
     And I have fixture collections

jekyll.gemspec

@@ -39,7 +39,8 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency("i18n",                  ">= 0.9.5", "< 2")
   s.add_runtime_dependency("jekyll-sass-converter", "~> 1.0")
   s.add_runtime_dependency("jekyll-watch",          "~> 2.0")
-  s.add_runtime_dependency("kramdown",              "~> 1.14")
+  s.add_runtime_dependency("kramdown",              "~> 2.1")
+  s.add_runtime_dependency("kramdown-parser-gfm",   "~> 1.0")
   s.add_runtime_dependency("liquid",                "~> 4.0")
   s.add_runtime_dependency("mercenary",             "~> 0.3.3")
   s.add_runtime_dependency("pathutil",              "~> 0.9")

lib/jekyll/configuration.rb

@@ -71,6 +71,7 @@ module Jekyll
         "smart_quotes"  => "lsquo,rsquo,ldquo,rdquo",
         "input"         => "GFM",
         "hard_wrap"     => false,
+        "guess_lang"    => true,
         "footnote_nr"   => 1,
         "show_warnings" => false,
       },

lib/jekyll/converters/markdown/kramdown_parser.rb

@@ -18,6 +18,7 @@ module Jekyll
           @config = config["kramdown"] || {}
           @highlighter = nil
           setup
+          load_dependencies
         end
 
         # Setup and normalize the configuration:
@@ -30,6 +31,7 @@ module Jekyll
         def setup
           @config["syntax_highlighter"] ||= highlighter
           @config["syntax_highlighter_opts"] ||= {}
+          @config["syntax_highlighter_opts"]["guess_lang"] = @config["guess_lang"]
           @config["coderay"] ||= {} # XXX: Legacy.
           modernize_coderay_config
           make_accessible
@@ -48,6 +50,20 @@ module Jekyll
 
         private
 
+        def load_dependencies
+          require "kramdown-parser-gfm" if @config["input"] == "GFM"
+
+          if highlighter == "coderay"
+            Jekyll::External.require_with_graceful_fail("kramdown-syntax-coderay")
+          end
+
+          # `mathjax` emgine is bundled within kramdown-2.x and will be handled by
+          # kramdown itself.
+          if (math_engine = @config["math_engine"]) && math_engine != "mathjax"
+            Jekyll::External.require_with_graceful_fail("kramdown-math-#{math_engine}")
+          end
+        end
+
         def make_accessible(hash = @config)
           hash.keys.each do |key|
             hash[key.to_sym] = hash[key]