fast, pure-Ruby Markdown-superset converter


Published on Monday, 25 April 2022

kramdown 2.4.0 released

A minor release bringing a small enhancement to the kramdown converter and some bug fixes.


  • 1 minor change:

    • Allow using a different list indentation (pull request #753 by Carsten Borman)
  • 2 bug fixes:

    • Fixed escaping of colon when converting to kramdown (fixes #751 by Carsten Borman)
    • Fixed setting highlighter class for code spans in HTML converter when using a default language (fixes #752 by Aswhin Maroli)
Published on Friday, 18 March 2022

kramdown 2.3.2 released

This release brings various bug fixes.


  • 2 minor change:

    • Make codespan delimiter available for converters (pull request #748 by cabo)
    • Make first list item marker available for converters (pull request #740 by cabo)
  • 1 bug fix:

    • Fixed handling of top-level text elements when converting from HTML (fixes #749 by numinit)
  • 1 other change:

    • Enhanced documentation for “forbidden_inline_options” configuration option (fixes #750 by Emily Grace Seville)
Published on Thursday, 18 March 2021

kramdown 2.3.1 released

This release brings various bug fixes, one of which fixes a security issue that can potentially lead to remote code execution.


  • 2 minor change:

    • Added rel="footnote" to footnote links (fixes #706 by xplosionmind)
    • Default options are now cached to avoid unnecessary computations (fixes #685 by Aswhin Maroli)
  • 6 bug fixes:

    • Fixed abbreviations handling so that they won’t be replaced in raw HTML tags (fixes #671 by Kaspar Etter)
    • Restricted Rouge formatters to Rouge::Formatters namespace (pull request #708 by Stan Hu)
    • Fixed conversion of empty raw html td/th tags to kramdown (fixes issue #682 by Virgil Ierubino)
    • Fixed LaTeX entity conversion (pull request #681 by aschmitz)
    • Fixed missing block attributes from IAL on standalone images (pull request #668 by Tobin Yehle)
    • Fixed inconsistency in how empty code spans are handle (fixes #704 by cabo)
  • 4 other change:

    • Test on Ruby 2.7 and Ruby 3.0 (pull request #696 by timcraft)
    • Fix rouge test failures due to new syntax (fixes issue #689 by Daniel Leidert)
    • Clarified requirements for rouge option ‘formatter’ (fixes issue #617 by Aswhin Maroli)
    • Removed warning in setup.rb (pull request #673 by Daniel Bair)
Published on Sunday, 28 June 2020

kramdown 2.3.0 released

Although this is a minor version bump there is one breaking change: Parsing of XML processing instructions was removed because they are invalid for HTML5 documents.

This change should only affect a negligible amount of existing kramdown documents since XML processing instructions were never something a normal user would use.

Additionally, CVE-2020-14001 (reported by Javier Rivera) is addressed to avoid problems when using the {::options /} extension together with the ‘template’ option. This means updating is highly recommended!


  • 2 major changes:

    • New option ‘forbidden_inline_options’ to restrict the options allowed with the {::options /} extension. This also addresses the security issue described in CVE-2020-14001.
    • Parsing of XML processing instructions is not done anymore for kramdown documents because they are invalid for HTML5 (fixes issue #660 by Samuel Williams)
  • 1 minor change:

    • Several internal changes with respect to memory usage and performance (PRs #654, #655, #665 by Ashwin Maroli)
  • 2 bug fixes:

    • Extend allowed characters in IDs set with headers to all characters allowed by XML (fixes #658 by Samuel Williams)
    • Fix thread safety issue by moving global state into an instance variable (fixes #663 by Samuel Williams)
  • 1 other change:

    • Documentation fixes and updates (issue #662 by Samuel Williams, PR #656 by Noah Doersing)
Published on Thursday, 23 April 2020

kramdown 2.2.1 released


  • 1 bug fix:

    • Don’t set role=doc-toc in HTML converter because it is invalid for ul/ol (fixes #653 by XhmikosR)
Published on Wednesday, 22 April 2020

kramdown 2.2.0 released

This release is a hotchpotch of many small, internal changes, some minor user visible changes and a few bug fixes. Special thanks to Ashwin Maroli for his many contributions!


  • 5 minor changes:

    • Change output of MathJax math engine to be compatible with MathJax v2 and v3 (fixes issue #626 by Abe Voelker) and wrap it in <div>/<span> tags for attribute assignment (fixes issue #533 by Luc J. Bourhis)
    • Make rexml a dependency due to it not being a default gem in the future (PR #638 by David Rodriguez)
    • Add WAI-ARIA role attributes to TOC and footnotes HTML (PR #646 by Maxime Kjaer)
    • Remove redundant line breaks in HTML output for CJK scripts (fixes issue #587, PR #588 both by Fangyi Zhou); can be enabled via the new option remove_line_breaks_for_cjk
    • Several internal changes with respect to memory usage and performance (PRs #600, #601, #621, #619, #641, #642, #597, #578, #598, #596 by Ashwin Maroli)
  • 4 bug fixes:

    • Fix performance problem on missing space with respect to autolinks (fixes issue #647 by Martijn Stegeman)
    • Allow juxtaposing &[mn]dash; and emphasis (fixes issue #624 by Kevin Bloch, PR #625 by Ashwin Maroli)
    • Fix kramdown converter to better handle markup inside non-convertible HTML tags (PR #614 by Bob Lail)
    • Fix regression for atx header parsing by not requiring whitespace before closing hash marks (PR #652 by Simon Coffey)
  • 3 other changes

    • Make Travis CI integration better (PRs #585 by stephengroat)
    • Documentation fixes (PRs #606 by tom93, #590 by Gleb Mazovetskiy, #629 by Kazuma Furuhashi, issue #649 by Joseph Wong)
    • New rake task and scripts for memory profiling (PRs #607, #608 by Aswhin Maroli)
Published on Thursday, 31 January 2019

kramdown 2.1.0 released

Not much to report, just fixing a problem after the move to frozen strings and enabling the integration of the extension gems in the kramdown binary.


  • 2 minor change:

    • Enable the use of extension gems in the kramdown binary through the new -x/--extension options (issue #569 by Ashwin Maroli)
    • Allow using the Rouge plaintext lexer with the :guess_lang highlighting option (issue #572 and pull request #573 by Ashwin Maroli)
  • 1 bug fix:

    • Fix problem with frozen string when using a codespan inside a table (issue #571 by Matijs van Zuijlen)
Published on Sunday, 20 January 2019

kramdown 2.0.0 released

This is a major release with breaking changes!

The most notable changes are that Ruby 2.3 is now required, Rouge is the new default syntax highlighter and that several extension have been extracted to their own repository and Rubygem.

All extracted extensions are now officially unmaintained - if anybody wants to step in, please contact me.

There are also some minor changes and bug fixes, most notable:

  • Paragraphs with a single image can now be rendered as <figure> elements.

  • Footnote IDs can now be made unique using the new option footnote_prefix. Together with the exposed count of footnotes it is now possible to render multiple documents into one output file:

    require 'kramdown/document'
    total_footnotes = 0
    documents = [
      "footnote[^a][^a]\n\n[^a]: My note\n[^b]: another (ignored) note",
      "footnote[^a][^a]\n\n[^a]: My note\n[^b]: another (ignored) note",
      "footnote[^a][^a]\n\n[^a]: My note\n[^b]: another (ignored) note",
    documents.each do |document|
      options = {footnote_nr: total_footnotes + 1, footnote_prefix: total_footnotes + 1}
      document =, options)
      puts document.to_html
      total_footnotes += document.root.options[:footnote_count]


  • 3 major changes:

  • 4 minor changes:

    • Allow HTML5 style attribute values without quotes for HTML parser (issue #522 and pull request #523 by Dan Allen)
    • Guessing of the syntax highlighting language with rouge is now only performed if the guess_lang option is set
    • Paragraphs with a single image can now be rendered as a <figure> element by specifying the standalone IAL reference (fixes issues #48 by Gilbert Townshend and #98 by Luca Barbato)
    • Add option footnote_prefix for avoiding duplicate IDs when rendering multiple documents (fixes issue #483 by Peter Poole)
  • 3 bug fixes:

    • Add support for single backslash variant of hard line break to the (extracted) GFM parser (issue #519 and pull request #520 by Dan Allen)
    • Don’t use the “plaintext” lexer of rouge
    • Fix updating IAL references so that they get handled correctly
Published on Thursday, 31 May 2018

kramdown 1.17.0 released

This release adds support for another server side math engine based on KaTeX but with an easier installation method. There are also various fixes, the most important one being a change in the Setext and atx style header parsers to prevent performance and potential denial of service problems.

Thanks to all the people working on making kramdown better!


  • 3 minor change:

    • Add new math engine katex for easier server-side conversion (pull requests #489, #510 by Gleb Mazovetskiy)
    • New configuration options --no-config-file and --config-file FILE for the kramdown binary (pull request #499 by ccorn)
    • Add information to AST whether a codeblock is indented or fenced (issue #507 and pull request #508 by Dan Allen)
  • 4 bug fixes:

    • Fix the numeric values of the entities cap and cup (pull request #487 by Ashe Connor)
    • Fix problem with parsing an empty tag inside a table cell while using html_to_native (issue #514 and pull request #515 by Dan Allen)
    • Fix performance issue in Setext and atx style headers when parsing a lot of space (fixes #505 by Dmitry Krasnoukhov, pull request #513 by Gleb Mazovetskiy)
    • Prevent duplicate warning for reference style links with missing link identifier (fixes #492 reported by Gregory Pakosz)
  • 8 documentation and other changes:

    • Expand table of contents example for HTML converter (pull request #484 by Milo Simpson)
    • Use non-deprecated SCSS color function for kramdown homepage (pull request #485 by ccorn)
    • Add usage notes and comparison for KaTeX vs SsKaTeX (pull request #493 by ccorn)
    • Node version 6.0 is now used because of newer mathjax-node requirements (pull request #498 by ccorn)
    • Rakefile adjustments for various math engines (pull request #499 by ccorn)
    • Add more files to .gitignore (pull request #518 by Gleb Mazovetskiy)
    • Remove some unneeded code for Ruby versions < 2.0 (pull request #502 by Ashwin Maroli)
    • Updated the kramdown website to be more privacy-friendly
Published on Wednesday, 29 November 2017

kramdown 1.16.2 released

And another quick bug fix release for a table parsing problem, upgrading is recommended!


  • 1 bug fix:

    • Fix parsing of tables with codespans and escaped pipes (fixes #477, reported by François #Dallaire)
Published on Tuesday, 28 November 2017

kramdown 1.16.1 released

Hot on the heels of 1.16.0 this bug fix release fixes problems with the new GFM task list implementation, so upgrading is recommended!


  • 1 bug fix:

    • Fix the GFM task list implementation (fixes #476, reported by Brandon Zarrella)
Published on Monday, 27 November 2017

kramdown 1.16.0 released

This release brings, amongst other things, support for setting default options for the kramdown binary via a configuration file, two new options (‘typographic_symbols’ and ‘footnote_backlink_inline’) and the new server-side math engine SsKaTeX which doesn’t need the whole NodeJS stack to work properly.

Please also note that the MathjaxNode math engine now relies on the mathjax-node-cli package instead of the mathjax-node package to work correctly. Make sure you update your NodeJS installation accordingly.

Thanks to all the contributors and supporters that made this release possible!


  • 8 minor change:

    • The kramdown binary now supports specifying default options via configuration file (fixes #453 requested by Kyle Barbour)
    • New GFM quirk ‘no_auto_typographic’ for disabling typographic conversions (fixes #459 via pull request #462, both by Kirill Kolyshkin)
    • The MathjaxNode math engine now needs the package mathjax-node-cli to work.
    • New math engine SsKaTeX for server-side rendering via KaTeX (patch #455 by Christian Cornelssen)
    • When using the Rouge syntax highlighter, the formatter option can now be a String (patch #448 by Alpha Chen)
    • New option ‘typographic_symbols’ to control how typographic symbols are output by the HTML and LaTeX converters (fixes #472 requested by Kyle Barbour)
    • New option ‘footnote_backlink_inline’ to allow placing the footnote backlink into the last, possibly nested paragraph or header instead of creating a new paragraph (fixes #454 requested by Kyle Barbour)
    • The GFM parser now supports task lists (fixes #172 and #346, patch #442 by Andrew)
  • 4 bug fixes:

    • Line breaks in a special situation were not respected (fixes #461, reported by Buo-Ren Lin)
    • Fix the RemoveHtmlTags converter to also process footnote content (patch #458 by Maximilian Scherr)
    • Fix bug in paragraph parsing when the ‘html_to_native’ option is used (fixes #466, reported by eddibravo)
    • Fix bug in kramdown converter when an image without a ‘src’ attribute is encountered (patch #470 by Uwe Kubosch)
Published on Friday, 08 September 2017

kramdown 1.15.0 released

The most important change is that this release drops compatibility with Ruby versions < 2.0! Aside from that it includes some bug fixes, so updating is recommended.


  • 2 minor changes:

    • Drop compatibility with Ruby versions < 2.0
    • Make footnote output XML compatible (requested by Kriss Andsten)
  • 4 bug fixes:

    • Apply abbreviation substitution to footnotes (fixes #440, reported by Thomas Leese)
    • Fix TOC entries by removing nested links (fixes #434, reported by Nate Wernimont)
    • Fix problems with brackets in certain situations when using the LaTeX converter (fixes #414, reported by Ryan Koppenhaver)
    • Fix escaping of URLs in the LaTeX converter (reported by Moshe Kamensky in pull request #67)
Published on Monday, 26 June 2017

kramdown 1.14.0 released

This release adds support for rouge 2.x and fixes some minor issues - updating is recommended.


  • 2 minor changes:

    • Adapt syntax highlighter for rouge to support version 1.x and 2.x (pull request #413 by Hirofumi Wakasugi)
    • Alias Kramdown::Converter::HashAST to Kramdown::Converter::HashAst so that the convenience method on Kramdown::Document works (fixes #435, requested by Hirofumi Wakasugi)
  • 1 bug fix:

    • Fix problem with GFM header ID generation when << or >> is used (reported by Parker Moore)
Published on Saturday, 07 January 2017

kramdown 1.13.2 released

This release fixes some minor issues - updating is recommended.


  • 3 bug fixes:

    • Fix footnote link spacing to use non-breaking space (pull request #399 by Martyn Chamberlin)
    • Show warning for unreferenced footnote definitions (fixes #400 reported by Kyle Barbour)
    • Fix test cases with respect to Ruby 2.4 (fixes #401 reported by Connor Shea)
Published on Friday, 25 November 2016

kramdown 1.13.1 released

This release fixes the GFM header ID generation for more cases, updating is very recommended.


  • 1 bug fix:

    • Fix GFM header ID generation when code spans, math elements, entities, typographic symbols or smart quotes are used (fixes #391 reported by Nick Fagerlund)
Published on Sunday, 20 November 2016

kramdown 1.13.0 released

The biggest change in this release is the introduction of a converter for man pages. Although there already exist two solutions (ronn and kramdown-man), both are not completely satisfactory:

  • Ronn doesn’t use standard Markdown syntax for all elements.
  • kramdown-man only converts a subset of the available element types.

The new man page converter uses standard kramdown syntax and supports nearly all element types, including tables.

This release also brings some enhancements for the GFM parser. One thing to note is that the header ID generation is now more compatible to GFM which also means that some IDs will be different - so check the documents on which you use the GFM parser, especially when you are using Jekyll or Github Pages.

Organizational-wise, issues and pull requests on Github that pertain to feature requests have been closed and are now tracked through a dedicated kramdown project on Github.


  • 4 minor changes:

    • Add new converter for man pages
    • Header ID generation for the GFM parser is now more compatible to GFM (fixes #267, requested by chadpowers)
    • Update to the MathJax math engine to allow formatting the preview as code / pre > code (pull request #372 by Florian Klampfer)
    • Allow tabs in table separator lines (pull request #370 by Shuanglei Tao)
  • 2 bug fixes:

    • Compactly nested lists are now handled correctly after fixing a bug in indentation detection (fixes #368 reported by Christopher Brown)
    • GFM parser: Allow indenting the delimiting lines of fenced code blocks for better GFM compatibility (pull request #369 by Shuanglei Tao)
  • 2 other fixes and enhancements:

    • Added information on how to run tests to (fixes #377 reported by Aron Griffis)
    • Added information about how to use KaTeX with the MathJax math engine (fixes #292 reported by Adrian Sieber, information by Dato Simó)
Published on Monday, 15 August 2016

kramdown 1.12.0 released

This release features two enhancements for definition lists:

  1. IALs can now be applied to definition terms:

    {:.classy} term
    : and its definition
  2. IDs for definition terms can now be created automatically (similar to header IDs) and optionally assigned a prefix:

    : definition
    : definition
    : definition
    : definition

Furthermore, compatibility of the GFM parser has been improved in regards to list/blockquotes/codeblocks that are used directly after a paragraph (i.e. without a blank line).


  • 4 minor change:

    • Allow using an IAL for definition terms (<dt>) as is already possible with definitions themselves (<dd>)
    • Added automatic generation of IDs (with optional prefix) for terms of definition lists (fixes #355, requested by Greg Wilson)
    • Removed obfuscation for e-mail links (fixes #343, requested by Anton Tsyganenko)
    • New option ‘gfm_quirks’ for enabling/disabling parsing differences of the GFM parser with respect to the kramdown parser
  • 4 bug fixes:

    • Added support for HTML5 element <main> (fixes #334, reported by Jean-Michel Lacroix)
    • Fixed math element output for HTML converter when no math engine is set (fixes #342, reported by Adrian Sampson)
    • Fixed problem when using custom HTML formatter for syntax highlighter rouge (fixes #356, patch by Alexey Vasiliev)
    • Better compatibility with GFM when lists/blockquotes/codeblocks are used directly after a paragraph (fixes #336 (reported by Shuanglei Tao), #359 (reported by Matti Schneider) via the patch #358 by Shuanglei Tao)
  • 3 other fixes and enhancements:

    • Added some more examples for how list indentation works (fixes #353, requested by Robbert Brak)
    • Using RbConfig instead of deprecated Config for determining data directory (fixes #345, patch by Cédric Boutillier)
    • JRuby is now also tested via TravisCI (fixes #363, patch by Shuanglei Tao)
Published on Sunday, 01 May 2016

kramdown 1.11.1 released

This release fixes an emphasis parsing regression introduced in the last version.


  • 1 bug fix:

    • Fixed emphasis parsing regression (fixes #333, reported by Marcus Stollsteimer)
Published on Sunday, 01 May 2016

kramdown 1.11.0 released

This release fixes some bugs and includes one minor change in regards to HTML syntax highlighting.


  • 1 minor change:

    • The syntax highlighting language is now always included in the output as class name even if a syntax highlighter is used (fixes #328, requested by SLaks)
  • 3 bug fixes:

    • Fixed the GFM fenced code block parser to correctly split a provided highlighter name into language name and options parts
    • Fixed problem with underscores being processed even if inside a word (fixes #323, reported by Haruki Kirigaya)
    • Fixed HTML/XML parser to correctly, case sensitively parse XML (fixes #310, reported by cabo)
  • 2 other fixes:

    • Updated copyright year (fixes #331, reported by Oscar Björkman)
    • Updated supported Ruby version on installation page (reported by cabo)
Published on Wednesday, 02 March 2016

kramdown 1.10.0 released

This release brings the usual bug fixes but also support for the strikethrough syntax in the GFM parser as well as some enhancements regarding the specification of language names for syntax highlighting purposes.


  • 4 minor changes:

    • Support for the math-engine MathJax-Node was updated to use the new mathjax-node package (fixes #313, pull request by Tom Thorogood)
    • URL query parameters can now be appended to language names specified in fenced code blocks if the syntax highlighting engine accepts them (fixes #234)
    • Added strikethrough syntax to the GFM parser (fixes #184 and #307; initial pull request by Diego Galeota, updated by Parker Moore)
    • Allow almost all characters in class names that are defined via a special syntax (fixes #318, requested by cabo)
  • 4 bug fixes:

    • Fixed a problem where would only accept the symbol :input but not the string ‘input’ as valid key (fixes #312, pull request by Sun Yaozhu)
    • Fixed inconsistent behavior: Empty link text is now also allowed for normal links, not just images (fixes #305, reported by cabo)
    • The HTML5 <mark> element is now recognized as span level element (fixes #298, reported by Niclas Darville)
    • Fixed problem where e-mail autolinks containing an underscore character were not correctly recognized (fixes #293, reported by erikse)
  • 3 other fixes:

    • Fixed missing package update statement for Travis (by Parker Moore)
    • Add some more documentation regarding MathJax (fixes #296, pull request by Christopher Jefferson)
    • Fixed bad link in API documentation (fixes #315, reported by Tom MacWright)
Published on Thursday, 01 October 2015

kramdown 1.9.0 released

This release contains some minor updates and bug fixes.


  • 3 minor changes:

    • The Rouge syntax highlighter can now be enabled/disabled for spans and/or blocks and options can now be set for both spans and blocks as well as only for spans or only for blocks (fixes #286, requested by Raphael R.)
    • Setting the ‘footnote_backlink’ option to an empty string now completely suppresses footnotes (fixes #270, requested by Kyle Barbour)
    • New converter HashAST for creating a hash from the internal tree structure (fixes #275, pull request by Hector Correa)
  • 1 bug fix:

    • When using the ‘hard_wrap’ option for the GFM parser, line numbers were lost (fixes #274, pull request by Marek Tuchowski)
Published on Saturday, 04 July 2015

kramdown 1.8.0 released

This release contains only some minor updates and bug fixes.


  • 4 minor changes:

    • The LaTeX converter now uses \texttt instead of \tt for code spans (fixes #257, reported by richard101696)
    • New option footnote_backlink for changing the backlink of footnotes in the HTML converter (fixes #247, requested by Benjamin Esham)
    • A quote directly followed by an ellipsis is now converted into an opening quotation mark (fixes #253, requested by Michael Franzl)
    • Removed warning for self-closing HTML elements that are not self-closed (fixes #262, requested by Gregory Pakosz)
  • 3 bug fixes:

    • Fixed #251: The special character sequence \` now works correctly when used in footnotes or headers that appear in the table of contents (reported by Peter Kehl)
    • Fixed #254: kramdown crashed on encountering a table with multiple consecutive separator lines (reported by Christian Kruse)
    • Fixed #256: Certain footnote definitions and codeblocks lead to crashes or unneeded backtracking in the regular expression engine - fixed by using atomic grouping (reported by Ali Ok)
Published on Monday, 27 April 2015

kramdown 1.7.0 released

This release brings among other things support for the ‘minted’ syntax highlighter for LaTeX and a new math engine based on MathJax-Node that outputs to MathML.


  • 4 minor changes:

    • The syntax highlighter ‘minted’ for the LaTeX converter is now available (fixes issue #93, initial patch #242 by l3kn)
    • A new math engine based on MathJax-Node that outputs to MathML is now available (patch #240 by Tom Thorogood)
    • Fixed #244, #246: Fenced code blocks now allow a dash in the code language name (requested and patched by Dennis Günnewig)
    • The option list in the man page as well in the output of kramdown --help is now sorted.
  • 2 bug fixes:

    • Fixed #230: Warning message for method in lib/kramdown/utils/configurable.rb will not show anymore (reported by Robert A. Heiler)
    • Fixed #239: Handling of single/double quotes in reference style links now follows the same rules as with inline links (reported by Josh Davis)
Published on Saturday, 28 February 2015

kramdown 1.6.0 released

This release contains many fixes and minor enhancements as well as one major goodie that comes with a small caveat: block IALs can now be applied to link and abbreviation definitions!

It may not sound like much but allowing block IALs to be applied to link definitions alleviates the problem that additional attributes could only be specified via span IALs. Now such attributes can be stored together with the URL and title at the link definition, for example:

This is a ![resized image].

[resized image]: some_image.jpg "with a title"
{: height="36px" width="36px" style="border: 1px solid green"}

There is one small caveat, though. Regard the following construct:

block element, e.g. a paragraph

The block IAL would have been applied to the paragraph in previous versions but now it is applied to the link definition. However, such a construct is not very likely encountered in the real world.


  • 7 minor changes:

    • Block IALs can now be applied to link and abbreviation definitions (inspired by issue #194 from cabo)
    • The syntax highlighting engine for Rouge now allows custom formatter classes to be used (issue #214, requested by BackOrder)
    • The MathJax math engine now allows adding previews (issue #225, requested by jethrogb)
    • The “toc_levels” option can now also take a Range object (pull request #210 by Jens Krämer)
    • The generated table of contents of the HTML converter now contains ID attributes on the links so that back-references can be used (issue #195, requested by Ciro Santilli)
    • A warning is now generated when duplicate HTML attributes are detected (issue #201, requested by winniehell)
    • Updated used version of prawn to 2.0.0
  • 8 bug fixes:

    • Fixed #192: Emphasis by using underscore sometimes wrongly worked within a word (reported by Michael Franzl)
    • Fixed #198: Empty alt attributes on <img> tags are now correctly handled by the kramdown converter (reported by winniehell)
    • Fixed #200: Trailing whitespace is now really removed in paragraphs (reported by winniehell)
    • Fixed #220: HTML blocks with attributes weren’t correctly detected when directly after another block (reported by Bill Tozier)
    • Fixed #199: Empty title attributes are now ignored for images when using the kramdown converter (reported by and pull request #206 from winniehell)
    • Leading and trailing white space from math statements is now stripped as the whitespace sometimes lead to LaTeX conversion errors
    • Fixed #226: Class names may now start with a dash in IALs/ALDs (reported by Adam Hardwick)
    • Multiple consecutive block IALs before an element are now correctly processed
Published on Saturday, 25 October 2014

kramdown 1.5.0 released

This release brings the addition of Rouge as supported syntax highlighting engine besides Coderay as well as support for MathML output in the HTML converter through the libraries Ritex or itex2MML as alternatives to MathJax.

By restructuring the code it will now be very easy to add other syntax highlighters or math engines in the future.

Please also note that the old ‘coderay_*’ options are still supported but they are deprecated as of now. It is recommended to use the new ‘syntax_highlighter’ and ‘syntax_highlighter_opts’ options instead. The latter also take precedence over the former ‘coderay_*’ options.


  • 6 minor changes:

    • Syntax highlighters are now configurable via the new ‘syntax_highlighter’ option.
    • Rouge has been added as alternative to Coderay for syntax highlighting (requested originally as Pgyments support in #24 by Jonathan Martin and then #68 by Eric Mill and #141 by Jeanine Adkisson).
    • The <div> tag surrounding syntax highlighted code now gets a class highlighter-NAME attached where NAME is the syntax highlighter used (requested in #76 by Marvin Gülker)
    • Math engines are now configurable via the new ‘math_engine’ option.
    • A math engine based on Ritex for MathML output has been added (requested by Tom Thorogood who provided the initial pull request #169).
    • A math engine based on itex2MML for MathML output has been added (requested by Tom Thorogood)
  • 2 bug fixes:

    • Fixed #171: Hard line wrapping in the GFM parser didn’t work correctly when an inline element started a new line (reported by Zach Ahn)
    • Fixed #173: The HTML <button> element is now recognized as span-level element (pull request by Morandat)
Published on Tuesday, 16 September 2014

kramdown 1.4.2 released

This release fixes some bugs and brings location information to more element types. A performance regression introduced in 1.4.0 has also been fixed – see the graphs of the benchmarks.


  • 1 minor change:

    • Closes #166: Location information is now available in nearly all elements (requested by Mark Harrison)
  • 6 bug fixes:

    • Option ‘footnote_nr’ is now correctly supported by the LaTeX converter
    • Fixes #161: Footnotes inside footnotes are now recognized (reported by Nate Cook)
    • Fixes #164: Escaped hash signs at the end ot atx headers now work (reported by Alexander Köplinger)
    • Fixes #158: Sometimes line numbers were incorrectly reported due to the usage of a false method (reported by Mark Harrison)
    • Fixes #152: Line breaks are now recognized in GFM parser when hard_wrap is off (reported by mathematicalcoffee)
    • Fixes #155: HTML <details> and <summary> tags are now interpreted as elements with block content model (reported by cheloizaguirre)
Published on Saturday, 02 August 2014

kramdown 1.4.1 released

This release brings better line number reporting in warning messages and fixes some bugs.


  • 1 minor change:

  • Improved line number reporting in warning messages

  • 3 bug fixes:

  • Fixed #147: HTML <textarea> tags were not parsed as block level elements (reported by Nguyen Anh Quynh)
  • Fixed #144: HTML <u> tags were not recognized as span level elements (reported by Yong-Yeol Ahn)
  • Fixed #148: GFM input and PDF output was missing in CLI help text (pull request by Sebastian Boehm)
Published on Wednesday, 18 June 2014

kramdown 1.4.0 released

This release fixes all outstanding bugs, so it is recommended to update. The one new feature is that the location of the footnotes can now be defined by attaching the reference name “footnotes” to an ordered or unordered list (like with the table of contents).

One major problem was that unescaped pipe characters | often led to involunatary tables. This release introduces some changes that should prevent this for more cases than before. Additionally, since this is the most common problem case, it is advised to use \vert instead of | in inline math statements. Both do the same in LaTeX but the latter may inadvertently start a table, so better use the former!


  • 2 minor changes:

    • Implemented #106: Users can now define the location of the footnotes (feature request by Matt Neuburg)
    • Merged #97: rake gemspec now generates a local kramdown.gemspec file (pull request by Nathanael Jones)
  • 9 bug fixes:

    • Fixed #128: <script> tags are now removed from math statements when converting to HTML (reported by Trevor Wennblom)
    • Fixed #129: Internal state of custom string scanner class was corrupted due to backtracking which led to problems with location tracking (reported by Mark Harrison)
    • Fixed #112: The content of <kbd>, <samp> and <var> is now also treated as raw HTML (reported by Denis Defreyne)
    • Fixed #114: Added missing HTML entity names (reported by Tomer Cohen)
    • Fixed #101: Fixed exception on missing alignment information when parsing HTML tables to native kramdown elements (initial pull request by zonecheung)
    • Fixed #117: The GFM parser now needs a space after a hash so that the line is identified as an atx header (reported by Trevo Wennblom)
    • Fixed #131: Location tracking in nested list was incorrect (reported by Mark Harrison)
    • Fixed/Worked around #23, #46, #107, #134: Parsing math blocks that contain pipe characters now works, adjusting inline math statements to use \vert instead of | resolves the other problems (reported by many)
    • Fixed #135: Escaped pipes in alternative text of image links were not correctly escaped (reported by Philipp Rudloff)
Published on Monday, 17 March 2014

kramdown 1.3.3 released

This release just fixes a bug with the default HTML document template.


  • 1 bug fix:

    • The string charset= was missing from a <meta> tag in the HTML document template.
Published on Sunday, 16 February 2014

kramdown 1.3.2 released

This release brings some small performance optimizations and the ability to define custom rules for updating predefined link definitions. The latter is used in webgen 1.2.1 to drastically reduce the time for converting kramdown documents that use a lot of predefined link definitions.


  • 2 minor changes:

    • Small (mostly string) performance optimizations
    • New method Kramdown::Parser::Kramdown#update_link_definitions method
Published on Sunday, 05 January 2014

kramdown 1.3.1 released

This release mitigates a performance problem introduced due to the storing of the location information. On Rubies prior to 2.0 the performance impact was negligible but on Ruby 2.0 and 2.1 performance was much worse.

With the fix the performance is not on prior levels but much better. See the tests page which has been updated with current performance graphs.

Also note that for PDF support you now need the newer Prawn versions (i.e. 0.13.x instead of 1.0.0.rc*)!


  • 1 minor change:

    • Now depending on the newer Prawn versions, i.e. 0.13.x
  • 1 bug fix:

    • Mitigated a performance regression on Ruby 2.0 and Ruby 2.1 (introduced due to the storing of the location information)
Published on Sunday, 08 December 2013

kramdown 1.3.0 released

This release brings a pure Ruby PDF converter for kramdown based on the Prawn library. The PDF output can be customized by sub-classing the converter or by using a template file that adjusts the converter object.


  • 1 major change:

    • A pure Ruby PDF converter based on Prawn is now available
  • 7 minor changes:

    • New option ‘auto_id_stripping’ can be used to strip HTML and other formatting before converting a header text to an ID (fixed GH#90 requested by Tuckie)
    • New option ‘hard_wrap’ for configuring the line break behaviour of the GFM parser (GH#83, patch by Brandur)
    • Location information (only line numbers) are now available in the :location option on most kramdown elements (GH#96 patch by Jo Hund)
    • Minitest 5.x is now used for testing.
    • A converter class can now specify whether a template should be applied before, after or before and after the conversion.
    • If a file specified with the “template” option is not found and the option starts with “string://”, the rest is assumed to be the template.
    • Unknown option keys are now passed through and not removed anymore
  • 5 bug fixes:

    • Fixed GH#77: Line break inside inline math statement now works correctly (reported by memeplex)
    • Fixed problem with line breaks in GFM parser
    • Fixed GH#95: Option coderay_bold_every now also accepts the value false (reported by Simon van der Veldt)
    • Fixed GH#91: Template extension is now the same as the converter name (initial patch by Andreas Josephson)
    • Fixed output of consecutive em/strong elements in kramdown converter
  • 3 documentation fixes:

    • The kramdown website is now hosted at - please update your bookmarks!
    • Fixed GH#80: Typo in (patch by Luca Barbato)
    • Fixed GH#81: Typo in options documentation (patch by Pete Michaud)
  • Deprecation notes:

    • Using .convertername instead of .converter_name is deprecated and will be removed in 2.0
    • The option ‘auto_id_stripping’ will be removed in 2.0 because it will be the default.
Published on Saturday, 31 August 2013

kramdown 1.2.0 released

Some people wanted to see Github Flavored Markdown features in kramdown for a long time and now the waiting is over, thanks to the new GFM parser by Arne Brasseur.

Aside from this new feature some bugs were also fixed. One that may have affected many people was the missing support for new stringex library versions.


  • 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)
Published on Tuesday, 02 July 2013

kramdown 1.1.0 released

This is just an incremental release bringing two new features and several bug fixes.


  • 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 <i>, <b>, <em> and <strong> 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)
Published on Thursday, 09 May 2013

kramdown 1.0.2 released

This release fixes some bugs; updating is recommended.

Some notes:

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


  • 4 bug fixes

    • Fixed GH#51: Try requiring a parser/converter library based on the specified input/output name (requested by postmodern)
    • Fixed GH#49: Convert non-breaking space to ~ for LaTeX converter (patch by Henning Perl)
    • Fixed GH#42: No more warning for IALs/ALDs/extensions without attributes (reported by DHB)
    • Fixed GH#44: Removed trailing whitespace in link definition for kramdown converter (patch by Marcus Stollsteimer)
Published on Monday, 11 March 2013

kramdown 1.0.1 released

This release just fixes a bug where kramdown was modifying the input string, so updating is recommended.


  • 1 bug fix

    • Fixed GH#40: Input string was unintentionally modified
Published on Sunday, 10 March 2013

kramdown 1.0.0 released

Finally! After four years of development I proudly present you kramdown 1.0.0!

Naturally, it is recommened to update to this version.

Although the version number now starts with one, the changes from the last release are mostly bug fixes and some small changes. The biggest change is the license change: Until now kramdown was released under the GPL but starting from 1.0.0 it is released under the MIT license!

The MIT license allows the use of kramdown in a commercial setting. However, if you are using kramdown in a commercial setting, I ask you to contribute back any changes you make for the benefit of the community and/or to make a donation - thanks in advance!


  • 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 &quot; 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)
Published on Sunday, 20 January 2013

kramdown 0.14.2 released

This release adds the possibility to pre-define link definitions via the new option link_defs. Apart from that one bug was fixed.

It is recommened to update to this version.

On a side note the kramdown homepage has been updated to show a menu of the available documentation pages when viewing a documentation page. And a documentation page showing all available options has been added.


  • 1 minor change

    • New option link_defs for pre-defining link definitions
  • 1 bug fix

    • Fixed raised errors on atx headers without text
Published on Friday, 30 November 2012

kramdown 0.14.1 released

This is just a bug fix release and it is recommened to update to this version.


  • 3 bug fixes

    • Only HTML elements that must not contain a body (like <br />) are output in this form, all other elements now use an explicit closing tag (resolves among other things issues with <i>)
    • 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)
Published on Sunday, 16 September 2012

kramdown 0.14.0 released

First of all please note that this release contains a backwards-incompatible change: The syntax for specifying a code language for a code block or code span has changed. Instead of using lang='CODELANG' one has to use .language-CODELANG now.

This change has been introduced to avoid problems because the lang="..." attribute is used by HTML for other purposes than setting the code language. Furthermore using .language-CODELANG is also proposed by HTML5 and it seems to be a good way to achieve the needed functionality.

Other changes in this release include the possibility of setting the code language on the starting line of a fenced code block and a way of excluding certain headers from the table of contents by assigning the .no_toc class to them.


  • 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)
Published on Friday, 31 August 2012

kramdown 0.13.8 released

This release brings two new options (one for adjusting header levels and the other for enabling/disabling coderay). And the usual bug fixes.


  • 2 minor changes

    • New option header_offset for offsetting all header levels (initial patch by Michal Till)
    • New option enable_coderay for enabling/disabling coderay (initial patch by Bran)
  • 5 bug fixes

    • Reserved HTML characters in abbreviation titles are now correctly output (patch by Alex Tomlins)
    • Similar abbreviations (like CSS and CSS3) are now correctly parsed
    • Fixed bug RF#29626: Text of mailto-link was sometimes wrongly obfuscated (reported by B Wright)
    • Fixed known Ruby 1.9.3 problem with RakeTest task (patch by Gioele Barabucci)
    • Fixed double output of ‘markdown’ attribute on HTML elements in kramdown converter
  • 1 documentation change

    • README file is now called and uses kramdown syntax (patch by Bran)
Published on Sunday, 03 June 2012

kramdown 0.13.7 released

This release, aside from fixing bugs and some other minor changes, adds a new converter for removing HTML tags from an element tree. This means that one can now do

kramdown -i html -o remove_html_tags,kramdown my_document.html

and get a nice kramdown document from a full HTML document!


  • 1 major change

  • 3 minor changes

    • Updated kramdown binary to support multiple, chained output formats
    • Added a new option for setting a default coderay highlighting language (requested by Lou Quillio)
    • Feature request RF#29575: Added support for &shy; soft-hyphen entity (requested by Alexander Groß)
  • 5 bug fixes

    • Fixed bug RF#29576: Footnotes in headers resulted in duplicated id attr in TOC (reported by korthaerd)
    • Multi-line titles in links are now correctly parsed
    • DOCTYPE declaration is now correctly parsed independent of case
    • Setting of nil options works now by using the String ‘nil’
    • Fixed table-of-content test cases (test went green although the meaning of the test was not satisfied due to copy-paste - d’oh!)
  • 1 documentation fix

    • Fixed bug RF#29577: sidebar link to news page was broken for HTML pages in sub directories (reported by korthaerd)
Published on Wednesday, 09 May 2012

kramdown 0.13.6 released

This is just a bug fix release and it is recommened to update to this version.


  • 2 bug fixes

    • Fixed a problem with CDATA sections appearing in MathJax output (reported by Xi Wang, see github commit)
    • Fixed bug RF#29557: Parsing fails with lists that contain an empty list item (reported by Juan Romero Abelleira)
Published on Sunday, 19 February 2012

kramdown 0.13.5 released

This is mostly a bug fix release and it is recommened to update to this version.

The kramdown homepage has also be updated visually. This should provide a better reading experience for mobile and small-screen devices.


  • 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 Jörg Sommer)
  • 1 documentation fix:

    • Fixed invalid options statement in example on quick reference page (reported by Jörg Sommer)
Published on Friday, 16 December 2011

kramdown 0.13.4 released

This is mostly a bug fix release and it is recommened to update to this version.


  • 1 minor change:

    • 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!
  • 7 bug fixes

    • 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
Published on Friday, 06 May 2011

kramdown 0.13.3 released

This is just a bug fix release and it is recommened to update to this version.


  • 1 minor change:

    • Added support for correctly parsing more HTML5 elements (requested by Bernt Carstenschulz)
  • 10 bug fixes:

    • Table line |a|`b` was parsed as |a`b` (patch by Masahiro Kitajima)
    • Table line |`a` lead to error condition (patch by Masahiro Kitajima)
    • Added OrderedHash#dup to fix a problem when converting a document more than once (reported by Michael Papile)
    • Fixed places where the document tree was modified during conversion
    • Fixed bug in LaTeX image element converter that was introduced in a former release (reported by Michael Franzl)
    • Fixed problem with block HTML tag being treated as header text
    • Fixed problem with footnotes in LaTeX tables – now using longtable instead of tabular environment (reported by Michael Franzl)
    • The style attribute is now used for outputting table cell alignments in HTML instead of using the deprecated col tags
    • Fixed HTML-to-native conversion of unsupported HTML elements
    • Fixed kramdown converter to correctly output table cells with attributes
  • 1 documentation fix:

    • Some HTML tags were not properly escaped on the quick reference page (reported by Yasin Zähringer)
Published on Monday, 21 February 2011

kramdown 0.13.2 released

This release just fixes a problem when parsing long paragraphs/blockquotes under Ruby 1.8.


  • 1 bug fix:

    • Fixed bug RF#28917: Regexp buffer overflow when parsing long paragraphs or blockquotes under Ruby 1.8 (reported by Michael Fischer)
Published on Saturday, 22 January 2011

kramdown 0.13.1 released

The focus of this release was bringing kramdown one step closer to the 1.0 release. The API hasn’t changed so this is a drop-in replacement for the previous version of kramdown.

If you think that

  • kramdown is still missing an important syntax found in another Markdown implementation,
  • the API doesn’t feel right,
  • or anything else is missing or should be changed for the 1.0 release,

please tell us so by writing to!


  • 3 minor changs:

    • The LaTeX converter now inserts \hypertarget commands for all elements that have an ID set. The normal link syntax can be used to link to such targets (requested by David Doolin)
    • New option smart_quotes for specifying how smart quotes should be output (requested by Michael Franzl)
    • Any character except a closing bracket is now valid as link identifier (this makes this part of the kramdown syntax compatible to Markdown syntax)
  • 10 bug fixes:

    • Fixed error when parsing unknown named entities (reported by David Doolin)
    • Added entity definitions for entities &ensp;, &emsp; and &thinsp; (patch by Damien Pollet)
    • Block HTML line was incorrectly recognized as table line (reported by Piotr Szotkowski)
    • Fixed bug RF#28809: Empty <a> tags are were output as self-closed tags (reported by Tim Cuthbertson)
    • Fixed bug RF#28785: Name of default template in documentation for template option was false (reported by Matthew Bennink)
    • Fixed bug RF#28769: span extension in list item wrongly triggered list item IAL parser (reported by Yann Esposito)
    • The table row parser has been fixed so that it does not use pipes which appear in <code> tags as cell separators anymore (like it is done with the native code span syntax)
    • Fixed bug where converting <em> and <strong> tags to native elements was wrongly done
    • Fixed calculation of cell alignment values when converting HTML tables to native ones, <col/> tags are now correctly used
    • HTML Tables are now only converted to native tables if all table rows have the same number of columns.
  • 1 deprecation note:

    • Removed deprecated option toc_depth – use the option toc_levels instead.
Published on Monday, 01 November 2010

kramdown 0.12.0 released

Some changes in the last release of kramdown lead to a performance drop. Therefore some performance optimizations have been done resulting in about 15% less created objects (which reduces the garbage collection pressure) and quite a performance gain (this version of kramdown is the faster than any previous version when using Ruby 1.9.2) – see the tests page for detailed information.

Aside from the performance optimizations, a Markdown-only parser based on the kramdown parser has been added

The “internal” API (which is currently everything except the Kramdown::Document class) has changed again and developers may therefore need to update their extensions! The API changes now allow parsers and converters to be used without a Kramdown::Document class since this class is just provided for convenience. All the needed information is now stored in the element tree itself. Information that has no direct representation as an element is stored in the options of the root element (e.g. abbreviation definitions). More information can be found in the API documentation.

The API should now be relatively stable and once kramdown reaches 1.0.0, the final API will only be changed in backwards compatible ways.


  • 1 major change:

    • Added Markdown-only parser
  • 6 minor changes:

    • Angle brackets can now also be escaped
    • Pipe characters in code spans that appear in tables do not need to be escaped anymore
    • New option toc_levels for specifying the header levels used for the table of contents (requested by Rick Frankel, RF#28672)
    • MathJax instead of jsMath is now used for math output in the HTML converter
    • New option latex_headers for customizing the header commands for the LaTeX converter
    • Removed parsing of HTML doctype in HTML parser
  • 6 bug fixes:

    • Fixed output of paragraphs starting with a right angle bracket in the kramdown converter
    • Invalid span IALs are now left alone and not removed anymore
    • Option entity_output is now respected when outputting a non-breaking space for emtpy table cells in the HTML converter (reported by Matt Neuburg)
    • Fixed bug where a block IAL before a block HTML element was ignored (reported by Matt Neuburg)
    • Fixed bug where block IALs were falsely applied to nested elements (reported by Matt Neuburg)
    • Fixed bug RF#28660: Converting <div><br /></div> from HTML to kramdown resulted in stack trace (reported by Garrett Heaver)
  • 1 deprecation note:

    • The option toc_depth is replaced by the new option toc_levels and will be removed in the next version.
Published on Friday, 01 October 2010

kramdown 0.11.0 released

The biggest change in this release is the implementation of the “lazy syntax” which allows one to not use the correct indent or block marker and still continue a paragraph, blockquote, … The original Markdown syntax allows this and it was requested that kramdown allows this, too. However, the main reason for adding this syntax to kramdown is not to encourage authors to be lazy but to allow kramdown texts to be hard-wrapped by other applications (think, for example, email programs). Therefore you shouldn’t make active use of this feature when creating a kramdown document!

Another important, though minor, change is that invalid HTML tags and extensions are not removed anymore. This is done because of the general rule that unrecognized elements are treated as simple text.

Note: The “internal” API (which is currently everything except the Kramdown::Document class) has changed and developers may therefore need to update their extensions!


  • 3 major changes:

    • Line wrapping a.k.a. “lazy syntax” is now supported (requested by Shawn Van Ittersum)
    • Link URLs in inline links and link definitions may now also contain spaces, even if not enclosed in angle brackets (requested by Matt Neuburg)
    • The kramdown converter produces nicer output, using the new option line_width
  • 9 minor changes:

    • The HTML converter does not escape the quotation mark in code blocks anymore (requested by Matt Neuburg)
    • The order of HTML attributes and attributes defined via IALs and ALDs is now preserved (requested by Matt Neuburg)
    • Syntax highlighting is now supported in code spans when using the HTML converter (requested by Josh Cheek)
    • Updated nomarkdown extension and converters to support restricting the output to certain or all converters
    • Colons are now allowed in ID names for ALDs and IALs
    • Tables and math blocks now have to start and end on block boundaries
    • The table syntax was relaxed to allow table lines that don’t start with a pipe character (to be more compatible with PHP Markdown Extra tables)
    • HTML elements <b> and <i> are now converted to <strong> and <em> when using HTML-to-native conversion
    • The document.html template now uses the text of the first not-nested header as title text
  • 9 bug fixes:

    • The LaTeX converter now removes trailing whitespace in footnotes (reported by Michael Franzl)
    • Fixed bug RF#28429: HTML output of iframe HTML element was invalid (reported by Matthew Riley)
    • Fixed bug RF#28420: LaTeX converter shouldn’t escape the content of the nomarkdown extension (reported by Bj Wilson)
    • Fixed bug RF#28469: HTML “document” template did not work (reported by Vofa Ethe)
    • Fixed bug: HTML/kramdown output of textarea HTML element was invalid (reported by John Muhl)
    • Invalid or unknown extension tags are now left alone and not removed anymore
    • Invalid HTML tags are now left alone and not removed anymore
    • Fixed a minor problem in list parsing which arised due to compact nested list detection
    • Link/Abbreviation/Footnote definitions as well as extensions, ALDs and block IALs now work correctly as block separators
  • 1 deprecation note:

    • The option numeric_entities has been removed
Published on Monday, 19 July 2010

kramdown 0.10.0 released

This release contains many small changes and improvements as well as many bug fixes, thanks to all the people on the kramdown mailing list!


  • Minor changes:

    • The LaTeX converter now also outputs the element attributes on the end tag (requested by Michael Franzl)
    • New option entity_output for specifying how entities should be output
    • The underscore in the option names is now replaced with a hyphen for nicer CLI option names
    • Paragraphs that contain only an image are converted to figures in the LaTeX converter (requested by Michael Franzl)
    • Added information to the LaTeX converter documentation on how to change the header types and quotation marks
  • Bug fixes:

    • LaTeX converter now outputs line breaks correctly (reported by Michael Franzl)
    • Always outputting the entities zcaron and Zcaron numerically since browser support seems to be non-existing (reported by Eric Sunshine)
    • Fixed warnings and problems when running under Ruby 1.9.2-rc1
    • Fixed problem with smart quote directly after smart quote output in LaTeX converter (reported by Michael Franzl)
    • Fixed problem in the HTML parser that prevented <body markdown="1"> from being processed correctly (reported by Eric Sunshine)
    • Blockquotes with multiple child elements are now output with the quotation environment instead of the quote environment by the LaTeX converter (reported by Michael Franzl)
    • Fixed problem with parsing autolinks when using an encoding different from UTF-8 (reported by Eric Sunshine)
    • Fixed problem with parsing HTML <a> tag without href attribute (reported by Eric Sunshine)
  • Deprecation notes:

    • The option numeric_entities is replaced by the new option entity_output and will be removed in the next version
    • The method Kramdown::Converter::Html#options_for_element has been removed
Published on Wednesday, 23 June 2010

kramdown 0.9.0 released

The biggest change in this release is the addition of a kramdown converter. This converter together with the HTML parser enables one to convert an HTML document into a kramdown document.

Apart from that there are many other small changes and bug fixes, a full list of which you find below.


  • Major changes:

    • New kramdown converter that converts an element tree into a kramdown document
  • Minor changes:

    • Added option numeric_entities that defines whether entities are output using their names or their numeric values
    • Added option toc_depth for specifying how many header levels to include in the table of contents (patch by Alex Marandon)
    • Ruby 1.9 only: The HTML converter now always tries to convert entities to their character equivalences if possible
    • Change in HTML parser: conversion of pre and code elements to their native counterpart is only done if they contain no entities (under Ruby 1.9 entities are converted to characters before this check if possible)
    • The comment extension now produces comment elements that are used by the converters
    • IALs can now also be assigned to definitions (i.e. dd elements)
    • Image links may now be specified without alternative text (requested by Rune Myrland, fixes RF#28292)
    • The HTML parser gained the ability to convert conforming span and div elements to math elements
    • The LaTeX converter now outputs the element attributes as LaTeX comment for some elements (blockquotes, lists and math environments; requested by Michael Franzl)
  • Bug fixes:

    • Fixed problem with list item IALs: the IAL was not recognized when first element was a code block
    • Fixed ri documentation error on gem installation (patch by Alex Marandon)
    • Math content is now correctly escaped when using the HTML converter
    • Fixed html-to-native conversion of tables to only convert conforming tables
  • Deprecation notes:

    • The filter_html option has been removed.
    • The method Kramdown::Converter::Html#options_for_element has been renamed to html_attributes – using the old name is deprecated and the alias will be removed in the next release
Published on Tuesday, 08 June 2010

kramdown 0.8.0 released

One of the bigger changes in this release is the support for converting HTML tags into native kramdown elements via the new html_to_native option. For example, the HTML tag p is converted to the native paragraph element instead of a generic HTML tag if this option is set to true. This is especially useful for converters that don’t handle generic HTML tags (e.g. the LaTeX converter).

This conversion is a feature of the new standalone HTML parser which is used by the kramdown parser for parsing HTML tags.

Also note that support for the old extension syntax and custom extensions has been dropped as of this release! And the filter_html option will be removed in the next release because there exist better facilities for performing this kind of task!


  • Major changes:

    • New parser for parsing HTML documents
    • Added the option html_to_native (default: false) which tells the kramdown parser whether to convert HTML tags to native kramdown elements or to generic HTML elements.
  • Minor changes:

    • Table header cells are now represented by their own element type
    • The element type :html_text is not used anymore - it is replaced by the general :text element
    • HTML comments are now converted to LaTeX comments when using the LaTeX converter
    • The LaTeX converter can now output the contents of HTML <i> and <b> tags
  • Bug fixes:

    • Attributes that have been assigned to the to-be-replaced TOC list are now added correctly on the generated TOC list in the HTML converter
    • Fixed problem in typographic symbol processing where an entity string instead of an entity element was added
    • Fixed problem with HTML span parsing: some text was not added to the correct element when the end tag was not found
    • HTML code and pre tags are now parsed as raw HTML tags
    • HTML tags inside raw HTML span tags are now parsed correctly as raw HTML tags
    • The Rakefile can now be used even if the rdoc gem is missing (patch by Ben Armston)
    • Fixed generation of footnotes in the LaTeX converter (patch by Ben Armston)
    • Fixed LaTeX converter to support code spans/blocks in footnotes
    • HTML comments and XML processing instructions are now correctly parsed inside raw HTML tags
    • HTML script tags are now correctly parsed
    • Fixed the abbreviation conversion in the LaTeX converter
    • Empty image links are not output anymore by the LaTeX converter
  • Deprecation notes:

    • The old extension syntax and support for custom extensions has been removed.
    • The filter_html option will be removed in the next release.
Published on Friday, 07 May 2010

kramdown 0.7.0 released

This release adds syntax support for abbreviations. This means that kramdown is now syntax-wise on par with Maruku and PHP Markdown Extra!

Another big change is the extension support: After some discussion on the mailing list (many thanks to Eric Sunshine and Shawn Van Ittersum), the syntax for the extensions has been changed and support for custom extensions will be dropped in a future release.

Additionally, the option auto_ids has been moved from being interpreted by the parser to being interpreted by the converters. This means that it is not possible anymore to turn automatic header ID generation on or off for parts of a text.

The HTML and LaTeX converters also gained the ability to generate a table of contents. Just add the reference name “toc” to an ordered or unordered list and it will be replaced by the ToC (this is “coincidentally” the same syntax that Maruku uses…).


  • Major changes:

    • Added support for PHP Markdown Extra like abbreviations
    • Added support for span extensions
    • New syntax for block/span extensions
    • Added support for generating a table of contents in the HTML and LaTeX converters
  • Minor changes:

    • The option auto_ids has been moved from the parser to the converters.
    • Invalid span IALs are now removed from the output
    • IALs can now be applied to individual list items by placing the IAL directly after the list item marker
    • Added an option for prefixing automatically generated IDs with a string
    • Block IALs can now also be put before a block element
  • Bug fixes:

    • Fixed a problem with parsing smart quotes at the beginning of a line (reported by Michael Franzl)
  • Deprecation notes:

    • Removed deprecated CLI option -f
    • The old extension syntax and support for custom extensions will be removed in the next release.
Published on Tuesday, 06 April 2010

kramdown 0.6.0 released

This release adds syntax support for block and inline LaTeX math (for example: \(e^{i\pi}=?\)). Aside from that there are the usual small enhancements and bug fixes.


  • Major changes:

    • Added syntax support for block and inline LaTeX math
  • Minor changes:

    • Added a man page for the kramdown binary
    • Added a CLI option for selecting the input format and changed the output format option to -o
    • Small syntax change for list items: the last list item text is now also wrapped in a paragraph tag if all other list items are.
    • Added documentation on available parsers and converters
  • Bug fixes:

    • Fixed problem where clearly invalid email autolinks were permitted (reported by Eric Sunshine)
    • Added documentation for autolinks (reported by Eric Sunshine)
    • Fixed performance problem related to emphasis parsing (reported by Chris Heald)
    • Fixed bug RF#27957: document templates were missing from distribution packages (reported by Alex Bargi)
    • Fixed problem with LaTeX converter handling HTML elements not correctly
  • Deprecation notes:

    • The CLI options -f will be removed in the next release.
Published on Monday, 15 February 2010

kramdown 0.5.0 released

This release features syntax support for smart quotes in kramdown documents and a new converter for LaTeX output. The kramdown binary has also been enhanced to support setting any option.

The additional support for the smart quotes makes this release of kramdown a little bit slower than the previous releases when run under Ruby 1.8. However, a small optimization in the span parser which is not noticable under Ruby 1.8 gives quite a performance boost under Ruby 1.9 (see the graphs on the tests page).

Also note that the internals have been restructured slightly. So if you do more than just using the basic, OPTIONS).to_html

you may need to adapt your code.

Since the option handling has been revamped, each coderay option must not be set separably!


  • Major changes:

    • Enhanced the kramdown binary (it now supports setting the available options)
    • Added support for ERB templates to wrap the generated output
    • Added syntax support for smart quotes
    • Added a converter for LaTeX output
  • Minor changes:

    • Some code restructurations
    • The quotation mark " is not converted to &quot; in normal text anymore.
  • Bug fixes:

    • Fixed problem with multibyte encodings under Ruby 1.9
Published on Friday, 22 January 2010

kramdown 0.4.0 released

This release features the addition of a simple table syntax and syntax highlighting of code blocks. I think that with these two additions kramdown now supports all the major features regarding parsing and HTML output that Maruku supports.

Regarding speed: Simple benchmarks using the Markdown README file (can be found inside this zip file) show that kramdown is currently faster than, for example, the original, PHP Markdown, PHP Markdown Extra, Python Markdown and Maruku.


  • Major changes:

  • Minor changes:

    • Changed CSS class name kramdown-footnotes to footnotes for better compatibility
  • Bug fixes:

    • Regular expression for matching escaped characters now works correctly
Published on Sunday, 20 December 2009

kramdown 0.3.0 released

The HTML block syntax was changed in this release sothat using raw HTML blocks works more naturally and the rules are easier to remember. This also lead to the creation of a completely new HTML block parser. Apart from that, there have also been some bug fixes.

Another important change is that kramdown now also runs under Ruby 1.8.5.


  • Major changes:

    • Added a compatibility fix so that kramdown works under Ruby 1.8.5 (requested by Steve Huff)
    • Complete overhaul of the used block HTML syntax and block HTML parser
    • Using the same semantics for invalid end tags and unclosed tags in the block and span HTML parser
  • Bug fixes:

    • Fixed warnings on Ruby 1.9
    • Fixed bug in emphasis parser where emphasis started with an underscore at the beginning of a new line inside a paragraph was not recognized (reported by Eric Sunshine)
  • Deprecation notes:

    • The old extension names kdoptions and nokramdown have been removed, only the new names options and nomarkdown will work from now on.
Published on Thursday, 03 December 2009

kramdown 0.2.0 released

The most important changes in this release are the inclusion of a definition list syntax and the much improved HTML parser. For example, the HTML parser now recognizes the markdown attribute for enabling and disabling syntax processing in an HTML element and it works in many more scenarios.

The kramdown syntax is still a bit in in a state of flux but all of the major syntax elements (except a syntax for tables) are now available. The following releases will focus on stability and fixing bugs.

kramdown now also passes 16 from the 23 original Markdown test cases and if one looks at the ones that fail one can easily see that this is because of the small changes in the syntax (e.g. converting --- to &mdash). This means that almost all Markdown documents show be correctly parsed by kramdown!

Last but not least I want to thank Eric Sunshine for his many helpful comments, suggestions and bug reports!


  • Major changes:

    • Definition lists are now supported
    • Option auto_ids now defaults to true
    • kramdown syntax (except HTML block lines) is not processed anymore by default in HTML block tags
    • Added option for enabling/disabling parsing of HTML blocks/spans
    • Added recognition and usage of the “markdown” attribute for HTML block/span tags
    • Renamed extensions kdoptions to options and nokramdown to nomarkdown (suggested by Eric Sunshine)
    • Added support for setting header IDs via the syntax available in PHP Markdown Extra and Maruku
  • Bug fixes:

    • Fixed bug that occured when using auto_ids=true and an IAL for assigning an ID to a header
    • Fixed bug with parsing of autolinks (reported by Eric Sunshine)
    • Fixed many bugs regarding HTML parsing – HTML parsing should work much better now (reported by Eric Sunshine)
    • Fixed bug with parsing of horizontal rules which contain tabs
  • Deprecation notes:

    • The old extension names kdoptions and nokramdown will be removed in one of the next versions, use the new names options and nomarkdown.
Published on Saturday, 21 November 2009

kramdown 0.1.0 released

This is the first release of kramdown, yet-another-Markdown converter for Ruby, with the following features:

  • Written in pure Ruby, no need to compile an extension (like BlueCloth or rdiscount)

  • Fast (current impl ~5x faster than Maruku, ~10x faster than BlueFeather, although ~30x slower than native code like rdiscount)

  • Strict syntax definition (special cases for which the original Markdown page does not account for are explicitly listed and it is shown how kramdown parses them - see the Syntax page)

  • Supports common Markdown extension (similar to Maruku)