starred/markdownlint

Fork 0

mirror of https://github.com/DavidAnson/markdownlint.git synced 2026-04-25 09:16:02 +03:00

[GH-ISSUE #43] Add rule for checking proper formating of fenced code block inside lists #35

New issue

Open

opened 2026-03-03 01:23:11 +03:00 by kerem · 4 comments

kerem commented

2026-03-03 01:23:11 +03:00

Owner

Originally created by @pascalberger on GitHub (Jan 18, 2017).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/43

Writing fenced code blocks inside of ordered and unordered lists might not be the most obvious thing. A rule indicating mistakes might be really helpful in this case.

Stuff to check:

There needs to be a new line before and following any fenced code block inside of a ordered or unordered list

Originally created by @pascalberger on GitHub (Jan 18, 2017). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/43 Writing fenced code blocks inside of ordered and unordered lists might not be the most obvious thing. A rule indicating mistakes might be really helpful in this case. Stuff to check: * There needs to be a new line before and following any fenced code block inside of a ordered or unordered list

kerem added the

new rule

label

2026-03-03 01:23:11 +03:00

kerem commented

2026-03-03 01:23:12 +03:00

Author

Owner

@twocs commented on GitHub (May 30, 2025):

I would say that the original problem is difficult to solve. However, there are currently two conflicting rules regarding fenced code blocks inside (numbered) lists. The new line before and following a fenced code block rule, but if a numbered list has a blank line before the subsequent number, then there's a warning that the number kept incrementing.

MD031/blanks-around-fences: Fenced code blocks should be surrounded by blank linesmarkdownlintMD031

MD029/ol-prefix: Ordered list item prefix [Expected: 1; Actual: 2; Style: 1/1/1]markdownlintMD029

1. My bulleted list includes some important code
2. This is my second point
  1. Code must be indented to be kept with this list item. It must be surrounded by blank lines to avoid 2.1. But a blank line is also a signal that the numbering does not continue.

    ```json
    {
      "ID": 12345,
      "Price": 100000
    }
    ```

   2. If I want the number 2 here, this line sees a warning for MD029.

I can avoid the MD031 by adding the blank lines (but they must not be indented). However, I'm unable to avoid MD029 except by annotations. This is the way I currently embed code into my numbered lists.

1. My bulleted list includes some important code
2. This is my second point
  1. Code must be indented to be kept with this list item. It must be surrounded by blank lines to avoid 2.1. But a blank line is also a signal that the numbering does not continue.
    <!-- markdownlint-disable-next-line MD029 -->
    ```json
    {
      "ID": 12345,
      "Price": 100000
    }
    ```
    <!-- markdownlint-disable-next-line MD029 -->
   2. Now there are no markdownlint warnings.

Note that the first comment simply guides markdownlint to consider the code block as being surrounded by blank lines, it doesn't actually require explicit mention of MD031. On the other hand, the second markdownlint-disable-next-line must specifically disable MD029.

@twocs commented on GitHub (May 30, 2025): I would say that the original problem is difficult to solve. However, there are currently two conflicting rules regarding fenced code blocks inside (numbered) lists. The new line before and following a fenced code block rule, but if a numbered list has a blank line before the subsequent number, then there's a warning that the number kept incrementing. > MD031/blanks-around-fences: Fenced code blocks should be surrounded by blank linesmarkdownlint[MD031](https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md031.md) > MD029/ol-prefix: Ordered list item prefix [Expected: 1; Actual: 2; Style: 1/1/1]markdownlint[MD029](https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md029.md) ``` 1. My bulleted list includes some important code 2. This is my second point 1. Code must be indented to be kept with this list item. It must be surrounded by blank lines to avoid 2.1. But a blank line is also a signal that the numbering does not continue. ```json { "ID": 12345, "Price": 100000 } ``` 2. If I want the number 2 here, this line sees a warning for MD029. ``` I can avoid the MD031 by adding the blank lines (but they must not be indented). However, I'm unable to avoid MD029 except by annotations. This is the way I currently embed code into my numbered lists. ``` 1. My bulleted list includes some important code 2. This is my second point 1. Code must be indented to be kept with this list item. It must be surrounded by blank lines to avoid 2.1. But a blank line is also a signal that the numbering does not continue.  ```json { "ID": 12345, "Price": 100000 } ```  2. Now there are no markdownlint warnings. ``` Note that the first comment simply guides markdownlint to consider the code block as being surrounded by blank lines, it doesn't actually require explicit mention of MD031. On the other hand, the second markdownlint-disable-next-line must specifically disable MD029.

kerem commented

2026-03-03 01:23:12 +03:00

Author

Owner

@DavidAnson commented on GitHub (May 30, 2025):

Properly indenting your original example produces no warnings:

https://dlaa.me/markdownlint/#%25m%23%20Example%0A%0A1.%20My%20bulleted%20list%20includes%20some%20important%20code%0A2.%20This%20is%20my%20second%20point%0A%20%20%201.%20Code%20must%20be%20indented%20to%20be%20kept%20with%20this%20list%20item.%20It%20must%20be%20surrounded%20by%20blank%20lines%20to%20avoid%202.1.%20But%20a%20blank%20line%20is%20also%20a%20signal%20that%20the%20numbering%20does%20not%20continue.%0A%0A%20%20%20%20%20%20%60%60%60json%0A%20%20%20%20%20%20%7B%0A%20%20%20%20%20%20%20%20%22ID%22%3A%2012345%2C%0A%20%20%20%20%20%20%20%20%22Price%22%3A%20100000%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%60%60%60%0A%0A%20%20%202.%20If%20I%20want%20the%20number%202%20here%2C%20this%20line%20sees%20a%20warning%20for%20MD029.%0A

@DavidAnson commented on GitHub (May 30, 2025): Properly indenting your original example produces no warnings: https://dlaa.me/markdownlint/#%25m%23%20Example%0A%0A1.%20My%20bulleted%20list%20includes%20some%20important%20code%0A2.%20This%20is%20my%20second%20point%0A%20%20%201.%20Code%20must%20be%20indented%20to%20be%20kept%20with%20this%20list%20item.%20It%20must%20be%20surrounded%20by%20blank%20lines%20to%20avoid%202.1.%20But%20a%20blank%20line%20is%20also%20a%20signal%20that%20the%20numbering%20does%20not%20continue.%0A%0A%20%20%20%20%20%20%60%60%60json%0A%20%20%20%20%20%20%7B%0A%20%20%20%20%20%20%20%20%22ID%22%3A%2012345%2C%0A%20%20%20%20%20%20%20%20%22Price%22%3A%20100000%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%60%60%60%0A%0A%20%20%202.%20If%20I%20want%20the%20number%202%20here%2C%20this%20line%20sees%20a%20warning%20for%20MD029.%0A

kerem commented

2026-03-03 01:23:12 +03:00

Author

Owner

@twocs commented on GitHub (May 30, 2025):

Yes, looks like we simply need an extra indent for the code block as well as surrounding it with blank lines. Additionally I missed that the example for MD029 does explain how to add the extra indent for code blocks.

In regards to the original issue report, I'm unclear how you could make the rules any clearer than they already are. However, I do agree with the statement: "Writing fenced code blocks inside of ordered and unordered lists might not be the most obvious thing". On the other hand, now that I know how it works I don't have any issue.

@twocs commented on GitHub (May 30, 2025): Yes, looks like we simply need an extra indent for the code block as well as surrounding it with blank lines. Additionally I missed that the example for MD029 does explain how to add the extra indent for code blocks. In regards to the original issue report, I'm unclear how you could make the rules any clearer than they already are. However, I do agree with the statement: "Writing fenced code blocks inside of ordered and unordered lists might not be the most obvious thing". On the other hand, now that I know how it works I don't have any issue.

kerem commented

2026-03-03 01:23:13 +03:00

Author

Owner

@DavidAnson commented on GitHub (May 30, 2025):

Yeah, that's the challenge: it's easy when you know and hard when you don't. :) I don't have a great idea for how to make a rule like this reliable, but it would be nice to have and so I've kept the issue open for tracking. Glad you got your issue sorted out!

@DavidAnson commented on GitHub (May 30, 2025): Yeah, that's the challenge: it's easy when you know and hard when you don't. :) I don't have a great idea for how to make a rule like this reliable, but it would be nice to have and so I've kept the issue open for tracking. Glad you got your issue sorted out!

kerem referenced this issue

2026-03-07 20:02:19 +03:00

[GH-ISSUE #35] Long headers cannot be multi-line (MD022) or longer than line length (MD013) #1875