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

Eric Sunshine sunshine at sunshineco.com
Fri Aug 31 18:47:52 UTC 2012


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. Since Github documentation
[1] mentions only the ``` syntax, many people likely do not know that
it also accepts the ~~~ syntax.

2) [specify language on ~~~ line]: Seems like a reasonable convenience.

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.)

[1]: http://github.github.com/github-flavored-markdown/
[2]: http://www.ietf.org/rfc/rfc1766.txt

-- ES


On Fri, Aug 31, 2012 at 12:07 PM, Matt Neuburg <matt at tidbits.com> wrote:
> I am someone who uses kramdown's fenced code block style and I agree with all three points: make no change to backticks, and go ahead and implement the other changes, even if there is breakage with "lang". m.
>
> On Aug 31, 2012, at 7:17 AM, Thomas Leitner wrote:
>
>> Hi everybody,
>>
>> there is a [pull request][1] on Github which, among other things, wants
>> to add 1) support for Github flavored code style and 2) support for
>> setting the highlighting language on the delimiter line of a fenced code
>> block.
>>
>> [1]: https://github.com/gettalong/kramdown/pull/15
>>
>> I also want to talk 3) about the current way of setting the highlighting
>> language.
>>
>>
>> ad 1) kramdown already has a fenced code block style:
>>
>>    ~~~
>>    some code here
>>    ~~~
>>
>> Github flavored code blocks use a backtick instead:
>>
>>    ```
>>    some code here
>>    ```
>>
>> I personally don't think that it is necessary or even good in this
>> case to provide another syntax for fenced code blocks. Using the
>> backtick currently only works on the Github website itself, as far as I
>> know.
>>
>> Also note that the kramdown (and php-markdown-extra and
>> python-markdown) fenced code blocks *do* work on Github, too!
>>
>> So, what do you think?
>>
>>
>> ad 2) Providing the syntax highlighting language on the delimiter line
>> is a rather nice idea and not only supported by Github but also by
>> other markdown implementations (like python-markdown). It would look
>> like this:
>>
>>    ~~~~~~ ruby
>>    class MyRuby
>>    end
>>    ~~~~~~~~~~~~
>>
>> I would like to integrate this into kramdown -- does anyone have good
>> reasons for not using this syntax?
>>
>>
>> ad 3) The syntax highlighting language can currently be set by using an
>> IAL to specify the attribute `lang`. However, the `lang` attribute in
>> HTML elements is generally used for setting the natural language of the
>> text inside an element...
>>
>> I'm for removing this collision by following the HTML5 way of
>> specifying the highlighting language, which is setting the class
>> `language-CODELANG` on the `<code>` element.
>>
>> This would mean that this kramdown document:
>>
>>    ~~~
>>    some code here
>>    ~~~
>>    {: .language-ruby .other attr="key"}
>>
>> would be transformed to this HTML output (in case coderay was not used):
>>
>>    <pre attr="key" class="other"><code class="language-ruby">some code here
>>    </code></pre>
>>
>> Note that the `language-ruby` class is set on the `<code>` element and
>> not on the parent `<pre>` element!
>>
>> This would be a backwards-incompatible change, what do you think?
>>
>>
>> Best regards,
>>  Thomas
>> _______________________________________________
>> kramdown-users mailing list
>> kramdown-users at rubyforge.org
>> http://rubyforge.org/mailman/listinfo/kramdown-users
>
> _______________________________________________
> kramdown-users mailing list
> kramdown-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/kramdown-users


More information about the kramdown-users mailing list