From 4d017b4fed9ea489b8772e9d0923cbed788c5957 Mon Sep 17 00:00:00 2001 From: Jordon Date: Sat, 15 Jun 2013 05:03:53 -0500 Subject: [PATCH 1/9] Use $stderr, not STDERR, $stderr points to STDERR. --- lib/jekyll/converters/markdown.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/jekyll/converters/markdown.rb b/lib/jekyll/converters/markdown.rb index 485cac82..bd30fafe 100644 --- a/lib/jekyll/converters/markdown.rb +++ b/lib/jekyll/converters/markdown.rb @@ -18,8 +18,8 @@ module Jekyll when 'maruku' MarukuParser.new @config else - STDERR.puts "Invalid Markdown processor: #{@config['markdown']}" - STDERR.puts " Valid options are [ maruku | rdiscount | kramdown | redcarpet ]" + $stderr.puts "Invalid Markdown processor: #{@config['markdown']}" + $stderr.puts " Valid options are [ maruku | rdiscount | kramdown | redcarpet ]" raise FatalException.new("Invalid Markdown process: #{@config['markdown']}") end @setup = true From 626d54a812e33d9fb43bd3caec8d1296733f6afc Mon Sep 17 00:00:00 2001 From: Jordon Date: Sat, 15 Jun 2013 05:04:47 -0500 Subject: [PATCH 2/9] New is implied by `raise`, 2nd is the message. --- lib/jekyll/converters/markdown.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/jekyll/converters/markdown.rb b/lib/jekyll/converters/markdown.rb index bd30fafe..6ee0fa50 100644 --- a/lib/jekyll/converters/markdown.rb +++ b/lib/jekyll/converters/markdown.rb @@ -20,7 +20,7 @@ module Jekyll else $stderr.puts "Invalid Markdown processor: #{@config['markdown']}" $stderr.puts " Valid options are [ maruku | rdiscount | kramdown | redcarpet ]" - raise FatalException.new("Invalid Markdown process: #{@config['markdown']}") + raise FatalException, "Invalid Markdown process: #{@config['markdown']}" end @setup = true end From c759a7a75f32ac8f3ab157a9188c80f59fc58344 Mon Sep 17 00:00:00 2001 From: Jordon Date: Sat, 15 Jun 2013 06:00:47 -0500 Subject: [PATCH 3/9] Allow custom Markdown processors. --- lib/jekyll/converters/markdown.rb | 28 ++++++++++--------- test/test_site.rb | 46 +++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+), 13 deletions(-) diff --git a/lib/jekyll/converters/markdown.rb b/lib/jekyll/converters/markdown.rb index 6ee0fa50..1a18c96b 100644 --- a/lib/jekyll/converters/markdown.rb +++ b/lib/jekyll/converters/markdown.rb @@ -8,20 +8,22 @@ module Jekyll def setup return if @setup - @parser = case @config['markdown'] - when 'redcarpet' - RedcarpetParser.new @config - when 'kramdown' - KramdownParser.new @config - when 'rdiscount' - RDiscountParser.new @config - when 'maruku' - MarukuParser.new @config + @parser = + case @config['markdown'] + when 'redcarpet' then RedcarpetParser.new(@config) + when 'kramdown' then KramdownParser.new(@config) + when 'rdiscount' then RDiscountParser.new(@config) + when 'maruku' then MarukuParser.new(@config) else - $stderr.puts "Invalid Markdown processor: #{@config['markdown']}" - $stderr.puts " Valid options are [ maruku | rdiscount | kramdown | redcarpet ]" - raise FatalException, "Invalid Markdown process: #{@config['markdown']}" - end + # So they can't try some tricky bullshit or go down the ancestor chain, I hope. + if @config['markdown'] !~ /[^A-Za-z0-9]/ && self.class.constants.include?(@config['markdown'].to_sym) + self.class.const_get(@config['markdown']).new(@config) + else + $stderr.puts "Invalid Markdown processor: #{@config['markdown']}" + $stderr.puts " Valid options are [ maruku | rdiscount | kramdown | redcarpet ]" + raise FatalException, "Invalid Markdown process: #{@config['markdown']}" + end + end @setup = true end diff --git a/test/test_site.rb b/test/test_site.rb index 35359a2a..d6a2b0fa 100644 --- a/test/test_site.rb +++ b/test/test_site.rb @@ -255,6 +255,52 @@ class TestSite < Test::Unit::TestCase end end + context 'using a non-default markdown processor in the configuration' do + should 'use the non-default markdown processor' do + class Jekyll::Converters::Markdown::CustomMarkdown + def initialize(*args) + @args = args + end + + def convert(*args) + "" + end + end + + custom_processor = "CustomMarkdown" + s = Site.new(Jekyll.configuration.merge({ 'markdown' => custom_processor })) + assert_nothing_raised do + s.process + end + + # Do some cleanup, we don't like straggling stuff's. + Jekyll::Converters::Markdown.send(:remove_const, :CustomMarkdown) + end + + should 'ignore, if there are any bad characters in the class name' do + module Jekyll::Converters::Markdown::Custom + class Markdown + def initialize(*args) + @args = args + end + + def convert(*args) + "" + end + end + end + + bad_processor = "Custom::Markdown" + s = Site.new(Jekyll.configuration.merge({ 'markdown' => bad_processor })) + assert_raise Jekyll::FatalException do + s.process + end + + # Do some cleanup, we don't like straggling stuff's. + Jekyll::Converters::Markdown.send(:remove_const, :Custom) + end + end + context 'with an invalid markdown processor in the configuration' do should 'not throw an error at initialization time' do bad_processor = 'not a processor name' From 31bebf0f9ed2bb6bf93b741693b949e7c084442d Mon Sep 17 00:00:00 2001 From: Garen Torikian Date: Wed, 25 Dec 2013 16:11:30 -0600 Subject: [PATCH 4/9] Depend on Jekyll.logger.error, not $stderr --- lib/jekyll/converters/markdown.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/jekyll/converters/markdown.rb b/lib/jekyll/converters/markdown.rb index 1a18c96b..9727f5a4 100644 --- a/lib/jekyll/converters/markdown.rb +++ b/lib/jekyll/converters/markdown.rb @@ -19,8 +19,8 @@ module Jekyll if @config['markdown'] !~ /[^A-Za-z0-9]/ && self.class.constants.include?(@config['markdown'].to_sym) self.class.const_get(@config['markdown']).new(@config) else - $stderr.puts "Invalid Markdown processor: #{@config['markdown']}" - $stderr.puts " Valid options are [ maruku | rdiscount | kramdown | redcarpet ]" + Jekyll.logger.error "Invalid Markdown Processor:", "#{@config['markdown']}" + Jekyll.logger.error "", "Valid options are [ maruku | rdiscount | kramdown | redcarpet ]" raise FatalException, "Invalid Markdown process: #{@config['markdown']}" end end From a206dc1a8fdc2c2b91a6fc4c0d16ea4ddbbfbb03 Mon Sep 17 00:00:00 2001 From: Jordon Bedwell Date: Wed, 25 Dec 2013 22:18:40 -0600 Subject: [PATCH 5/9] Use downcase. --- lib/jekyll/converters/markdown.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/jekyll/converters/markdown.rb b/lib/jekyll/converters/markdown.rb index 9727f5a4..837a757d 100644 --- a/lib/jekyll/converters/markdown.rb +++ b/lib/jekyll/converters/markdown.rb @@ -9,7 +9,7 @@ module Jekyll def setup return if @setup @parser = - case @config['markdown'] + case @config['markdown'].downcase when 'redcarpet' then RedcarpetParser.new(@config) when 'kramdown' then KramdownParser.new(@config) when 'rdiscount' then RDiscountParser.new(@config) From 60b43104ee9ae0c59330f55c4dc08a27fabce2d0 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Thu, 26 Dec 2013 00:02:56 -0500 Subject: [PATCH 6/9] Extract checks for acceptable custom markdown processors to method. We should probably write more about what it does and how it works in a TomDoc block above. @envygeeks, want to give that a shot? --- lib/jekyll/converters/markdown.rb | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/lib/jekyll/converters/markdown.rb b/lib/jekyll/converters/markdown.rb index 837a757d..878be0b8 100644 --- a/lib/jekyll/converters/markdown.rb +++ b/lib/jekyll/converters/markdown.rb @@ -16,7 +16,7 @@ module Jekyll when 'maruku' then MarukuParser.new(@config) else # So they can't try some tricky bullshit or go down the ancestor chain, I hope. - if @config['markdown'] !~ /[^A-Za-z0-9]/ && self.class.constants.include?(@config['markdown'].to_sym) + if allowed_custom_class?(@config['markdown']) self.class.const_get(@config['markdown']).new(@config) else Jekyll.logger.error "Invalid Markdown Processor:", "#{@config['markdown']}" @@ -40,6 +40,11 @@ module Jekyll setup @parser.convert(content) end + + private + def allowed_custom_class?(parser_name) + parser_name !~ /[^A-Za-z0-9]/ && self.class.constants.include?(parser_name.to_sym) + end end end end From 7b9984699c13eab3fc7b435e8ccd50267bdbd2f6 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Thu, 26 Dec 2013 00:14:24 -0500 Subject: [PATCH 7/9] Fix error in exception message in Markdown Converter [ci skip] --- lib/jekyll/converters/markdown.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/jekyll/converters/markdown.rb b/lib/jekyll/converters/markdown.rb index 878be0b8..a539150e 100644 --- a/lib/jekyll/converters/markdown.rb +++ b/lib/jekyll/converters/markdown.rb @@ -21,7 +21,7 @@ module Jekyll else Jekyll.logger.error "Invalid Markdown Processor:", "#{@config['markdown']}" Jekyll.logger.error "", "Valid options are [ maruku | rdiscount | kramdown | redcarpet ]" - raise FatalException, "Invalid Markdown process: #{@config['markdown']}" + raise FatalException, "Invalid Markdown Processor: #{@config['markdown']}" end end @setup = true From ab95cca4349640d6e66a356dbe1048ac8c04fbb6 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Thu, 26 Dec 2013 00:33:34 -0500 Subject: [PATCH 8/9] Add TomDoc for Jekyll::Converters::Markdown#allowed_custom_class? --- lib/jekyll/converters/markdown.rb | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/lib/jekyll/converters/markdown.rb b/lib/jekyll/converters/markdown.rb index a539150e..178eaaa8 100644 --- a/lib/jekyll/converters/markdown.rb +++ b/lib/jekyll/converters/markdown.rb @@ -42,6 +42,14 @@ module Jekyll end private + + # 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 def allowed_custom_class?(parser_name) parser_name !~ /[^A-Za-z0-9]/ && self.class.constants.include?(parser_name.to_sym) end From 88612bf7cef0d41aa3be9f17dcfc6554e67d7725 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Thu, 26 Dec 2013 00:52:20 -0500 Subject: [PATCH 9/9] Add docs for custom markdown processors. --- site/docs/extras.md | 40 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/site/docs/extras.md b/site/docs/extras.md index 0c190ec1..14261e34 100644 --- a/site/docs/extras.md +++ b/site/docs/extras.md @@ -16,7 +16,12 @@ Maruku comes with optional support for LaTeX to PNG rendering via blahtex Maruku to not assume a fixed location for `dvips`, check out [Remi’s Maruku fork](http://github.com/remi/maruku). -## RDiscount +## Alternative Markdown Processors + +While Jekyll defaults to using Maruku for Markdown conversion, you may use one +of the other three pre-defined markdown parsers or define your own. + +### RDiscount If you prefer to use [RDiscount](http://github.com/rtomayko/rdiscount) instead of [Maruku](http://github.com/bhollis/maruku) for Markdown, just make sure you have @@ -34,7 +39,7 @@ have Jekyll run with that option. markdown: rdiscount {% endhighlight %} -## Kramdown +### Kramdown You can also use [Kramdown](http://kramdown.rubyforge.org/) instead of Maruku for Markdown. Make sure that Kramdown is installed: @@ -54,3 +59,34 @@ Kramdown has various options for customizing the HTML output. The [Configuration](/docs/configuration/) page lists the default options used by Jekyll. A complete list of options is also available on the [Kramdown website](http://kramdown.rubyforge.org/options.html). + +### User-Defined + +So, you're totally at odds with our four built-in markdown parsers, eh? No +sweat. You can define one as a plugin: + +{% highlight ruby %} +require 'jekyll' +require 'some_renderer' + +class Jekyll::Converters::Markdown::MyCustomParser + def initialize(config) + @site_config = config + end + + def convert(content) + # (this _must_ return the resulting String after the rendering) + SomeRenderer.new(@site_config).to_html(content) + end +end +{% endhighlight %} + +Once you've got that setup, ask Jekyll to use your custom markdown parser in +your `_config.yml` file: + +{% highlight yaml %} +markdown: MyCustomParser +{% endhighlight %} + +(Note that this **is case-sensitive**, and is only the piece after +`Jekyll::Converters::Markdown`.) And there you are!