[GH-ISSUE #1331] MD028: Add specific handling of GitHub-style callouts #2509

New issue

Closed

opened 2026-03-07 20:08:26 +03:00 by kerem · 3 comments

kerem commented

2026-03-07 20:08:26 +03:00

Owner

Originally created by @volker-raschek on GitHub (Aug 19, 2024).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1331

Hello everyone,
GitHub has introduced Markdown callouts in the past. These are or have already been adopted by other VCSs - for example by Gitea. In this issue are all callouts as example defined.

If I now write several callouts in a row, this violates the MD028 rule. I understand the rule and would like to keep it, but there should be an exception for a callout.

Example of callout nesting:

# Title

> [!TIP] You can use a container image mirror [germany - west](https://example.com) to increase the download speed.

> [!WARNING]
> Please do not use the latest image, because ...

Tip

You can use a container image mirror germany - west to increase the download speed.

Warning

Please do not use the latest image, because ...

Please adapt MD028 to allow nested callouts by default or implement a setting to allow it generally.

Originally created by @volker-raschek on GitHub (Aug 19, 2024). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1331 Hello everyone, GitHub has introduced Markdown callouts in the past. These are or have already been adopted by other VCSs - for example by [Gitea](https://github.com/go-gitea/gitea/issues/29032). In this issue are all callouts as example defined. If I now write several callouts in a row, this violates the MD028 rule. I understand the rule and would like to keep it, but there should be an exception for a callout. Example of callout nesting: ```text # Title > [!TIP] You can use a container image mirror [germany - west](https://example.com) to increase the download speed. > [!WARNING] > Please do not use the latest image, because ... ``` > [!TIP] > You can use a container image mirror [germany - west](https://example.com) to increase the download speed. > [!WARNING] > Please do not use the latest image, because ... Please adapt MD028 to allow nested callouts by default or implement a setting to allow it generally.

kerem

2026-03-07 20:08:26 +03:00

closed this issue
added the
question
label

kerem commented

2026-03-07 20:08:27 +03:00

Author

Owner

@DavidAnson commented on GitHub (Aug 19, 2024):

As you show, the GitHub parser does not merge consecutive block quotes, so the rationale of MD028 does not apply there. Why not disable the rule?

@DavidAnson commented on GitHub (Aug 19, 2024): As you show, the GitHub parser does not merge consecutive block quotes, so the rationale of MD028 does not apply there. Why not disable the rule?

kerem commented

2026-03-07 20:08:27 +03:00

Author

Owner

@volker-raschek commented on GitHub (Aug 19, 2024):

Well, that's not true. I use in VSCode the markdownlint extention v0.55.0. The point at which MD028 is violated is marked in yellow.

I have a container image with markdownlint 0.41.0, which I use for the demo:

$ cat > /tmp/README.md <<EOF
# Title

> [!NOTE]
> NOTE

> [!TIP]
> TIP

EOF

$ docker run --rm --volume /tmp:/tmp docker.io/volkerraschek/markdownlint:0.41.0 /tmp/README.md 
/tmp/README.md:5 MD028/no-blanks-blockquote Blank line inside blockquote

Sure, I can simply deactivate the rule, but the rule would change the behavior of normal block quotes, too. This is not what I want.

The question I am asking myself is, how can a set of rules be implemented that validates the following Markdown as invalid with MD028 for non GitHub-style collouts?

$ cat > /tmp/README.md <<EOF
# Title

> [!NOTE]
> NOTE

> [!TIP]
> TIP

Hello

> World

> Foo Bar
EOF

$ docker run --rm --volume /tmp:/tmp docker.io/volkerraschek/markdownlint:0.41.0 /tmp/README.md 
/tmp/README.md:12 MD028/no-blanks-blockquote Blank line inside blockquote

@volker-raschek commented on GitHub (Aug 19, 2024): Well, that's not true. I use in VSCode the markdownlint extention v0.55.0. The point at which MD028 is violated is marked in yellow. ![Bildschirmfoto vom 2024-08-19 18-47-00](https://github.com/user-attachments/assets/de838513-e563-4ca0-96ee-7e1812c7298b) I have a container image with markdownlint 0.41.0, which I use for the demo: ```bash $ cat > /tmp/README.md <<EOF # Title > [!NOTE] > NOTE > [!TIP] > TIP EOF $ docker run --rm --volume /tmp:/tmp docker.io/volkerraschek/markdownlint:0.41.0 /tmp/README.md /tmp/README.md:5 MD028/no-blanks-blockquote Blank line inside blockquote ``` Sure, I can simply deactivate the rule, but the rule would change the behavior of normal block quotes, too. This is not what I want. The question I am asking myself is, how can a set of rules be implemented that validates the following Markdown as invalid with MD028 for non GitHub-style collouts? ```bash $ cat > /tmp/README.md <<EOF # Title > [!NOTE] > NOTE > [!TIP] > TIP Hello > World > Foo Bar EOF $ docker run --rm --volume /tmp:/tmp docker.io/volkerraschek/markdownlint:0.41.0 /tmp/README.md /tmp/README.md:12 MD028/no-blanks-blockquote Blank line inside blockquote ```

kerem commented

2026-03-07 20:08:27 +03:00

Author

Owner

@DavidAnson commented on GitHub (Aug 19, 2024):

I may not have been clear. What I was pointing out is that GitHub does not seem to merge consecutive block quotes that are separated by an empty line. This appears to be the case whether or not they are callouts. Rule MD028 exists to warn people about the problem of unexpected behavior for parsers that DO merge, but GitHub does not seem to be such a parser and therefore the rule does not seem necessary in that context. I propose that you can disable MD028 for GitHub scenarios regardless of whether callouts are being used.

@DavidAnson commented on GitHub (Aug 19, 2024): I may not have been clear. What I was pointing out is that GitHub does not seem to merge consecutive block quotes that are separated by an empty line. This appears to be the case whether or not they are callouts. Rule MD028 exists to warn people about the problem of unexpected behavior for parsers that DO merge, but GitHub does not seem to be such a parser and therefore the rule does not seem necessary in that context. I propose that you can disable MD028 for GitHub scenarios regardless of whether callouts are being used.