[GH-ISSUE #207] Support for Admonition syntax (non-standard)

kerem commented

2026-03-07 20:03:49 +03:00

Owner

Originally created by @berot3 on GitHub (Jul 17, 2019).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/207

Please add support for Admonitions!

https://python-markdown.github.io/extensions/admonition/

Admonitions are created using the following syntax:

!!! type "optional explicit title within double quotes"
    Any number of other indented markdown elements.

    This is the second paragraph.

Since I am a mkdocs-material user, it would be really great to have this.
Even in a previewer in vscode admonitions are displayed.

Originally created by @berot3 on GitHub (Jul 17, 2019). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/207 Please add support for Admonitions! https://python-markdown.github.io/extensions/admonition/ > Admonitions are created using the following syntax: > > ``` > !!! type "optional explicit title within double quotes" > Any number of other indented markdown elements. > > This is the second paragraph. > ``` Since I am a mkdocs-material user, it would be really great to have this. Even in a previewer in vscode admonitions are displayed.

kerem

2026-03-07 20:03:49 +03:00

closed this issue
added the
question
label

kerem commented

2026-03-07 20:03:50 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jul 17, 2019):

It looks like Admonitions are supported by this markdown-it plug-in: https://www.npmjs.com/package/markdown-it-admonition

You can specify that via the markdownItPlugins option like so: https://github.com/DavidAnson/markdownlint/blob/master/README.md#optionsmarkdownitplugins

Doing so will provide basic parsing support and should make the existing markdownlint rules work a little better with this syntax.

Is that what you are looking for?

@DavidAnson commented on GitHub (Jul 17, 2019): It looks like Admonitions are supported by this `markdown-it` plug-in: https://www.npmjs.com/package/markdown-it-admonition You can specify that via the `markdownItPlugins` option like so: https://github.com/DavidAnson/markdownlint/blob/master/README.md#optionsmarkdownitplugins Doing so will provide basic parsing support and should make the existing `markdownlint` rules work a little better with this syntax. Is that what you are looking for?

kerem commented

2026-03-07 20:03:50 +03:00

Author

Owner

@berot3 commented on GitHub (Jul 19, 2019):

ah cool thanks, will try!

so since admonitions are non-stadard does this mean that markdownlint will never support it by default?

@berot3 commented on GitHub (Jul 19, 2019): ah cool thanks, will try! so since admonitions are non-stadard does this mean that markdownlint will never support it by default?

kerem commented

2026-03-07 20:03:50 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jul 19, 2019):

“Never“ is a long time, but I do try to keep external dependencies to a minimum, so I would prefer her not to bake this in if you’re able to use that extensibility point happily.

@DavidAnson commented on GitHub (Jul 19, 2019): “Never“ is a long time, but I do try to keep external dependencies to a minimum, so I would prefer her not to bake this in if you’re able to use that extensibility point happily.

kerem commented

2026-03-07 20:03:50 +03:00

Author

Owner

@Stanzilla commented on GitHub (Dec 11, 2019):

@DavidAnson Is there a way to enable those plugins from a markdownlintrc file? I tried "markdownItPlugins": ["markdown-it-admonition"] but got nothing.

@Stanzilla commented on GitHub (Dec 11, 2019): @DavidAnson Is there a way to enable those plugins from a `markdownlintrc` file? I tried `"markdownItPlugins": ["markdown-it-admonition"]` but got nothing.

kerem commented

2026-03-07 20:03:50 +03:00

Author

Owner

@DavidAnson commented on GitHub (Dec 11, 2019):

The CLI does not currently support markdown-it plugins.

@DavidAnson commented on GitHub (Dec 11, 2019): The CLI does not currently support markdown-it plugins.

kerem commented

2026-03-07 20:03:50 +03:00

Author

Owner

@Stanzilla commented on GitHub (Dec 11, 2019):

