module Kramdown::Options

This module defines all options that are used by parsers and/or converters as well as providing methods to deal with the options.

Available `Options`

auto_id_prefix (type: String, default: “”)

Prefix used for automatically generated header IDs

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!

Used by: HTML/Latex converter

auto_id_stripping (type: Kramdown::Options::Boolean, default: false)

Strip all formatting from header text for automatic ID generation

If this option is ‘true`, only the text elements of a header are used for generating the ID later (in contrast to just using the raw header text line).

This option will be removed in version 2.0 because this will be the default then.

Used by: kramdown parser

auto_ids (type: Kramdown::Options::Boolean, default: true)

Use automatic header ID generation

If this option is ‘true`, ID values for all headers are automatically generated if no ID is explicitly specified.

Used by: HTML/Latex converter

entity_output (type: Symbol, default: :as_char)

Defines how entities are output

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).

Used by: HTML converter, kramdown converter

footnote_backlink (type: String, default: “↩”)

Defines the text that should be used for the footnote backlinks

The footnote backlink is just text, so any special HTML characters will be escaped.

If the footnote backlint text is an empty string, no footnote backlinks will be generated.

Used by: HTML converter

footnote_backlink_inline (type: Kramdown::Options::Boolean, default: false)

Specifies whether the footnote backlink should always be inline

With the default of false the footnote backlink is placed at the end of the last paragraph if there is one, or an extra paragraph with only the footnote backlink is created.

Setting this option to true tries to place the footnote backlink in the last, possibly nested paragraph or header. If this fails (e.g. in the case of a table), an extra paragraph with only the footnote backlink is created.

Used by: HTML converter

footnote_link_text (type: String, default: “%s”)

The text used for the footnote number in a footnote link

This option can be used to add additional text to the footnote link. It should be a format string, and is passed the footnote number as the only argument to the format string. e.g. “[footnote %s]” would display as “[footnote 1]”.

Used by: HTML

footnote_nr (type: Integer, default: 1)

The number of the first footnote

This option can be used to specify the number that is used for the first footnote.

Used by: HTML converter

footnote_prefix (type: String, default: “”)

Prefix used for footnote IDs

This option can be used to set a prefix for footnote IDs. This is useful when rendering multiple documents into the same output file to avoid duplicate IDs. The prefix should only contain characters that are valid in an ID!

Used by: HTML

forbidden_inline_options (type: Object, default: [:template])

Defines the options that may not be set using the {::options} extension

The value needs to be an array of option names.

Used by: HTML converter

header_links (type: Kramdown::Options::Boolean, default: false)

Adds anchor tags within headers that can be used to generate permalinks when not using a table of contents.

The anchor tags are empty, but can be styled to your liking.

Default: false

header_offset (type: Integer, default: 0)

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.

Used by: HTML converter, Kramdown converter, Latex converter

html_to_native (type: Kramdown::Options::Boolean, default: false)

Convert HTML elements to native elements

If this option is ‘true`, the parser converts HTML elements to native elements. For example, when parsing `hallo` 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.

This is useful for converters that cannot deal with HTML elements.

Used by: kramdown parser

latex_headers (type: Object, default: [“section”, “subsection”, “subsubsection”, “paragraph”, “subparagraph”, “subparagraph”])

Defines the LaTeX commands for different header levels

The commands for the header levels one to six can be specified by separating them with commas.

Used by: Latex converter

line_width (type: Integer, default: 72)

Defines the line width to be used when outputting a document

Used by: kramdown converter

link_defs (type: Object, default: {})

Pre-defines link definitions

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.

Used by: kramdown parser

list_indent (type: Integer, default: 2)

Sets the number of spaces to use for list indentation

Used by: Kramdown converter

math_engine (type: Symbol, default: :mathjax)

Set the math engine

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.

Options for the selected math engine can be set with the math_engine_opts configuration option.

Used by: HTML converter

math_engine_opts (type: Object, default: {})

Set the math engine options

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.

Used by: HTML converter

parse_block_html (type: Kramdown::Options::Boolean, default: false)

Process kramdown syntax in block HTML tags

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.

Used by: kramdown parser

parse_span_html (type: Kramdown::Options::Boolean, default: true)

Process kramdown syntax in span HTML tags

If this option is ‘true`, the kramdown parser processes the content of span HTML tags as text containing span-level elements.

