[kramdown-users] Backward incompatible changes in parser/converter

Thomas Leitner t_leitner at gmx.at
Wed Apr 7 04:23:45 EDT 2010

Hi everyone,

while reading over the kramdown syntax documentation and considering the
recent posts on the Markdown ML, I propose the following changes and
would like to hear your opinions. Some of the following changes would
make the next kramdown release *not* compatible with current kramdown

One reason for some of the changes is that I would like to make the
parser non-configurable (the Markdown ML has some discussions of the
benefits of a non-configurable parser). This means that the parser will
always generate the same internal element tree from a source
document which is generally a good thing.

* Moving the :auto_ids option from the kramdown parser to the converters

  This is just a minor change, mostly in the code base and will not
  change the overall behaviour of kramdown. There is really no need
  for the parser to do this and it removes one parser option.

* Removing the options :parse_block_html and :parse_span_html

  These are the last two parser options and should be removed to make
  the parser non-configurable. I don't know if anyone has ever changed
  one of these options - I haven't. The reasons for their respective
  default values have been discussed on this ML before and a good
  choice was made.

  One can always en-/disable parsing of specific HTML elements by using
  the `markdown` attribute. Therefore there should be no use case for

* Removing/changing the extensions feature

  I originally thought that the extensions feature would be quite
  useful. However, when writing standalone documents extensions I did
  not use them. And when writing multiple documents, for example the
  source files for the kramdown homepage, another framework (in this
  case [webgen][1]) provides features that are similar to the kramdown

  Therefore I would like to completely remove the support for custom
  extensions in the next release.

  Another change I would like to make is to change the syntax used for
  the built-in extensions (comment, nomarkdown and options). The
  current syntax is just fine but introduces a new and unnecessary
  syntax. Since people which use Markdown are normally familiar with
  HTML tags (or at least know how they look like), I would like to
  completely remove the custom syntax and base the new syntax on
  XML/HTML tags. This would have the additional benefit of having the
  extensions available as span level elements.

  For example, setting options is currently done like this:

      {::options:: auto_ids="true"}

  The new way would look like this:

      <md:options auto_ids="true" />

  As one can see the new version is just one character longer and just
  as easy to read.

  This change, however, would make the next kramdown release backwards

I would like to incorporate all the above changes in the next release
of kramdown and if there are no major concerns against these changes I
will start implementing them in about two weeks.

-- Thomas

[1]: http://webgen.rubyforge.org

More information about the kramdown-users mailing list