kramdown 1.6.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a8108b2bee2981647e49b9d9bab886babcc204fc
-  data.tar.gz: cc74805fdeda7a9756f98f9a16d6ec3ca17442c5
+  metadata.gz: 28967ed8b0da11707a43ff1e7e92eb844d472fd0
+  data.tar.gz: dcf6f6dcf3f06e7bbf0c6fe90f326e380466b29b
 SHA512:
-  metadata.gz: efc4e05dfd0cc980479e027bfe8aa362e0f25dc008198dbd1922a3c18eb5552fdee1f78e2587ed430618af34ef6ea53f757b9f3447a86ea6b537318ed0d1c7e2
-  data.tar.gz: a7294eefa4b979a6bfe307c340c6b00b537f44c04e46977b4f5dedd256326bc7e02089a23edeaf4942e5e1f889fde1c21e469fcfa55dd32bfa8f49f94aa19818
+  metadata.gz: 4736e9a72ae7c194704ea5e7870e0bee43161794d2f71c071df0def49933578e02fabd72c4c02ba80b70f045fce748cb494c83a40ff915511bd7c8a39036a6d5
+  data.tar.gz: 86304867c51dcaa09e446701d88d975cdfada7d998d6051bd2479defda8d8ef1c0d9c2f3b74f3fce0ee17832e8d6785574a694f39fe063e6347ceeb24c245cf4

data/CONTRIBUTERS

@@ -1,6 +1,6 @@
   Count Name
 ======= ====
-    756 Thomas Leitner <t_leitner@gmx.at>
+    763 Thomas Leitner <t_leitner@gmx.at>
       6 Gioele Barabucci <gioele@svario.it>
       4 Ted Pak <powerpak006@gmail.com>
       4 Arne Brasseur <arne@arnebrasseur.net>
@@ -10,12 +10,14 @@
       3 Ben Armston <ben.armston@googlemail.com>
       3 Alex Marandon <contact@alexmarandon.com>
       2 Nathanael Jones <nathanael.jones@gmail.com>
+      2 Max Meyer <dev@fedux.org>
       2 Jo Hund <jhund@clearcove.ca>
       2 Bran <m.versum@gmail.com>
       1 winniehell <git@winniehell.de>
       1 utenmiki <utenmiki@gmail.com>
       1 Trevor Wennblom <trevor@well.com>
       1 tomykaira <tomykaira@gmail.com>
+      1 Tom Thorogood <me+github@tomthorogood.co.uk>
       1 Tim Blair <tim@bla.ir>
       1 Tim Besard <tim.besard@gmail.com>
       1 Tim Bates <tim@rumpuslabs.com>
@@ -29,6 +31,7 @@
       1 Matt Hickford <matt.hickford@gmail.com>
       1 Marcus Stollsteimer <sto.mar@web.de>
       1 Luca Barbato <luca.barbato@gmail.com>
+      1 l3kn <hello@l3kn.de>
       1 John Croisant <jacius@gmail.com>
       1 Joe Fiorini <joe@faithfulgeek.org>
       1 Jens Kraemer <jk@jkraemer.net>

data/VERSION

@@ -1 +1 @@
-1.6.0
+1.7.0

data/bin/kramdown

@@ -37,7 +37,7 @@ OptionParser.new do |opts|
   opts.separator "kramdown options:"
   opts.separator ""
 
-  Kramdown::Options.definitions.each do |n, definition|
+  Kramdown::Options.definitions.sort.each do |n, definition|
     no = n.to_s.tr('_', '-')
     if definition.type == Kramdown::Options::Boolean
       opts.on("--[no-]#{no}") {|v| options[n] = Kramdown::Options.parse(n, v)}

data/doc/documentation.template

@@ -18,6 +18,7 @@
   * [MathJax](math_engine/mathjax.html)
   * [Ritex](math_engine/ritex.html)
   * [itex2MML](math_engine/itex2mml.html)
+  * [Mathjax-Node](math_engine/mathjaxnode.html)
 * [Configuration Options](options.html)
 * [Tests](tests.html)
 

data/doc/index.page

