class Kramdown::Converter::Base
Have a look at the Base::convert method for additional information!
converters do the transformation.
method per element type is a straight forward way to do it - this is how the Html and Latex
The actual transformation of the document tree can be done in any way. However, writing one
code for converting an element and has to return the conversion result.
properly). Then you need to implement the #convert method which has to contain the conversion
it in the Kramdown::Converter module (the latter is only needed if auto-detection should work
Implementing a new converter is rather easy: just derive a new class from this class and put
== Implementing a converter
directly but only use the Base::convert method.
state information during conversion. Therefore one can’t instantiate a converter object
A converter object is used as a throw-away object, i.e. it is only used for storing the needed
automatically applied to the result (for example, embedding the output into a template).
used by all converters (like #generate_id) as well as common functionality that is
This class serves as base class for all converters. It provides methods that can/should be
== Base class for converters
def self.apply_template(converter, body) # :nodoc:
and the converter object in the @converter instance variable.
The template is evaluated using ERB and the body is available in the @body instance variable
Apply the +template+ using +body+ as the body string.
def self.apply_template(converter, body) # :nodoc: erb = ERB.new(get_template(converter.options[:template])) obj = Object.new obj.instance_variable_set(:@converter, converter) obj.instance_variable_set(:@body, body) erb.result(obj.instance_eval { binding }) end
def self.convert(tree, options = {})
4. Check if the template name starts with 'string://' and if so, strip this prefix away and
directory (the form +.convertername+ is deprecated).
3. Append +.converter_name+ to the template name and look for it in the kramdown data
file in the current working directory (the form +.convertername+ is deprecated).
2. Append +.converter_name+ (e.g. +.html+) to the template name and look for the resulting
1. Look in the current working directory for the template.
The template resolution is done in the following way (for the converter ConverterName):
the body; if evaluated after, the result is used as body. See ::apply_template.
and #apply_template_after?. If the template is evaluated before, an empty string is used for
before and/or after the tree conversion depending on the result of #apply_template_before?
If the +template+ option is specified and non-empty, the template is evaluate with ERB
+tree+ as parameter.
Initializes a new instance of the calling class and then calls the #convert method with
options that should be used.
string) and an array with warning messages. The parameter +options+ specifies the conversion
Convert the element tree +tree+ and return the resulting conversion object (normally a
def self.convert(tree, options = {}) converter = new(tree, ::Kramdown::Options.merge(options.merge(tree.options[:options] || {}))) if !converter.options[:template].empty? && converter.apply_template_before? apply_template(converter, '') end result = converter.convert(tree) if result.respond_to?(:encode!) && result.encoding != Encoding::BINARY result.encode!(tree.options[:encoding] || (raise ::Kramdown::Error, "Missing encoding option on root element")) end if !converter.options[:template].empty? && converter.apply_template_after? result = apply_template(converter, result) end [result, converter.warnings] end
def self.get_template(template) # :nodoc:
Return the template specified by +template+.
def self.get_template(template) # :nodoc: format_ext = '.' + ::Kramdown::Utils.snake_case(name.split("::").last) shipped = File.join(::Kramdown.data_dir, template + format_ext) if File.exist?(template) File.read(template) elsif File.exist?(template + format_ext) File.read(template + format_ext) elsif File.exist?(shipped) File.read(shipped) elsif template.start_with?('string://') template.delete_prefix("string://") else raise "The specified template file #{template} does not exist" end end
def apply_template_after?
Returns whether the template should be applied after the conversion of the tree.
def apply_template_after? true end
def apply_template_before?
Returns whether the template should be applied before the conversion of the tree.
def apply_template_before? false end
def basic_generate_id(str)
The basic version of the ID generator, without any special provisions for empty or unique
def basic_generate_id(str) gen_id = str.gsub(/^[^a-zA-Z]+/, '') gen_id.tr!('^a-zA-Z0-9 -', '') gen_id.tr!(' ', '-') gen_id.downcase! gen_id end
def convert(_el)
Convert the element +el+ and return the resulting object.
def convert(_el) raise NotImplementedError end
def extract_code_language(attr)
def extract_code_language(attr) if attr['class'] && attr['class'] =~ /\blanguage-\S+/ attr['class'].scan(/\blanguage-(\S+)/).first.first end end
def extract_code_language!(attr)
See #extract_code_language
def extract_code_language!(attr) lang = extract_code_language(attr) attr['class'] = attr['class'].sub(/\blanguage-\S+/, '').strip if lang attr.delete('class') if lang && attr['class'].empty? lang end
def format_math(el, opts = {})
Format the given math element with the math engine configured through the option
def format_math(el, opts = {}) return nil unless @options[:math_engine] engine = ::Kramdown::Converter.math_engine(@options[:math_engine]) if engine engine.call(self, el, opts) else warning("The configured math engine #{@options[:math_engine]} is not available.") nil end end
def generate_id(str)
Uses the option +auto_id_prefix+: the value of this option is prepended to every generated
Generate an unique alpha-numeric ID from the the string +str+ for use as a header ID.
def generate_id(str) str = ::Kramdown::Utils::Unidecoder.decode(str) if @options[:transliterated_header_ids] gen_id = basic_generate_id(str) gen_id = 'section' if gen_id.empty? @used_ids ||= {} if @used_ids.key?(gen_id) gen_id += "-#{@used_ids[gen_id] += 1}" else @used_ids[gen_id] = 0 end @options[:auto_id_prefix] + gen_id end
def highlight_code(text, lang, type, opts = {})
Highlight the given +text+ in the language +lang+ with the syntax highlighter configured
def highlight_code(text, lang, type, opts = {}) return nil unless @options[:syntax_highlighter] highlighter = ::Kramdown::Converter.syntax_highlighter(@options[:syntax_highlighter]) if highlighter highlighter.call(self, text, lang, type, opts) else warning("The configured syntax highlighter #{@options[:syntax_highlighter]} is not available.") nil end end
def in_toc?(el)
Return +true+ if the header element +el+ should be used for the table of contents (as
def in_toc?(el) @options[:toc_levels].include?(el.options[:level]) && (el.attr['class'] || '') !~ /\bno_toc\b/ end
def initialize(root, options)
def initialize(root, options) @options = options @root = root @data = {} @warnings = [] end
def output_header_level(level)
Return the output header level given a level.
def output_header_level(level) [[level + @options[:header_offset], 6].min, 1].max end
def smart_quote_entity(el)
def smart_quote_entity(el) res = @options[:smart_quotes][SMART_QUOTE_INDICES[el.value]] ::Kramdown::Utils::Entities.entity(res) end
def warning(text)
def warning(text) @warnings << text end