Fenced code blocks in list items have inconsistent hanging indent behavior #311

Closed
nfagerlund opened this Issue Feb 17, 2016 · 7 comments

Projects

None yet

3 participants

@nfagerlund

When putting multiple block-level items (paragraphs, blockquotes, code blocks) in a single list item, you use a hanging indent to keep it associated with the list item. kramdown usually allows two indentation behaviors (well, at least two, but these are the reasonable ones):

  1. Regular: Indent additional block elements by 4 spaces.
  2. Cosmetic: Indent additional block elements so that they align with the first TEXT character of the first line of the list item.

That is:

* List item

    second paragraph, 4 spaces
* List item

  second paragraph, 2 spaces (would use 3 spaces for single-digit numbered list)

However, fenced code blocks only support the second style — they won't render correctly if you use the four-space hanging indent.

This is bad for our team, because the four-space indent is more predictable and easier to reason about, especially with numbered lists. Being able to just tab-and-trust makes for more maintainable text than having to fidget with exact odd-numbered spaces.

Test cases:

Regular indent (doesn't work):

* list item 1
    * list item 2

        2nd paragraph of list item 2

        ``` ruby
        fenced code block in list item 2
        ```

        fourth paragraph of list item 2

    * list item 3
* list item 4

Cosmetic indent (works):

* list item 1
    * list item 2

        2nd paragraph of list item 2

      ``` ruby
      fenced code block in list item 2
      ```

        fourth paragraph of list item 2

    * list item 3
* list item 4

Numbered list (cosmetic indent, works):

1. list item 1
    1. list item 2

        2nd paragraph of list item 2

       ``` ruby
       fenced code block in list item 2
       ```

        fourth paragraph of list item 2

    2. list item 3
2. list item 4
@nfagerlund

Er, I'm using GFM fenced blocks in the examples. Substitute with tildes as needed.

@gettalong gettalong self-assigned this Feb 17, 2016
@gettalong gettalong added the question label Feb 17, 2016
@gettalong
Owner

@nfagerlund You are mistaken, see http://kramdown.gettalong.org/syntax.html#lists. kramdown does not allow 4 space indent, this fallback behavior is only used in the special case where there is no non-space character in the line with the list item marker.

Indentation for list items is always calculated based on the first non-space character after the list item marker.

While it appears that the 4 space indent is working for other block level elements than fenced code blocks, this is just because most block level elements can be indented up to 3 characters and still work, e.g. blockquote markers.

So it is actually very easy to reason about the correct indentation, just align to the first non-space character after the list item marker (which allows nicely formats the text for reading).

@gettalong gettalong closed this Feb 17, 2016
@nfagerlund

Bleah, I didn't realize that. Okay.

But: Since GitHub flavored markdown (as implemented on github.com) will render a fenced code block with the four-space nesting, would you consider making kramdown's GFM mode match it?

@gettalong
Owner

I would certainly accept pull requests.

@tl3shi
tl3shi commented Mar 5, 2016

I've tried sub list for server times. It's OK for Numbered list, However it failed if I use unordered list. I am wondering why. I am using kramdown (1.9.0). The example as follows is Chinese.

-   Disqus Bug
    1. 首页无评论狂, 找不到 `` <div id="disqus_thread"></div> `` 因此报了一下错误`` "Cannot read property 'appendChild' of null" with Disqus ...``
    1. Fix: 添加 ` if($("#disqus_thread").length) `

*   自动部署脚本deploy.sh 替换成 travis-ci
    * [travis添加环境变量](http://stackoverflow.com/questions/23277391/how-to-publish-to-github-pages-from-travis-ci)
    * [travis设置ssh](https://xuanwo.org/2015/02/07/Travis-CI-Hexo-Autodeploy/)
* 自动部署脚本deploy.sh 替换成 travis-ci
   * [travis添加环境变量](http://stackoverflow.com/questions/23277391/how-to-publish-to-github-pages-from-travis-ci)
   * [travis设置ssh](https://xuanwo.org/2015/02/07/Travis-CI-Hexo-Autodeploy/)

* 自动部署脚本deploy.sh 替换成 travis-ci
    *   [travis添加环境变量](http://stackoverflow.com/questions/23277391/how-to-publish-to-github-pages-from-travis-ci)
    *   [travis设置ssh](https://xuanwo.org/2015/02/07/Travis-CI-Hexo-Autodeploy/)

* 自动部署脚本deploy.sh 替换成 travis-ci
   *   [travis添加环境变量](http://stackoverflow.com/questions/23277391/how-to-publish-to-github-pages-from-travis-ci)
   *   [travis设置ssh](https://xuanwo.org/2015/02/07/Travis-CI-Hexo-Autodeploy/)
@gettalong
Owner

I get the following HTML from your source which seems right:

<ul>
  <li>Disqus Bug
    <ol>
      <li>首页无评论狂, 找不到 <code>&lt;div id="disqus_thread"&gt;&lt;/div&gt;</code> 因此报了一下错误<code>"Cannot read property 'appendChild' of null" with Disqus ...</code></li>
      <li>Fix: 添加 ` if($(“#disqus_thread”).length) `</li>
    </ol>
  </li>
  <li>自动部署脚本deploy.sh 替换成 travis-ci
    <ul>
      <li><a href="http://stackoverflow.com/questions/23277391/how-to-publish-to-github-pages-from-travis-ci">travis添加环境变量</a></li>
      <li><a href="https://xuanwo.org/2015/02/07/Travis-CI-Hexo-Autodeploy/">travis设置ssh</a></li>
    </ul>
  </li>
  <li>自动部署脚本deploy.sh 替换成 travis-ci
    <ul>
      <li><a href="http://stackoverflow.com/questions/23277391/how-to-publish-to-github-pages-from-travis-ci">travis添加环境变量</a></li>
      <li><a href="https://xuanwo.org/2015/02/07/Travis-CI-Hexo-Autodeploy/">travis设置ssh</a></li>
    </ul>
  </li>
  <li>自动部署脚本deploy.sh 替换成 travis-ci
    <ul>
      <li><a href="http://stackoverflow.com/questions/23277391/how-to-publish-to-github-pages-from-travis-ci">travis添加环境变量</a></li>
      <li><a href="https://xuanwo.org/2015/02/07/Travis-CI-Hexo-Autodeploy/">travis设置ssh</a></li>
    </ul>
  </li>
  <li>自动部署脚本deploy.sh 替换成 travis-ci
    <ul>
      <li><a href="http://stackoverflow.com/questions/23277391/how-to-publish-to-github-pages-from-travis-ci">travis添加环境变量</a></li>
      <li><a href="https://xuanwo.org/2015/02/07/Travis-CI-Hexo-Autodeploy/">travis设置ssh</a></li>
    </ul>
  </li>
</ul>

What do you get?

@tl3shi
tl3shi commented Mar 6, 2016

Oh, I tried once again, and found that it's caused by the jekyll themes.
Thank you.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment