[kramdown-users] Inline comments

Shawn Van Ittersum svicalifornia at gmail.com
Mon Apr 12 21:14:31 EDT 2010

Well, as we are working on the clearest and easiest syntax for kramdown tags, let's review the full kramdown tag syntax, starting with the tags used most often:

{: HTML-attribute [, HTML-attribute, ...] }

Spaces within the braces are optional.

#id-name | .class-name : attribute="value"

Generalized kramdown tag

Based on the above, this is the general syntax for a kramdown tag of any kind:
{: ...}


1. I don't see a need to have additional colons at the end extension tags.  The other kramdown tags don't have them, and there's no reason that extension tags need them, as they are already differentiated by two colons at the beginning of the tag.  They should be stripped off for simplicity (made optional for backwards compatibility).

2. While kramdown does not yet support nested tags, it would be very handy if it did, and we should design the syntax to accommodate it, so that we are not limited by the syntax choices we make today.

3. Thanks to 25 years of SGML, HTML, and XML, the slash character is widely known and understood as a tag modifier to indicate closing.  HTML is the most pervasive of Web languages, so we would do well to adopt this character and inherit the meaning it has already built up for us.

4. We should plan now to support arguments and attributes on extensions, to make them more useful in the future.

5. Several people have expressed interest in a shorthand closing tag, which I share.  This can be accomplished using the slash and making the extension command text optional on the closing tag.

With those observations, I propose these possibilities:

Opening tag
{::nomarkdown}      Standard form
{:: nomarkdown }    Optional spaces
{::nomarkdown::}    Optional ending colons
{:: nomarkdown ::}  Optional space and ending colons

Opening tag with arguments and attributes
{::nomarkdown arg1 arg2 attr1="..." attr2="..."}

Closing tag
{::/nomarkdown}     Double-colon standard form
{:/nomarkdown}      Alternate shorter form; single-colon followed by slash indicates closing extension tag
{:/}                Shorthand: close the last opened extension


This is a block with no markdown{::comment}, and this is a comment that will be omitted{:/comment}

Note: With the above syntax, I withdraw my prior request for {::comment this is a comment} syntax.  {::tag}This new syntax{:/} is short enough and ensures that we don't have special-case syntax only for certain extensions, which may be hard to parse and limiting of future expandability of the extensions feature.


On Mon, 12 Apr 2010 20:32:07 +0200, Thomas Leitner wrote:
> On Mon, 12 Apr 2010 16:31:45 +1000, Shawn Van Ittersum wrote:
>> Well, I can still see that being a source of great confusion, even
>> more so when the tags are wrapped around a block.  I would at least
>> like kramdown to support an alternate close-tag syntax, so I can make
>> sure that my documents can use distinctive close tags.  Having to
>> track whether each {::nomarkdown:} or other state-toggle tag is
>> opening or closing in a long document could be a major pain.
> You are correct in this regard, there should probably be a difference
> between the start and end tag of an extension block. What about having
> `{::comment:}` as start and `{::}` as end tag? This should be no
> problem *except* when one wants to nest extension tags which is also
> not supported currently (and therefore no problem). This approach would
> also be less verbose.
> -- Thomas
> _______________________________________________
> kramdown-users mailing list
> kramdown-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/kramdown-users

More information about the kramdown-users mailing list