@@ -97,8 +97,8 @@ extensions that have been made popular by the [PHP Markdown Extra] package and [
 It is probably the fastest pure-Ruby Markdown converter available (September 2014), being about 3x
 faster than [Maruku] and about 4.5x faster than [BlueFeather].
 
-Version **1.6.0**{:itemprop="softwareVersion"} released on
-**2015-02-28**{:itemprop="datePublished"}, [more news](news.html)
+Version **1.7.0**{:itemprop="softwareVersion"} released on
+**2015-04-27**{:itemprop="datePublished"}, [more news](news.html)
 {: style="text-align: center; font-size: 80%"}
 
 </div>

data/doc/syntax.page

@@ -1150,9 +1150,8 @@ Notes:
   However, if you use square brackets within the link text, you have to either properly nest them or
   to escape them. It is not possible to create nested links!
 
-* The link URL must not contain single or double quotes and it has to contain properly nested
-  parentheses if no title is specified, or the link URL must be contained in angle brackets
-  (incorrectly nested parentheses are allowed).
+* The link URL has to contain properly nested parentheses if no title is specified, or the link URL
+  must be contained in angle brackets (incorrectly nested parentheses are allowed).
 
 * The link title may not contain its delimiters and may not be empty.
 
@@ -1194,9 +1193,9 @@ definition looks like this:
 The link definition has the following structure:
 
 * The link identifier in square brackets, optionally indented up to three spaces,
-* then a colon and one or more spaces/tabs,
-* then the link URL which must not contain any single or double quotes and which must contain at
-  least one non-space character, or a left angle bracket, the link URL and a right angle bracket,
+* then a colon and one or more optional spaces/tabs,
+* then the link URL which must contain at least one non-space character, or a left angle bracket,
+  the link URL and a right angle bracket,
 * then optionally the title in single or double quotes, separated from the link URL by one or more
   spaces or on the next line by itself indented any number of spaces/tabs.
 

data/lib/kramdown/converter.rb

@@ -31,12 +31,12 @@ module Kramdown
 
     configurable(:syntax_highlighter)
 
-    ["Coderay", "Rouge"].each do |klass_name|
+    ['Minted', "Coderay", "Rouge"].each do |klass_name|
       kn_down = klass_name.downcase.intern
       add_syntax_highlighter(kn_down) do |converter, text, lang, type, opts|
         require "kramdown/converter/syntax_highlighter/#{kn_down}"
         klass = ::Kramdown::Utils.deep_const_get("::Kramdown::Converter::SyntaxHighlighter::#{klass_name}")
-        if klass::AVAILABLE
+        if !klass.const_defined?(:AVAILABLE) || klass::AVAILABLE
           add_syntax_highlighter(kn_down, klass)
         else
           add_syntax_highlighter(kn_down) {|*args| nil}
@@ -47,15 +47,12 @@ module Kramdown
 
     configurable(:math_engine)
 
-    require 'kramdown/converter/math_engine/mathjax'
-    add_math_engine(:mathjax, ::Kramdown::Converter::MathEngine::Mathjax)
-
-    ["Ritex", "Itex2MML"].each do |klass_name|
+    ['Mathjax', "MathjaxNode", "Ritex", "Itex2MML"].each do |klass_name|
       kn_down = klass_name.downcase.intern
       add_math_engine(kn_down) do |converter, el, opts|
         require "kramdown/converter/math_engine/#{kn_down}"
         klass = ::Kramdown::Utils.deep_const_get("::Kramdown::Converter::MathEngine::#{klass_name}")
-        if klass::AVAILABLE
+        if !klass.const_defined?(:AVAILABLE) || klass::AVAILABLE
           add_math_engine(kn_down, klass)
         else
           add_math_engine(kn_down) {|*args| nil}

data/lib/kramdown/converter/base.rb

@@ -182,8 +182,8 @@ module Kramdown
 
       # Extract the code block/span language from the attributes.
       def extract_code_language(attr)
-        if attr['class'] && attr['class'] =~ /\blanguage-\w+\b/
-          attr['class'].scan(/\blanguage-(\w+)\b/).first.first
+        if attr['class'] && attr['class'] =~ /\blanguage-\w[\w-]*\b/
+          attr['class'].scan(/\blanguage-(\w[\w-]*)\b/).first.first
         end
       end
 
@@ -192,7 +192,7 @@ module Kramdown
       # *Warning*: This version will modify the given attributes if a language is present.
       def extract_code_language!(attr)
         lang = extract_code_language(attr)
-        attr['class'] = attr['class'].sub(/\blanguage-\w+\b/, '').strip if lang
+        attr['class'] = attr['class'].sub(/\blanguage-\w[\w-]*\b/, '').strip if lang
         attr.delete('class') if lang && attr['class'].empty?
         lang
       end

data/lib/kramdown/converter/latex.rb

@@ -84,7 +84,12 @@ module Kramdown
       def convert_codeblock(el, opts)
         show_whitespace = el.attr['class'].to_s =~ /\bshow-whitespaces\b/
         lang = extract_code_language(el.attr)
-        if show_whitespace || lang
+
+        if @options[:syntax_highlighter] == :minted &&
+            (highlighted_code = highlight_code(el.value, lang, :block))
+          @data[:packages] << 'minted'
+          "#{latex_link_target(el)}#{highlighted_code}\n"
+        elsif show_whitespace || lang
           options = []
           options << "showspaces=%s,showtabs=%s" % (show_whitespace ? ['true', 'true'] : ['false', 'false'])
           options << "language=#{lang}" if lang
@@ -226,7 +231,14 @@ module Kramdown
       end
 
       def convert_codespan(el, opts)
-        "{\\tt #{latex_link_target(el)}#{escape(el.value)}}"
+        lang = extract_code_language(el.attr)
+        if @options[:syntax_highlighter] == :minted &&
+            (highlighted_code = highlight_code(el.value, lang, :span))
+          @data[:packages] << 'minted'
+          "#{latex_link_target(el)}#{highlighted_code}"
+        else
+          "{\\tt #{latex_link_target(el)}#{escape(el.value)}}"
+        end
       end
 
       def convert_footnote(el, opts)

data/lib/kramdown/converter/math_engine/mathjaxnode.rb

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+#
+#--
+# Copyright (C) 2009-2015 Thomas Leitner <t_leitner@gmx.at>
+#
+# This file is part of kramdown which is licensed under the MIT.
+#++
+#
+
+module Kramdown::Converter::MathEngine
+
+  # Uses the MathJax-node library for converting math formulas to MathML.
+  module MathjaxNode
+
+    # MathjaxNode is available if this constant is +true+.
+    AVAILABLE = RUBY_VERSION >= '1.9' && begin
+      npm = %x{npm --global --depth=1 list MathJax-node}
+
+      unless /MathJax-node@/ === npm.lines.drop(1).join("\n")
+        npm = %x{npm --depth=1 list MathJax-node}
+      end
+
+      T2MPATH = File.join(npm.lines.first.strip, "node_modules/MathJax-node/bin/tex2mml")
+      /MathJax-node@/ === npm.lines.drop(1).join("\n") && File.exist?(T2MPATH)
+    rescue
+      false
+    end
+
+    def self.call(converter, el, opts)
+      type = el.options[:category]
+
+      cmd = [T2MPATH]
+      cmd << "--inline" unless type == :block
+      cmd << "--semantics" if converter.options[:math_engine_opts][:semantics] == true
+      cmd << "--notexhints" if converter.options[:math_engine_opts][:texhints] == false
+      result = IO.popen(cmd << el.value).read.strip
+
+      attr = el.attr.dup
+      attr.delete('xmlns')
+      attr.delete('display')
+      result.insert("<math".length, converter.html_attributes(attr))
+
+      (type == :block ? "#{' '*opts[:indent]}#{result}\n" : result)
+    end
+
+  end
+
+end

data/lib/kramdown/converter/syntax_highlighter/coderay.rb

@@ -27,7 +27,7 @@ module Kramdown::Converter::SyntaxHighlighter
       if type == :span && lang
         ::CodeRay.scan(text, lang.to_sym).html(options(converter, :span)).chomp
       elsif type == :block && (lang || options(converter, :default_lang))
-        lang = (lang || options(converter, :default_lang)).to_sym
+        lang = (lang || options(converter, :default_lang)).to_s.gsub(/-/, '_').to_sym
         ::CodeRay.scan(text, lang).html(options(converter, :block)).chomp << "\n"
       else
         nil

data/lib/kramdown/converter/syntax_highlighter/minted.rb

@@ -0,0 +1,35 @@
+# -*- coding: utf-8 -*-
+#
+#--
+# Copyright (C) 2009-2015 Thomas Leitner <t_leitner@gmx.at>
+#
+# This file is part of kramdown which is licensed under the MIT.
+#++
+#
+
+module Kramdown::Converter::SyntaxHighlighter
+
+  # Uses Minted to highlight code blocks and code spans.
+  module Minted
+
+    def self.call(converter, text, lang, type, _opts)
+      opts = converter.options[:syntax_highlighter_opts]
+
+      # Fallback to default language
+      lang ||= opts[:default_lang]
+
+      options = []
+      options << "breaklines" if opts[:wrap]
+      options << "linenos" if opts[:line_numbers]
+      options << "frame=#{opts[:frame]}" if opts[:frame]
+
+      if lang && type == :block
+        "\\begin{minted}[#{options.join(',')}]{#{lang}}\n#{text}\n\\end{minted}"
+      elsif lang && type == :span
+        "\\mintinline{#{lang}}{#{text}}"
+      else
+        nil
+      end
+    end
+  end
+end

data/lib/kramdown/options.rb

@@ -525,7 +525,7 @@ Options for the syntax highlighter can be set with the
 syntax_highlighter_opts configuration option.
 
 Default: coderay
-Used by: HTML converter
+Used by: HTML/Latex converter
 EOF
 
     define(:syntax_highlighter_opts, Object, {}, <<EOF) do |val|
@@ -538,7 +538,7 @@ The value needs to be a hash with key-value pairs that are understood by
 the used syntax highlighter.
 
 Default: {}
-Used by: HTML converter
+Used by: HTML/Latex converter
 EOF
       val = simple_hash_validator(val, :syntax_highlighter_opts)
       val.keys.each do |k|

data/lib/kramdown/parser/gfm.rb

@@ -55,7 +55,7 @@ module Kramdown
       ATX_HEADER_START = /^\#{1,6}\s/
       define_parser(:atx_header_gfm, ATX_HEADER_START, nil, 'parse_atx_header')
 
-      FENCED_CODEBLOCK_MATCH = /^(([~`]){3,})\s*?(\w+)?\s*?\n(.*?)^\1\2*\s*?\n/m
+      FENCED_CODEBLOCK_MATCH = /^(([~`]){3,})\s*?(\w[\w-]*)?\s*?\n(.*?)^\1\2*\s*?\n/m
       define_parser(:codeblock_fenced_gfm, /^[~`]{3,}/, nil, 'parse_codeblock_fenced')
 
     end

data/lib/kramdown/parser/html.rb

@@ -150,7 +150,7 @@ module Kramdown
               elsif result = @src.scan(HTML_INSTRUCTION_RE)
                 @tree.children << Element.new(:xml_pi, result, nil, :category => :block, :location => line)
               elsif @src.scan(HTML_TAG_RE)
-                if method(:handle_html_start_tag).arity == 1
+                if method(:handle_html_start_tag).arity.abs >= 1
                   handle_html_start_tag(line, &block)
                 else
                   handle_html_start_tag(&block) # DEPRECATED: method needs to accept line number in 2.0
@@ -422,7 +422,7 @@ module Kramdown
             else
               set_basics(el, :codeblock)
               if el.children.size == 1 && el.children.first.value == 'code'
-                value = (el.children.first.attr['class'] || '').scan(/\blanguage-\w+\b/).first
+                value = (el.children.first.attr['class'] || '').scan(/\blanguage-\w[\w-]*\b/).first
                 el.attr['class'] = "#{value} #{el.attr['class']}".rstrip if value
               end
             end

data/lib/kramdown/parser/kramdown/codeblock.rb

@@ -32,7 +32,7 @@ module Kramdown
 
 
       FENCED_CODEBLOCK_START = /^~{3,}/
-      FENCED_CODEBLOCK_MATCH = /^((~){3,})\s*?(\w+)?\s*?\n(.*?)^\1\2*\s*?\n/m
+      FENCED_CODEBLOCK_MATCH = /^((~){3,})\s*?(\w[\w-]*)?\s*?\n(.*?)^\1\2*\s*?\n/m
 
       # Parse the fenced codeblock at the current location.
       def parse_codeblock_fenced

data/lib/kramdown/parser/kramdown/link.rb

@@ -18,10 +18,11 @@ module Kramdown
         id.gsub(/[\s]+/, ' ').downcase
       end
 
-      LINK_DEFINITION_START = /^#{OPT_SPACE}\[([^\n\]]+)\]:[ \t]*(?:<(.*?)>|([^'"\n]*?\S[^'"\n]*?))[ \t]*?(?:\n?[ \t]*?(["'])(.+?)\4[ \t]*?)?\n/
+      LINK_DEFINITION_START = /^#{OPT_SPACE}\[([^\n\]]+)\]:[ \t]*(?:<(.*?)>|([^\n]*?\S[^\n]*?))(?:(?:[ \t]*?\n|[ \t]+?)[ \t]*?(["'])(.+?)\4)?[ \t]*?\n/
 
       # Parse the link definition at the current location.
       def parse_link_definition
+        return false if @src[3].to_s =~ /[ \t]+["']/
         @src.pos += @src.matched_size
         link_id, link_url, link_title = normalize_link_id(@src[1]), @src[2] || @src[3], @src[5]
         warning("Duplicate link ID '#{link_id}' on line #{@src.current_line_number} - overwriting") if @link_defs[link_id]

data/lib/kramdown/utils/configurable.rb

@@ -29,7 +29,7 @@ module Kramdown
         singleton_class = (class << self; self; end)
         singleton_class.send(:define_method, :configurables) do
           @_configurables ||= Hash.new {|h, k| h[k] = {}}
-        end
+        end unless respond_to?(:configurables)
         singleton_class.send(:define_method, name) do |data|
           configurables[name][data]
         end

data/lib/kramdown/version.rb

@@ -10,6 +10,6 @@
 module Kramdown
 
   # The kramdown version.
-  VERSION = '1.6.0'
+  VERSION = '1.7.0'
 
 end

data/man/man1/kramdown.1

@@ -35,41 +35,16 @@ Show the help.
 .SH KRAMDOWN OPTIONS
 
 .TP
-.B \-\-template ARG
-
-The name of an ERB template file that should be used to wrap the output
-or the ERB template itself.
-
-This is used to wrap the output in an environment so that the output can
-be used as a stand-alone document. For example, an HTML template would
-provide the needed header and body tags so that the whole output is a
-valid HTML file. If no template is specified, the output will be just
-the converted text.
+.B \-\-auto-id-prefix ARG
 
-When resolving the template file, the given template name is used first.
-If such a file is not found, the converter extension (the same as the
-converter name) is appended. If the file still cannot be found, the
-templates name is interpreted as a template name that is provided by
-kramdown (without the converter extension). If the file is still not
-found, the template name is checked if it starts with 'string://' and if
-it does, this prefix is removed and the rest is used as template
-content.
+Prefix used for automatically generated header IDs
 
-kramdown provides a default template named 'document' for each converter.
+This option can be used to set a prefix for the automatically generated
+header IDs so that there is no conflict when rendering multiple kramdown
+documents into one output file separately. The prefix should only
+contain characters that are valid in an ID!
 
 Default: ''
-Used by: all converters
-
-
-.TP
-.B \-\-[no\-]auto-ids
-
-Use automatic header ID generation
-
-If this option is `true`, ID values for all headers are automatically
-generated if no ID is explicitly specified.
-
-Default: true
 Used by: HTML/Latex converter
 
 
@@ -90,103 +65,92 @@ Used by: kramdown parser
 
 
 .TP
-.B \-\-auto-id-prefix ARG
+.B \-\-[no\-]auto-ids
 
-Prefix used for automatically generated header IDs
+Use automatic header ID generation
 
-This option can be used to set a prefix for the automatically generated
-header IDs so that there is no conflict when rendering multiple kramdown
-documents into one output file separately. The prefix should only
-contain characters that are valid in an ID!
+If this option is `true`, ID values for all headers are automatically
+generated if no ID is explicitly specified.
 
-Default: ''
+Default: true
 Used by: HTML/Latex converter
 
 
 .TP
-.B \-\-[no\-]transliterated-header-ids
-
-Transliterate the header text before generating the ID
+.B \-\-coderay-bold-every ARG
 
-Only ASCII characters are used in headers IDs. This is not good for
-languages with many non-ASCII characters. By enabling this option
-the header text is transliterated to ASCII as good as possible so that
-the resulting header ID is more useful.
+Defines how often a line number should be made bold
 
-The stringex library needs to be installed for this feature to work!
+Can either be an integer or false (to turn off bold line numbers
+completely).
 
-Default: false
-Used by: HTML/Latex converter
+Default: 10
+Used by: HTML converter
 
 
 .TP
-.B \-\-[no\-]parse-block-html
+.B \-\-coderay-css ARG
 
-Process kramdown syntax in block HTML tags
+Defines how the highlighted code gets styled
 
-If this option is `true`, the kramdown parser processes the content of
-block HTML tags as text containing block-level elements. Since this is
-not wanted normally, the default is `false`. It is normally better to
-selectively enable kramdown processing via the markdown attribute.
+Possible values are :class (CSS classes are applied to the code
+elements, one must supply the needed CSS file) or :style (default CSS
+styles are directly applied to the code elements).
 
-Default: false
-Used by: kramdown parser
+Default: style
+Used by: HTML converter
 
 
 .TP
-.B \-\-[no\-]parse-span-html
+.B \-\-coderay-default-lang ARG
 
-Process kramdown syntax in span HTML tags
+Sets the default language for highlighting code blocks
 
-If this option is `true`, the kramdown parser processes the content of
-span HTML tags as text containing span-level elements.
+If no language is set for a code block, the default language is used
+instead. The value has to be one of the languages supported by coderay
+or nil if no default language should be used.
 
-Default: true
-Used by: kramdown parser
+Default: nil
+Used by: HTML converter
 
 
 .TP
-.B \-\-[no\-]html-to-native
+.B \-\-coderay-line-number-start ARG
 
-Convert HTML elements to native elements
+The start value for the line numbers
 
-If this option is `true`, the parser converts HTML elements to native
-elements. For example, when parsing `<em>hallo</em>` the emphasis tag
-would normally be converted to an `:html` element with tag type `:em`.
-If `html_to_native` is `true`, then the emphasis would be converted to a
-native `:em` element.
+Default: 1
+Used by: HTML converter
 
-This is useful for converters that cannot deal with HTML elements.
 
-Default: false
-Used by: kramdown parser
+.TP
+.B \-\-coderay-line-numbers ARG
 
+Defines how and if line numbers should be shown
 
-.TP
-.B \-\-link-defs ARG
+The possible values are :table, :inline or nil. If this option is
+nil, no line numbers are shown.
 
-Pre-defines link definitions
+Default: :inline
+Used by: HTML converter
 
-This option can be used to pre-define link definitions. The value needs
-to be a Hash where the keys are the link identifiers and the values are
-two element Arrays with the link URL and the link title.
 
-If the value is a String, it has to contain a valid YAML hash and the
-hash has to follow the above guidelines.
+.TP
+.B \-\-coderay-tab-width ARG
 
-Default: {}
-Used by: kramdown parser
+The tab width used in highlighted code
+
+Used by: HTML converter
 
 
 .TP
-.B \-\-footnote-nr ARG
+.B \-\-coderay-wrap ARG
 
-The number of the first footnote
+Defines how the highlighted code should be wrapped
 
-This option can be used to specify the number that is used for the first
-footnote.
+The possible values are :span, :div or nil.
 
-Default: 1
+Default: :div
 Used by: HTML converter
 
 
@@ -203,144 +167,166 @@ Used by: HTML converter
 
 
 .TP
-.B \-\-coderay-wrap ARG
+.B \-\-entity-output ARG
 
-Defines how the highlighted code should be wrapped
+Defines how entities are output
 
-The possible values are :span, :div or nil.
+The possible values are :as_input (entities are output in the same
+form as found in the input), :numeric (entities are output in numeric
+form), :symbolic (entities are output in symbolic form if possible) or
+:as_char (entities are output as characters if possible, only available
+on Ruby 1.9).
 
-Default: :div
-Used by: HTML converter
+Default: :as_char
+Used by: HTML converter, kramdown converter
 
 
 .TP
-.B \-\-coderay-line-numbers ARG
+.B \-\-footnote-nr ARG
 
-Defines how and if line numbers should be shown
+The number of the first footnote
 
-The possible values are :table, :inline or nil. If this option is
-nil, no line numbers are shown.
+This option can be used to specify the number that is used for the first
+footnote.
 
-Default: :inline
+Default: 1
 Used by: HTML converter
 
 
 .TP
-.B \-\-coderay-line-number-start ARG
+.B \-\-[no\-]hard-wrap
 
-The start value for the line numbers
+Interprets line breaks literally
 
-Default: 1
-Used by: HTML converter
+Insert HTML `<br />` tags inside paragraphs where the original Markdown
+document had newlines (by default, Markdown ignores these newlines).
+
+Default: true
+Used by: GFM parser
 
 
 .TP
-.B \-\-coderay-tab-width ARG
+.B \-\-header-offset ARG
 
-The tab width used in highlighted code
+Sets the output offset for headers
 
-Used by: HTML converter
+If this option is c (may also be negative) then a header with level n
+will be output as a header with level c+n. If c+n is lower than 1,
+level 1 will be used. If c+n is greater than 6, level 6 will be used.
+
+Default: 0
+Used by: HTML converter, Kramdown converter, Latex converter
 
 
 .TP
-.B \-\-coderay-bold-every ARG
+.B \-\-[no\-]html-to-native
 
-Defines how often a line number should be made bold
+Convert HTML elements to native elements
 
-Can either be an integer or false (to turn off bold line numbers
-completely).
+If this option is `true`, the parser converts HTML elements to native
+elements. For example, when parsing `<em>hallo</em>` the emphasis tag
+would normally be converted to an `:html` element with tag type `:em`.
+If `html_to_native` is `true`, then the emphasis would be converted to a
+native `:em` element.
 
-Default: 10
-Used by: HTML converter
+This is useful for converters that cannot deal with HTML elements.
+
+Default: false
+Used by: kramdown parser
 
 
 .TP
-.B \-\-coderay-css ARG
+.B \-\-latex-headers ARG
 
-Defines how the highlighted code gets styled
+Defines the LaTeX commands for different header levels
 
-Possible values are :class (CSS classes are applied to the code
-elements, one must supply the needed CSS file) or :style (default CSS
-styles are directly applied to the code elements).
+The commands for the header levels one to six can be specified by
+separating them with commas.
 
-Default: style
-Used by: HTML converter
+Default: section,subsection,subsubsection,paragraph,subparagraph,subparagraph
+Used by: Latex converter
 
 
 .TP
-.B \-\-coderay-default-lang ARG
-
-Sets the default language for highlighting code blocks
+.B \-\-line-width ARG
 
-If no language is set for a code block, the default language is used
-instead. The value has to be one of the languages supported by coderay
-or nil if no default language should be used.
+Defines the line width to be used when outputting a document
 
-Default: nil
-Used by: HTML converter
+Default: 72
+Used by: kramdown converter
 
 
 .TP
-.B \-\-entity-output ARG
+.B \-\-link-defs ARG
 
-Defines how entities are output
+Pre-defines link definitions
 
-The possible values are :as_input (entities are output in the same
-form as found in the input), :numeric (entities are output in numeric
-form), :symbolic (entities are output in symbolic form if possible) or
-:as_char (entities are output as characters if possible, only available
-on Ruby 1.9).
+This option can be used to pre-define link definitions. The value needs
+to be a Hash where the keys are the link identifiers and the values are
+two element Arrays with the link URL and the link title.
 
-Default: :as_char
-Used by: HTML converter, kramdown converter
+If the value is a String, it has to contain a valid YAML hash and the
+hash has to follow the above guidelines.
+
+Default: {}
+Used by: kramdown parser
 
 
 .TP
-.B \-\-toc-levels ARG
+.B \-\-math-engine ARG
 
-Defines the levels that are used for the table of contents
+Set the math engine
 
-The individual levels can be specified by separating them with commas
-(e.g. 1,2,3) or by using the range syntax (e.g. 1..3). Only the
-specified levels are used for the table of contents.
+Specifies the math engine that should be used for converting math
+blocks/spans. If this option is set to +nil+, no math engine is used and
+the math blocks/spans are output as is.
 
-Default: 1..6
-Used by: HTML/Latex converter
+Options for the selected math engine can be set with the
+math_engine_opts configuration option.
+
+Default: mathjax
+Used by: HTML converter
 
 
 .TP
-.B \-\-line-width ARG
+.B \-\-math-engine-opts ARG
 
-Defines the line width to be used when outputting a document
+Set the math engine options
 
-Default: 72
-Used by: kramdown converter
+Specifies options for the math engine set via the math_engine
+configuration option.
+
+The value needs to be a hash with key-value pairs that are understood by
+the used math engine.
+
+Default: {}
+Used by: HTML converter
 
 
 .TP
-.B \-\-latex-headers ARG
+.B \-\-[no\-]parse-block-html
 
-Defines the LaTeX commands for different header levels
+Process kramdown syntax in block HTML tags
 
-The commands for the header levels one to six can be specified by
-separating them with commas.
+If this option is `true`, the kramdown parser processes the content of
+block HTML tags as text containing block-level elements. Since this is
+not wanted normally, the default is `false`. It is normally better to
+selectively enable kramdown processing via the markdown attribute.
 
-Default: section,subsection,subsubsection,paragraph,subparagraph,subparagraph
-Used by: Latex converter
+Default: false
+Used by: kramdown parser
 
 
 .TP
-.B \-\-smart-quotes ARG
+.B \-\-[no\-]parse-span-html
 
-Defines the HTML entity names or code points for smart quote output
+Process kramdown syntax in span HTML tags
 
-The entities identified by entity name or code point that should be
-used for, in order, a left single quote, a right single quote, a left
-double and a right double quote are specified by separating them with
-commas.
+If this option is `true`, the kramdown parser processes the content of
+span HTML tags as text containing span-level elements.
 
-Default: lsquo,rsquo,ldquo,rdquo
-Used by: HTML/Latex converter
+Default: true
+Used by: kramdown parser
 
 
 .TP
@@ -368,28 +354,17 @@ Used by: RemoveHtmlTags converter
 
 
 .TP
-.B \-\-header-offset ARG
-
-Sets the output offset for headers
-
-If this option is c (may also be negative) then a header with level n
-will be output as a header with level c+n. If c+n is lower than 1,
-level 1 will be used. If c+n is greater than 6, level 6 will be used.
-
-Default: 0
-Used by: HTML converter, Kramdown converter, Latex converter
-
-
-.TP
-.B \-\-[no\-]hard-wrap
+.B \-\-smart-quotes ARG
 
-Interprets line breaks literally
+Defines the HTML entity names or code points for smart quote output
 
-Insert HTML `<br />` tags inside paragraphs where the original Markdown
-document had newlines (by default, Markdown ignores these newlines).
+The entities identified by entity name or code point that should be
+used for, in order, a left single quote, a right single quote, a left
+double and a right double quote are specified by separating them with
+commas.
 
-Default: true
-Used by: GFM parser
+Default: lsquo,rsquo,ldquo,rdquo
+Used by: HTML/Latex converter
 
 
 .TP
@@ -405,7 +380,7 @@ Options for the syntax highlighter can be set with the
 syntax_highlighter_opts configuration option.
 
 Default: coderay
-Used by: HTML converter
+Used by: HTML/Latex converter
 
 
 .TP
@@ -420,38 +395,63 @@ The value needs to be a hash with key-value pairs that are understood by
 the used syntax highlighter.
 
 Default: {}
-Used by: HTML converter
+Used by: HTML/Latex converter
 
 
 .TP
-.B \-\-math-engine ARG
+.B \-\-template ARG
 
-Set the math engine
+The name of an ERB template file that should be used to wrap the output
+or the ERB template itself.
 
-Specifies the math engine that should be used for converting math
-blocks/spans. If this option is set to +nil+, no math engine is used and
-the math blocks/spans are output as is.
+This is used to wrap the output in an environment so that the output can
+be used as a stand-alone document. For example, an HTML template would
+provide the needed header and body tags so that the whole output is a
+valid HTML file. If no template is specified, the output will be just
+the converted text.
 
-Options for the selected math engine can be set with the
-math_engine_opts configuration option.
+When resolving the template file, the given template name is used first.
+If such a file is not found, the converter extension (the same as the
+converter name) is appended. If the file still cannot be found, the
+templates name is interpreted as a template name that is provided by
+kramdown (without the converter extension). If the file is still not
+found, the template name is checked if it starts with 'string://' and if
+it does, this prefix is removed and the rest is used as template
+content.
 
-Default: mathjax
-Used by: HTML converter
+kramdown provides a default template named 'document' for each converter.
+
+Default: ''
+Used by: all converters
 
 
 .TP
-.B \-\-math-engine-opts ARG
+.B \-\-toc-levels ARG
 
-Set the math engine options
+Defines the levels that are used for the table of contents
 
-Specifies options for the math engine set via the math_engine
-configuration option.
+The individual levels can be specified by separating them with commas
+(e.g. 1,2,3) or by using the range syntax (e.g. 1..3). Only the
+specified levels are used for the table of contents.
 
-The value needs to be a hash with key-value pairs that are understood by
-the used math engine.
+Default: 1..6
+Used by: HTML/Latex converter
 
-Default: {}
-Used by: HTML converter
+
+.TP
+.B \-\-[no\-]transliterated-header-ids
+
+Transliterate the header text before generating the ID
+
+Only ASCII characters are used in headers IDs. This is not good for
+languages with many non-ASCII characters. By enabling this option
+the header text is transliterated to ASCII as good as possible so that
+the resulting header ID is more useful.
+
+The stringex library needs to be installed for this feature to work!
+
+Default: false
+Used by: HTML/Latex converter
 
 
 .SH EXIT STATUS