Used by: kramdown parser

remove_block_html_tags (type: Kramdown::Options::Boolean, default: true)

Remove block HTML tags

If this option is ‘true`, the RemoveHtmlTags converter removes block HTML tags.

Used by: RemoveHtmlTags converter

remove_line_breaks_for_cjk (type: Kramdown::Options::Boolean, default: false)

Specifies whether line breaks should be removed between CJK characters

Used by: HTML converter

remove_span_html_tags (type: Kramdown::Options::Boolean, default: false)

Remove span HTML tags

If this option is ‘true`, the RemoveHtmlTags converter removes span HTML tags.

Used by: RemoveHtmlTags converter

smart_quotes (type: Object, default: [“lsquo”, “rsquo”, “ldquo”, “rdquo”])

Defines the HTML entity names or code points for smart quote output

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.

Used by: HTML/Latex converter

syntax_highlighter (type: Symbol, default: :rouge)

Set the syntax highlighter

Specifies the syntax highlighter that should be used for highlighting code blocks and spans. If this option is set to nil, no syntax highlighting is done.

Options for the syntax highlighter can be set with the syntax_highlighter_opts configuration option.

Used by: HTML/Latex converter

syntax_highlighter_opts (type: Object, default: {})

Set the syntax highlighter options

Specifies options for the syntax highlighter set via the syntax_highlighter configuration option.

The value needs to be a hash with key-value pairs that are understood by the used syntax highlighter.

Used by: HTML/Latex converter

template (type: String, default: “”)

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.

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.

kramdown provides a default template named ‘document’ for each converter.

Used by: all converters

toc_levels (type: Object, default: [1, 2, 3, 4, 5, 6])

Defines the levels that are used for the table of contents

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.

Used by: HTML/Latex converter

transliterated_header_ids (type: Kramdown::Options::Boolean, default: false)

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!

Used by: HTML/Latex converter

typographic_symbols (type: Object, default: {})

Defines a mapping from typographical symbol to output characters

Typographical symbols are normally output using their equivalent Unicode codepoint. However, sometimes one wants to change the output, mostly to fallback to a sequence of ASCII characters.

This option allows this by specifying a mapping from typographical symbol to its output string. For example, the mapping {hellip: …} would output the standard ASCII representation of an ellipsis.

The available typographical symbol names are:

hellip: ellipsis
mdash: em-dash
ndash: en-dash
laquo: left guillemet
raquo: right guillemet
laquo_space: left guillemet followed by a space
raquo_space: right guillemet preceeded by a space

Used by: HTML/Latex converter

Option Definitions

Option Validators

Public Class Methods

simple_array_validator (val, name, size = nil)

Source

# File lib/kramdown/options.rb, line 141
def self.simple_array_validator(val, name, size = nil)
  if String === val
    val = val.split(",")
  elsif !(Array === val)
    raise Kramdown::Error, "Invalid type #{val.class} for option #{name}"
  end
  if size && val.size != size
    raise Kramdown::Error, "Option #{name} needs exactly #{size} values"
  end
  val
end

Ensures that the option value val for the option called name is a valid array. The parameter val can be

a comma separated string which is split into an array of values
or an array.

Optionally, the array is checked for the correct size.

simple_hash_validator (val, name)

Source

