kramdown Documentation

kramdown is a fast, pure Ruby Markdown superset converter that uses an internal AST (Abstract Syntax Tree) to support multiple formats.

Supported Input Formats:

• kramdown (a Markdown superset)
• Markdown
• GFM (GitHub Flavored Markdown)
• HTML

Supported Output Formats:

• HTML
• kramdown
• LaTeX (which can be used to generate PDF)
• PDF (via Prawn)

kramdown provides a simple Ruby API for converting text into various formats. To convert Markdown text to HTML, require the kramdown library and use the Kramdown::Document.new method followed by .to_html.

require 'kramdown'

Kramdown::Document.new(text).to_html

Kramdown supports Inline Attribute Lists (IAL) to attach attributes like id, class, or custom key-value pairs to inline elements (like spans).

An IAL is defined using the {: syntax.

• IDs: Use # followed by the ID name (e.g., {#my-id}).
• Classes: Use . followed by the class name (e.g., {.my-class}).
• Key-Value Pairs: Use key="value" or key='value' (e.g., {title="Hello"}).
• References: You can also include references within the list.

Example syntax for an inline attribute list: {:.my-class #my-id key="value"}

The Kramdown::Converter::Latex automatically tracks and adds required LaTeX packages to the @data[:packages] set based on the elements encountered during conversion:

• Math: When math elements are processed, the following packages are added: amssymb, amsmath, amsthm, and amsfonts.
• Abbreviations: When abbreviation elements are processed, the acronym package is added.
• Images: When images are processed, the graphicx package is added.
• Tables: When tables are processed, the longtable package is added.
• Footnotes: When footnotes are processed, the fancyvrb package is added.
• Minted Syntax Highlighting: If the :syntax_highlighter option is set to :minted, the minted package is added.

You can extend the default HTML output behavior by creating a subclass of Kramdown::Converter::Html. To change how specific Markdown elements are rendered, override the corresponding convert_NAME methods.

Each overridden method must accept the following parameters:

• el: The element of type NAME to be converted.
• indent: An integer representing the current amount of spaces for indentation (primarily used for block-level elements).

The method must return a String containing the element el formatted as HTML.

Example of overriding a method:

class MyCustomConverter < Kramdown::Converter::Html
  def convert_p(el, indent)
    # Custom paragraph logic here
    "<div class='custom-p'>#{inner(el, indent)}</div>\n"
  end
end

You can extend the functionality of the LaTeX output converter by creating a subclass of Kramdown::Converter::Latex and overriding specific convert_NAME methods.

Each overridden method must follow this signature:

• convert_NAME(el, opts)

Parameters:

• el: The element of type NAME to be converted.
• opts: A hash containing processing options. The key :parent is always present and contains the parent element.

The method must return a string containing the element formatted as valid LaTeX markup.

Kramdown supports Block Attribute Lists (ALD) to attach attributes to block-level elements. An ALD is placed on its own line following a block element.

Syntax: {:<attributes>}

Example:

# My Heading
{: #my-id .my-class}

The converter automatically manages link references and footnotes to produce clean markdown.

1. Link References: When convert_a encounters a link that is an external URL (starting with http or ftp) or contains parentheses, it adds the element to @linkrefs and uses the reference syntax [text][index]. At the end of the conversion process, create_link_defs generates the corresponding [index]: url definitions.
2. Footnotes: When convert_footnote is called, it adds the footnote content to @footnotes. The create_footnote_defs method then generates the [^name]: definitions at the end of the document.
3. Abbreviations: If abbrev_defs are provided in the root options, create_abbrev_defs generates the *[name]: text definitions.

To implement a new parser in Kramdown, you must derive a new class from Kramdown::Parser::Base and place it within the Kramdown::Parser module. This placement is required for Kramdown's auto-detection mechanism to work.

Your subclass must implement the parse method, which contains the actual parsing logic. The parse method is responsible for parsing the content provided in the @source instance variable and building an element tree that is stored in the @root instance variable.

Note that you should not instantiate the parser directly using .new. Instead, use the Base.parse class method, which handles instantiation and execution for you.

The kramdown command-line tool converts Markdown (or other input formats) into various output formats like HTML, LaTeX, or Man pages. It can process one or multiple files provided as arguments. By default, it reads from standard input or files provided via ARGF and outputs to standard output.

Basic Usage:

kramdown [options] [FILE FILE ...]