kramdown

kramdown is a free Ruby library that can be used for parsing a superset of Markdown. It is completely written in Ruby, supports standard Markdown (with some minor modifications) and various extensions that have been made popular by the PHP Markdown Extra package and Maruku.

It is probably the fastest pure-Ruby Markdown converter available (November 2009), being 5x faster than Maruku and about 10x faster than BlueFeather.

The kramdown syntax is based on Markdown, a very easy to write, easy to read markup for writing HTML documents in plain text. Since the basic Markdown syntax has some shortcomings, implementations (especially the PHP Markdown Extra package) have tried to overcome this shortcomings with additional syntax. kramdown supports all features of the original Markdown syntax (albeit with some minor corrections) as well as newer features implemented in the PHP Markdown Extra package and Maruku.

Usage:

The kramdown package provides two ways for using it:

* As a library

 kramdown uses basically the same API as RedCloth, BlueCloth and Maruku:

 require 'kramdown'

 Kramdown::Document.new(text).to_html

 The second parameter to the new call is an options hash for (de)activating certain features. For more information have a look at the API documentation.

* As an application

 Together with the library files a binary called kramdown is shipped which can be used to convert text in kramdown syntax to HTML. It either reads from the files specified as the command line arguments or from the standard input. For example:

 kramdown path/to/kramdown/doc/syntax.page

What is new in this release:

• 2 minor changes:
• Added a parser for Github Flavored Markdown (resolves GH#68 by Arne Brasseur who provided the initial implementation)
• HTML attributes are now output for horizontal lines
• 5 bug fixes:
• The correct encoding on the result string is now set even when the template option is used
• Fixed GH#72, GH#74: All ways to set a header ID now follow the same scheme which is compliant with HTML IDs (except that dots are not allowed) (reported and initial patch by Matti Schneider)
• Fixed GH#73: The default HTML template now has a DOCTYPE and sets the encoding correctly (initial patch by Simon Lydell)
• Fixed GH#67: URLs of link elements are now escaped in the LaTeX converter to avoid problems (patch by Henning Perl)
• Fixed GH#70: Any version of the stringex library is now supported (reported by Simon Lydell)

What is new in version 1.1.0:

• 2 minor changes:
• Footnote markers can now be repeated (resolves GH#62 and GH#63 by Theodore Pak who provided the initial patch)
• The LaTeX acronym package is now used for abbreviations (resolves GH#55 by Tim Besard who provided the initial patch)
• 3 bug fixes:
• Fixed GH#60: Numbers are now recognized in addition to word characters when converting underscores (patch by Trevor Wennblom)
• Fixed GH#66: HTML elements , , and are now converted correctly by the LaTeX converter (patch by Henning Perl)
• Fixed GH#57: Better smart quote handling when underscores are directly after or before quotation marks (reported by Bill Tozier)

What is new in version 1.0.2:

• The tests page has been updated to include relative times in the benchmark so that it is possible to better gauge the performance of kramdown (requested by postmodern).
• The kramdown Wiki now contains a listing of libraries that extend kramdown (idea by postmodern).

What is new in version 1.0.0:

• 4 minor changes:
• New option transliterated_header_ids for transliterating header text into ASCII before generating a header ID which is useful for language like Vietnamese (fixed GH#35, requested by Kỳ Anh)
• The quotation mark entity " now gets converted to its character equivalent when entity_output=as_char.
• A warning is now output for IALs/ALDs that contain not attribute defintion.
• HTML footnote output is changed to use class instead of rel to achieve (X)HTML4/5 compatibility
• 3 bug fixes:
• Fixed GH#38: Encoding problem on 1.9/2.0 due to incompatible encodings - the source string is now converted to UTF-8 before parsing and converted back after converting (reported by Simon Lydell)
• Fixed RF#29647: Abbreviations with non-word first character at start of text lead to exception (reported by Stephan Dale)
• Fixed RF#29704: ID specified on atx style headers were not always correctly detected (reported by Kyle Barbour)

What is new in version 0.14.2:

• 1 minor change:
• New option link_defs for pre-defining link definitions
• 1 bug fix:
• Fixed raised errors on atx headers without text

What is new in version 0.14.1:

• Only HTML elements that must not contain a body (like ) are output in this form, all other elements now use an explicit closing tag (resolves among other things issues with )
• Specifying a block IAL before a definition list now works correctly
• Fixed bug GH#30: Empty body for a definition in a definition list lead to an exception (reported by Mark Johnson)

What is new in version 0.14.0:

• 2 major changes:
• Code language is now specified via .language-CODELANG instead of lang='CODELANG'
• Implemented support for setting language on fenced code block starting line (initial patch by Bran)
• 1 minor change:
• Headers with an ID can be prevented from showing in the TOC by assigning the .no_toc class to them (patch by Tim Bates)
• 1 bug fix:
• Numeric instead of symbolic HTML entities are now the default fallback (patch by Gioele Barabucci)

What is new in version 0.13.5:

• 2 minor changes:
• HTML attributes without values are now supported (fixes bug RF#29490 reported by Nat Welch)
• HTML attributes names are now always converted to lower case for consistency
• 5 bug fixes:
• Fixed Document#method_missing to accept snake_cased class name (patch by tomykaira)
• Fixed problem with missing REXML constant on older Ruby 1.8.6 version (reported by Dave Everitt)
• Fixed bug RF#29520: Valid inline math statement does not trigger math block anymore (reported by Gioele Barabucci)
• Fixed bug RF#29521: HTML math output is now always XHTML compatible (reported by Gioele Barabucci)
• Empty id attributes are now handled better by the HTML and kramdown converters (reported by Jorg Sommer)
• 1 documentation fix:
• Fixed invalid options statement in example on quick reference page (reported by Jorg Sommer)

What is new in version 0.13.4:

• Added a converter that extracts the TOC of a document (requested by Brendan Hay). Note that this is only useful if you use kramdown as a library!
• Fixed a typo: It should be --output and not --ouput (patch by postmodern)
• Fixed HTML converter to correctly output empty span tags (patch by John Croisant)
• Fixed bug RF#29350: Parsing of HTML tags with mismatched case now works
• Fixed bug RF#29426: Content of style tags is treated as raw text now
• HTML converter now uses rel instead of rev to be HTML5 compatible (patch by Joe Fiorini)
• Fixed Ruby 1.9.3 related warnings
• Fixed HTML parser to work around an implementation change of Array#delete_if in Ruby 1.9.3

Requirements:

• Ruby