0

I need to embed a code block in a list item in kramdown. The code block is highlighted by Pygments.
The result looks like the following picture. I expect the code block to shift right to prove it's part of the list element. The kramdown docs use fenced block style, it's not working well with my Jekyll site, so I use another:

{% highlight robotframework %}
...
{% endhighlight %}

How to control the indentation automatically in this manner?
Thanks for any advice.

this

2

2 Answers 2

1

kramdown supports fenced code block within a list.

According to Planet Jekyll FAQ,The key is to indent your fenced code block lined up with the list item. Also need to put a separating newline above and below the fenced block:

Q: How can I get backtick fenced code blocks (e.g. ```) working inside lists (with kramdown)?

The gist is that the indentation for the code block in lists is determined by the column number of the first non-space character after the list item marker. Huh?

Let's use some examples (note the leading spaces get replaced with dots e.g. · to help along):

Bulleted List

*·some text     =>  use 2 spaces indentation e.g.

  ```
  $ gem install beerdb
  ```

*···some text   =>  use 4 spaces indentation e.g.

    ```
    $ gem install beerdb
    ```

Numbered List

1.·some text    =>  use 3 spaces indentation e.g.

   ```
   $ gem install beerdb
   ```

==> If you line up the fenced code block with the "natural" list indentation, it will work.

For more examples, see the syntax highlighter sandbox list page - (source).

3
  • It seems that Pygments doesn't work well with fenced blocks, so I use this this form:{% highlight robotframework %}...{% endhighlight %}, then there comes the problem of how to embed a code block in a list item. Jun 30, 2016 at 2:05
  • @RobertLi markdown does allow multi line list item, just leave two trailing spaces after previous line -- if that's your problem. Furthermore, why not switch to rouge for code highlighting?
    – cherrot
    Jul 1, 2016 at 2:53
  • Pygments support more programming languages than rouge . Jul 1, 2016 at 3:06
0

It appears that Kramdown only supports fenced code blocks at the root (not nested) of the document. While other implementations have recently been adapted to support nested fenced code blocks, Kramdown still implements the old original proposal and has not been updated in some time. If you would like to use fenced code blocks nested within list items, then you will need to use a different Markdown implementation (and/or convince the developers to Kramdown to update their implementation).

You may need to update to a more recent version of Kramdown, and/or adjust the amount of indent that you have in front of each line of your fenced code block. There seems to be some inconsistency in that regard. According to this comment, you should have exactly four spaces of indent, however, at least some versions have been know to fail with four spaces but work with two.

Irrespective of which Markdown implementation you are using Jekyll provides a template based method of identifying code blocks for highlighting purposes. However, that is also restricted to only being on the document root. After all, if you wanted to use a code block within a Markdown document to show how to use this method, that code block would be indented. Therefore, Jekyll only acts on non-indented blocks.

You may find that a JavaScript highlighting engine will serve you better. That way you can use standard (indented) code blocks which will work with any Markdown implementation and nest them however you like. And some of the better JavaScript highlighting engines have pretty good language detection, so you usually don't need to label the language of the code blocks.

7
  • This is wrong, Kramdown does support code blocks (both indented and fenced) inside list items.
    – matt
    Jan 25, 2016 at 20:00
  • I couldn't get it to work. Perhaps that is using an older version?
    – Waylan
    Jan 26, 2016 at 1:24
  • Ah, now I see that Babelmark is using 1.2.0 and Kramdown's documentation references 1.9.0. Unfortunately, outside of installing it locally, I don't have any way of testing that it works. And I don't see any release notes to review what changes have been made.
    – Waylan
    Jan 26, 2016 at 1:31
  • Version 1.2.0 is a couple of years old, but you can still get code blocks inside list items
    – matt
    Jan 26, 2016 at 1:36
  • 1.9.0 still parses your example the same way, which is a bit odd – I guess the extra indentation throws it off in some way.
    – matt
    Jan 26, 2016 at 1:42

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.