# File lib/kramdown/options.rb, line 158
def self.simple_hash_validator(val, name)
  if String === val
    begin
      val = YAML.safe_load(val)
    rescue RuntimeError, ArgumentError, SyntaxError
      raise Kramdown::Error, "Invalid YAML value for option #{name}"
    end
  end
  raise Kramdown::Error, "Invalid type #{val.class} for option #{name}" unless Hash === val
  val
end

Ensures that the option value val for the option called name is a valid hash. The parameter val can be

a hash in YAML format
or a Ruby Hash object.

Option definitions

Constants

ALLOWED_TYPES: Allowed option types.
Definition: Struct class for storing the definition of an option.

Public Class Methods

defaults ()

Source

# File lib/kramdown/options.rb, line 71
def self.defaults
  @defaults ||=
    begin
      temp = {}
      @options.each {|_n, o| temp[o.name] = o.default }
      temp.freeze
    end
end

Return a Hash with the default values for all options.

define (name, type, default, desc, &block)

Source

# File lib/kramdown/options.rb, line 50
def self.define(name, type, default, desc, &block)
  name = name.to_sym
  raise ArgumentError, "Option name #{name} is already used" if @options.key?(name)
  raise ArgumentError, "Invalid option type #{type} specified" unless ALLOWED_TYPES.include?(type)
  raise ArgumentError, "Invalid type for default value" if !(type === default) && !default.nil?
  raise ArgumentError, "Missing validator block" if type == Object && block.nil?
  @options[name] = Definition.new(name, type, default, desc, block)
  @defaults = nil
end

Define a new option called name (a Symbol) with the given type (String, Integer, Float, Symbol, Boolean, Object), default value default and the description desc. If a block is specified, it should validate the value and either raise an error or return a valid value.

The type ‘Object’ should only be used for complex types for which none of the other types suffices. A block needs to be specified when using type ‘Object’ and it has to cope with a value given as string and as the opaque type.

defined? (name)

Source

# File lib/kramdown/options.rb, line 66
def self.defined?(name)
  @options.key?(name.to_sym)
end

Return true if an option called name is defined.

definitions ()

Source

# File lib/kramdown/options.rb, line 61
def self.definitions
  @options
end

Return all option definitions.

merge (hash)

Source

# File lib/kramdown/options.rb, line 82
def self.merge(hash)
  temp = defaults.dup
  hash.each do |k, v|
    k = k.to_sym
    temp[k] = @options.key?(k) ? parse(k, v) : v
  end
  temp
end

Merge the defaults Hash with the parsed options from the given Hash, i.e. only valid option names are considered and their value is run through the parse method.

parse (name, data)

Source

# File lib/kramdown/options.rb, line 96
def self.parse(name, data)
  name = name.to_sym
  raise ArgumentError, "No option named #{name} defined" unless @options.key?(name)
  unless @options[name].type === data
    data = data.to_s
    data = if @options[name].type == String
             data
           elsif @options[name].type == Integer
             Integer(data) rescue raise Kramdown::Error, "Invalid integer value for option '#{name}': '#{data}'"
           elsif @options[name].type == Float
             Float(data) rescue raise Kramdown::Error, "Invalid float value for option '#{name}': '#{data}'"
           elsif @options[name].type == Symbol
             str_to_sym(data)
           elsif @options[name].type == Boolean
             data.downcase.strip != 'false' && !data.empty?
           end
  end
  data = @options[name].validator[data] if @options[name].validator
  data
end

Parse the given value data as if it was a value for the option name and return the parsed value with the correct type.

If data already has the correct type, it is just returned. Otherwise it is converted to a String and then to the correct type.

str_to_sym (data)

Source

# File lib/kramdown/options.rb, line 122
def self.str_to_sym(data)
  data = data.strip
  data = data[1..-1] if data[0] == ':'
  (data.empty? || data == 'nil' ? nil : data.to_sym)
end

Converts the given String data into a Symbol or nil with the following provisions:

A leading colon is stripped from the string.
An empty value or a value equal to “nil” results in nil.

module Kramdown::Options

Available Options

Available `Options`