[kramdown-users] Syntax of IALs, ALDs and extensions

Thomas Leitner t_leitner at gmx.at
Tue Apr 20 04:17:06 EDT 2010

> Eric pretty well summarized my feelings on the ">" syntax.  To that,
> I'll add that because ">" is used so commonly in HTML/XML to end
> tags, it's very confusing to find it in the middle of a kramdown
> tag.  This is even more troublesome when we consider that
> HTML/XML/ERB will likely appear in some kramdown documents.

As I replied to Eric's mail, it was just one of the characters that
came in mind and I agree that it might be confusing.

> 1. Personally, I wish the Maruku team had adopted the equal sign (=)
> to assign attributes to references in ALDs:
>   {:ref=.class1 #id ... }
> I'd like to request that as an optional alternate syntax to the
> Maruku convention, as it is so much clearer than adding an extra
> colon.  However, we should still support the Maruku convention, so
> we'll still need to make the extension syntax distinct (see next
> point).

I don't think that the equal sign would be a good choice. I.e., while
reading your above example one can easily think that `ref` has the
value `.class1`. I also don't want to add optional alternate syntax if
there is no good reason for it - convenience is too little. 

So I would rather stay with `{:ref: .cls #id key="val"}` regarding ALDs.
> 2. Amending my proposal for extensions, I had also considered with
> the idea of a standard prefix character on extension directives.  In
> this case, we don't even need the colon, since the prefix serves as a
> signal that we are invoking a kramdown extension.  Since invoking an
> extension is something like calling a subroutine, it seems
> appropriate (and also looks pretty good, I think) to borrow the
> ampersand from Perl:
>   {&extension arg1 arg2 ... }
> Other alternatives would include:
>   {@extension arg1 arg2 ... }
>   {!extension arg1 arg2 ... }
>   {%extension arg1 arg2 ... }
> Then we make a rule that ALD reference names can't start with such a
> prefix character, and there we have the distinction between ALDs and
> extensions.

ALD names already have such a restriction - see

Also, for consistency I don't want to omit the leading colon, even in
extensions. And I think that the ampersand is too "blocky", ie. the
beginning of the extension name is hard to read. The exclamation mark
would be a better choice in this regard I think.

> 4. It would be incredibly cool if kramdown would support custom
> extensions in the future.  I'm working on a software documentation
> project now in kramdown, where I will often need to link to a
> separate system that contains database schema definitions.  I would
> love to define a ruby method and be able to call it in the middle of
> my kramdown documents:
>   User data is stored in the {&db_schema_link users /} table.
> with a corresponding Ruby method (note the return value of the custom
> extension method is in kramdown syntax, to be evaluated by kramdown):
>   def db_schema_link(table_name)
> 	"[#{table_name}](http://docs.project.com/schema/#{table_name}.html)"
>   end

I think that this is not the way to go. You are mixing two things here:
a markup language that is used for writing probably large amounts of
text and which supports a certain syntax for marking up some parts of
the text. And a template processor which is used to execute arbitrary

kramdown is a markup language and not a template processor. Its syntax
is used for semantically marking up parts of the text as paragraph,
block quotes, emphasis, link and so on. This has and should have nothing
to do with executing arbitrary code. While implementing kramdown I
thought that this would be good idea and therefore added support for
it, even using it on the kramdown homepage... However, my opinion on
that changed.

The current "extensions" are useful in kramdown as a markup language
since often one wants to omit draft text or one's notes from the output
(comment) or work around an edge case where kramdown does not work
correctly (nomarkdown) or wants to set options on how the kramdown
document is converted (options).

What you want to achieve can already be achieved in a much simpler way:
just use ERB tags and run ERB first and the kramdown. This will do
exactly what you want! And it is much more flexible than any solution
within kramdown. If you don't want to be tied to a syntax that is Ruby
specific, you can use another template processor like [moustache] which
is language agnostic.

   Therefore I think that extensions in kramdown are really not that
            useful and I would like to remove them!

As for the syntax: In the case of not having custom extensions, it can
be simplied to something like the following (same for block and span

  {:comment}some comment{:/comment}      # verbose form
  {:comment}some comment{:/}             # short form
  {:options key="val" /}                 # no-body form

In this case we also don't need an extra differentiator like `!` at the
beginning of a extension name since the names are "well known". Also
note that the short form would need to have the leading colon as well!

[moustache]: http://mustache.github.com/

-- Thomas

ps. The repo version now contains the last missing syntax from
Maruku/PHP Markdown extra: abbreviations ;-)

More information about the kramdown-users mailing list