Oh. :(

@Stanzilla commented on GitHub (Dec 11, 2019): Oh. :(

kerem commented

2026-03-07 20:03:51 +03:00

Author

Owner

@miffels commented on GitHub (Jan 24, 2020):

@berot3 @Stanzilla did any of you have luck with what David proposed? I just tried hacking the plugin into the markdownlint-cli options passed to markdownlint, but it doesn't seem to do anything - markdownlint still interprets paragraphs in admonition as indented code blocks:

!!! note
    This is a note

    Second paragraph, which markdownlint reports as code block :(

@DavidAnson just to confirm - below is what you have been proposing, right?

const markdownItAdmonition = require('markdown-it-admonition');
// ...
// https://github.com/igorshubovych/markdownlint-cli/blob/master/markdownlint.js#L237
const markdownItPlugins = [[markdownItAdmonition]];
  const lintOptions = {
    config,
    customRules,
    files,
    markdownItPlugins
  };
// ...
const lintResult = markdownlint.sync(lintOptions);

If we can get this to work, I'd consider making a PR to have this supported in markdownlint-cli.

@miffels commented on GitHub (Jan 24, 2020): @berot3 @Stanzilla did any of you have luck with what David proposed? I just tried hacking the plugin into the `markdownlint-cli` options passed to `markdownlint`, but it doesn't seem to do anything - `markdownlint` still interprets paragraphs in admonition as indented code blocks: ``` !!! note This is a note Second paragraph, which markdownlint reports as code block :( ``` @DavidAnson just to confirm - below is what you have been proposing, right? ``` const markdownItAdmonition = require('markdown-it-admonition'); // ... // https://github.com/igorshubovych/markdownlint-cli/blob/master/markdownlint.js#L237 const markdownItPlugins = [[markdownItAdmonition]]; const lintOptions = { config, customRules, files, markdownItPlugins }; // ... const lintResult = markdownlint.sync(lintOptions); ``` If we can get this to work, I'd consider making a PR to have this supported in `markdownlint-cli`.

kerem commented

2026-03-07 20:03:51 +03:00

Author

Owner

@Stanzilla commented on GitHub (Jan 24, 2020):

Sadly not, kinda gave up on it for now, sorry 🙁

@Stanzilla commented on GitHub (Jan 24, 2020): Sadly not, kinda gave up on it for now, sorry 🙁

kerem commented

2026-03-07 20:03:51 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jan 24, 2020):

@miffels, yes, that’s my proposal. I’d suggest trying this directly with the markdownlint library first. It might help to examine the markdown-it token stream before/after adding the plugin. Also, have a look at the last 4 test cases here which exercise this feature: https://github.com/DavidAnson/markdownlint/blob/master/test/markdownlint-test.js

@DavidAnson commented on GitHub (Jan 24, 2020): @miffels, yes, that’s my proposal. I’d suggest trying this directly with the `markdownlint` library first. It might help to examine the `markdown-it` token stream before/after adding the plugin. Also, have a look at the last 4 test cases here which exercise this feature: https://github.com/DavidAnson/markdownlint/blob/master/test/markdownlint-test.js

kerem commented

2026-03-07 20:03:51 +03:00

Author

Owner

@miffels commented on GitHub (Mar 24, 2020):

@DavidAnson Just took a quick look - thanks for pointing out the tests, a lot better than my recent meddling with your code base :P

The issue currently seems to be that

The syntax supported by the plugin is different from what I need, i.e.
```
!!! note
content
!!!
```
vs.
```
!!! note
    content
```
The plugin seems to be no longer actively maintained - there is a bunch of issues (one pointing out the above syntax difference between markdown-it admonition and pymdown admonition) that haven't been replied to in a year or two. @berot3 has been involved in those discussions as well, as it turns out.
I added the plugin and it seems to block the test from completing - it's just hanging there. Haven't debugged into it, but based on the other issues this is where I will stop now.

Currently looks like the only way forward would be to publish a new plugin that would address the issue. I am hesitant to do that due to corporate guidelines.

@miffels commented on GitHub (Mar 24, 2020): @DavidAnson Just took a quick look - thanks for pointing out the tests, a lot better than my recent meddling with your code base :P The issue currently seems to be that 1. The syntax supported by the plugin is different from what I need, i.e. ```markdown !!! note content !!! ``` vs. ```markdown !!! note content ``` 2. The plugin seems to be no longer actively maintained - there is a bunch of issues (one pointing out the above syntax difference between markdown-it admonition and pymdown admonition) that haven't been replied to in a year or two. @berot3 has been involved in those discussions as well, as it turns out. 3. I added the plugin and it seems to block the test from completing - it's just hanging there. Haven't debugged into it, but based on the other issues this is where I will stop now. Currently looks like the only way forward would be to publish a new plugin that would address the issue. I am hesitant to do that due to corporate guidelines.

kerem commented

2026-03-07 20:03:51 +03:00

Author

Owner

@g13013 commented on GitHub (Mar 24, 2020):

why is this issue closed ?

@g13013 commented on GitHub (Mar 24, 2020): why is this issue closed ?

kerem commented

2026-03-07 20:03:51 +03:00

Author

Owner

@DavidAnson commented on GitHub (Mar 25, 2020):

You can scroll up to see the issue history. It was closed by the opener on July 22, 2019. There is some context just above that.

@DavidAnson commented on GitHub (Mar 25, 2020): You can scroll up to see the issue history. It was closed by the opener on July 22, 2019. There is some context just above that.

kerem commented

2026-03-07 20:03:51 +03:00

Author

Owner

@g13013 commented on GitHub (Mar 25, 2020):

Yeah i've read the history and i don't think there is viable solution for this. can we reopen ?

@g13013 commented on GitHub (Mar 25, 2020): Yeah i've read the history and i don't think there is viable solution for this. can we reopen ?

kerem commented

2026-03-07 20:03:51 +03:00

Author

Owner

@DavidAnson commented on GitHub (Mar 25, 2020):

Because Admonitions are not part of the CommonMark specification and they are supported by a markdown-it plug-in and plug-ins are supported by this library, there aren’t any changes to this library that I am planning to make in the near term.

You could re-open this issue for tracking, but it’s not my plan to add library support for everybody’s favorite custom extensions to the Markdown language. There are too many and they can conflict with each other.

@DavidAnson commented on GitHub (Mar 25, 2020): Because Admonitions are not part of the CommonMark specification and they are supported by a markdown-it plug-in and plug-ins are supported by this library, there aren’t any changes to this library that I am planning to make in the near term. You could re-open this issue for tracking, but it’s not my plan to add library support for everybody’s favorite custom extensions to the Markdown language. There are too many and they can conflict with each other.

Rows
Columns

[GH-ISSUE #207] Support for Admonition syntax (non-standard) #2026