[kramdown-users] Backward incompatible changes in parser/converter
t_leitner at gmx.at
Wed Apr 7 04:23:45 EDT 2010
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]) 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:
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.
More information about the kramdown-users