[GH-ISSUE #1915] MD046: enable parsing/linting of over-indented blocks when set to fenced style #780

New issue

Open

opened 2026-03-03 01:29:49 +03:00 by kerem · 4 comments

kerem commented

2026-03-03 01:29:49 +03:00

Owner

Originally created by @nbanyan on GitHub (Jan 16, 2026).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1915

In my project we try to enforce use of the fenced code style instead of the indented style because it is more declarative and the indented style mostly happens due to improper indentation. We also use Material, so things like admonitions and snippets can make some indented text look like code blocks when they are not.

Still having the warning for the wrong code style is critical for finding and standardizing actual or accidental indented code blocks, but it would be very helpful to have this rule enable parsing and linting of those indented blocks rather than skipping them - perhaps as a second boolean option for this rule like { "style": "fenced", "parse_indented": true }.

## Heading

Paragraph text before an over indented fenced code block.

    ```py
    # Broken code indent and failed fenced code as well...
        ```

??? note "MkDocs Material admonition"
    These have been discussed before, but I'm just looking to allow their content to be linted without explicitly supporting non-standard syntax.
    Examples of errors I've seen in these that I'd like linting warnings for:

    Paragraph text before an indented code block that needs the linting warning. (I'm still finding these in my project...)

        cp /path/to/file /path/to/new/file

    ##### Badly Incremented Heading

    * Mixed list styles
        - And other inconsistencies

--8<-- "snippet_list.md"

        * Appending to a list started in a snippet.
            - Snippets should also not be fully disected to be parsed/linted, but linting over indented text would be very useful in these instances.

Originally created by @nbanyan on GitHub (Jan 16, 2026). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1915 In my project we try to enforce use of the fenced code style instead of the indented style because it is more declarative and the indented style mostly happens due to improper indentation. We also use Material, so things like admonitions and snippets can make some indented text look like code blocks when they are not. Still having the warning for the wrong code style is critical for finding and standardizing actual or accidental indented code blocks, but it would be very helpful to have this rule enable parsing and linting of those indented blocks rather than skipping them - perhaps as a second boolean option for this rule like `{ "style": "fenced", "parse_indented": true }`. ````markdown title="Sample syntax with some of the bad code I've worked with" linenums="1" ## Heading Paragraph text before an over indented fenced code block. ```py # Broken code indent and failed fenced code as well... ``` ??? note "MkDocs Material admonition" These have been discussed before, but I'm just looking to allow their content to be linted without explicitly supporting non-standard syntax. Examples of errors I've seen in these that I'd like linting warnings for: Paragraph text before an indented code block that needs the linting warning. (I'm still finding these in my project...) cp /path/to/file /path/to/new/file ##### Badly Incremented Heading * Mixed list styles - And other inconsistencies --8<-- "snippet_list.md" * Appending to a list started in a snippet. - Snippets should also not be fully disected to be parsed/linted, but linting over indented text would be very useful in these instances. ````

kerem added the

question

label

2026-03-03 01:29:49 +03:00

kerem commented

2026-03-03 01:29:49 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jan 16, 2026):

As I understand, your project already bans the use of indented code blocks, so scenarios that might cause the problem you show are already flagged for attention. Fixing those problems will immediately reveal all the others, but instead it sounds like you want to reparse the document after making guesses about how to reformat it so those violations can be flagged in parallel? I don't understand the motivation - why not fix the reported indenting which will fix the structure of the document? Which it seems you want to do anyway?

@DavidAnson commented on GitHub (Jan 16, 2026): As I understand, your project already bans the use of indented code blocks, so scenarios that might cause the problem you show are already flagged for attention. Fixing those problems will immediately reveal all the others, but instead it sounds like you want to reparse the document after making guesses about how to reformat it so those violations can be flagged in parallel? I don't understand the motivation - why not fix the reported indenting which will fix the structure of the document? Which it seems you want to do anyway?

kerem commented

2026-03-03 01:29:49 +03:00

Author

Owner

@nbanyan commented on GitHub (Jan 16, 2026):

Because correct and intentional indentation such as for admonition content or after snippets are not errors, but since those constructs are not supported those indentations are assumed to be code blocks and therefore not parsed. I'm not looking for direct support for Material Markdown, just better compatibility for detecting errors in the blocks of text indented by these structures.

In the example:

Line 5 is properly flagged for the wrong code style despite being fenced code and because it is indented.
Line 14 is flagged for the wrong code style due to indentation under the unrecognized admonition, which is fine.
Line 16 is ignored as part of the assumed indented code block, but would ideally be flagged as a wrong code style since it is over indented again.
Line 18 is ignored as well but should be flagged for skipping heading levels
Line 21 is ignored but should be flagged for inconsistent list marker style
Line 25 is flagged for the wrong code style due to indentation under the unrecognized snippet syntax
Line 26 is ignored as part of another assumed indented code block, but should be flagged for inconsistent list marker style

@nbanyan commented on GitHub (Jan 16, 2026): Because correct and intentional indentation such as for admonition content or after snippets are not errors, but since those constructs are not supported those indentations are assumed to be code blocks and therefore not parsed. I'm not looking for direct support for Material Markdown, just better compatibility for detecting errors in the blocks of text indented by these structures. In the example: * Line 5 is properly flagged for the wrong code style despite being fenced code and because it is indented. * Line 14 is flagged for the wrong code style due to indentation under the unrecognized admonition, which is fine. * Line 16 is ignored as part of the assumed indented code block, but would ideally be flagged as a wrong code style since it is over indented again. * Line 18 is ignored as well but should be flagged for skipping heading levels * Line 21 is ignored but should be flagged for inconsistent list marker style * Line 25 is flagged for the wrong code style due to indentation under the unrecognized snippet syntax * Line 26 is ignored as part of another assumed indented code block, but should be flagged for inconsistent list marker style

kerem commented

2026-03-03 01:29:49 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jan 16, 2026):

If a document's structure is wildly off, I don't see a straightforward way to accomplish what you suggest without reparsing and reevaluating the relevant sections. But that requires knowing exactly what the structural problem is and how to fix it - and being able to do so reliably. Or else it requires understanding the specific Markdown flavor you're using, but that goes against the philosophy of using CommonMark plus GFM which covers the vast majority of scenarios out there.

@DavidAnson commented on GitHub (Jan 16, 2026): If a document's structure is wildly off, I don't see a straightforward way to accomplish what you suggest without reparsing and reevaluating the relevant sections. But that requires knowing exactly what the structural problem is and how to fix it - and being able to do so reliably. Or else it requires understanding the specific Markdown flavor you're using, but that goes against the philosophy of using CommonMark plus GFM which covers the vast majority of scenarios out there.

kerem commented

2026-03-03 01:29:49 +03:00

Author

Owner

@nbanyan commented on GitHub (Jan 16, 2026):

My assumption was that it'd just be a matter of not having it skip indented code text while evaluating.
Would doing precheck for indented code blocks (to get the warnings) then stripping the excess indentation in memory before a normal check work for this (although this would require recursion to catch nested instances...)? It might be easier than recursively evaluating each indented code block afterwards, although that might work also.

If any of those could work, it'd allow catching the example errors without requiring specific knowledge of the non-common syntax.

@nbanyan commented on GitHub (Jan 16, 2026): My assumption was that it'd just be a matter of not having it skip indented code text while evaluating. Would doing precheck for indented code blocks (to get the warnings) then stripping the excess indentation in memory before a normal check work for this (although this would require recursion to catch nested instances...)? It might be easier than recursively evaluating each indented code block afterwards, although that might work also. If any of those could work, it'd allow catching the example errors without requiring specific knowledge of the non-common syntax.