[kramdown-users] Syntax for specifying code highlighting language | Github flavored code blocks style

Thomas Leitner t_leitner at gmx.at
Sat Sep 1 08:31:27 UTC 2012


Thanks for all the replies so far!

On 2012-08-31 22:33 -0700 Lou Quillio wrote:
> On Fri, Aug 31, 2012 at 11:47 AM, Eric Sunshine
> <sunshine at sunshineco.com> wrote:
> > 1) [Github alternate fenced blocks]: I am not a fan of this and
> > other gratuitous differences from the norm, and my gut reaction is
> > to reject the change. The only small justification I can make for
> > accepting it is that it would increase the likelihood of kramdown
> > being employed locally to compose and preview a Markdown document
> > which ultimately will be viewed in rendered form on Github.
> 
> (Not picking on Eric here, just easier to jump-off from his post.)
> 
> I don't think that accepting backticks on the same rules as tildes is
> likely to collide with anything -- and it has a consistency logic.
> Things that are good for kramdown and don't cause user pain are good.
> Within limits. Thomas is a good judge of those limits.

Since Github (or more exactly, the redcarpet/sundown library) supports
the php-markdown-extra style fenced code blocks there really would be no
benefit of supporting github style fenced code blocks - but that's just
my opinion.

When I think about this issue, I also think of two similar but not too
simliar cases already present in the syntax:

* We already have two ways of specifying headers (atx and setext).
  However, since those two syntaxes differ very much from each other
  and have come from a historic context this is okay.

* It is possible to specify unordered lists with various characters (*,
  + and -). The case could be made that github style code blocks should
  be supported because from a syntactical point of view only the
  character (` instead of ~) changes.

  However, people inherently use stars and dashes for making lists,
  even with pen and paper. No such thing can be said for fenced code
  blocks, there is no natural character for starting/ending a code
  block. Therfore I would not introduce another, second way to do this.

> > 3) [syntax highlighting language]: kramdown has been around long
> > enough and (presumably) is widely enough used that
> > backward-incompatible changes should not be undertaken lightly. If I
> > understand correctly, the backward-incompatible change to which you
> > refer is that kramdown would no longer recognize lang=FOO specially.
> > In the interest of backward-compatibility, perhaps continue to
> > recognize lang=FOO if the following is true: .language-FOO is not
> > present and the FOO in lang=FOO does not seem to be a natural
> > language specification [2]. (Rough heuristic: If FOO contains a
> > hyphen or is only two characters in length, then it's probably a
> > natural language specification.)
> 
> Maybe this idea needs more time to marinate, see what people do in the
> real world. Setting a lexer with 'lang=' has a narrow and different
> purpose than natural-language setting, and I'm a bit uncomfortable
> with conflating them. If it turns out to be an uncomplicated, common
> markup practice, then it's safe. We just don't know yet, and there'd
> be a little pain. To me, there's no rush on this one.

The problem is that those things *are* currently conflated. I have
based the initial syntax on that of MaRuKu and it has used
the `lang=LANG` for specifying the syntax highlighting language - and
I didn't think enough about this when implementing it.

Due to the recent Github pull request I saw that this is probably not
so a good idea because the 'lang' attribute as defined by the HTML
specs is only for natural languages and kramdown abuses it.

Therefore I would like to get rid of it, the sooner the better. The
more people use kramdown the harder it will be to make
backward-incompatible changes. I know that kramdown is already widely
used but I don't think that this exact feature is that widely used.

Eric's idea for backward-compatibility is rather nice. So how about
making the change (releasing 0.14.0 because of this) and providing such
a heuristic for current users until the next major release (0.15.0 or
1.0.0)?

Best regards,
  Thomsa


More information about the kramdown-users mailing list