[GH-ISSUE #479] Allow parsing MyST-flavored Markdown #392

New issue

Closed

opened 2026-03-03 01:26:30 +03:00 by kerem · 3 comments

kerem commented

2026-03-03 01:26:30 +03:00

Owner

Originally created by @cgranade on GitHub (Jan 12, 2022).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/479

The Sphinx and Jupyter-Book projects both make use of MyST, a Markdown variant specialized for formatting documentation and interactive books (https://myst-parser.readthedocs.io/en/latest/index.html). In particular, MyST extends Markdown with a few concepts from reStructuredText (an alternative plain-text format historically used by Sphinx), such as allowing plugins to add new element and block types. For example, the following MyST markup instructs the Sphinx toctree plugin to typeset a table of contents with depth 2, and include several pages in the generated ToC.

:::{toctree}
---
maxdepth: 2
---

parser
generator
jit
:::

Currently, markdownlint seems to interpret the above as a section called :::{toctree} denoted with setext-style heading markers, and raises warnings about the use of setext versus atx:

Warning: docs/api-reference/index.md:3 MD003/heading-style/header-style Heading style [Expected: atx; Actual: setext]
Warning: docs/api-reference/index.md:3 MD022/blanks-around-headings/blanks-around-headers Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: ":::{toctree}"]
Warning: docs/api-reference/index.md:5 MD003/heading-style/header-style Heading style [Expected: atx; Actual: setext]
Warning: docs/api-reference/index.md:5 MD022/blanks-around-headings/blanks-around-headers Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Above] [Context: "maxdepth: 2"]

If possible and reasonable, it would be really helpful to be able to provide an option that allows for markdownlint to ignore MyST-style syntax.

Thank you for an awesome project! 💕

Originally created by @cgranade on GitHub (Jan 12, 2022). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/479 The Sphinx and Jupyter-Book projects both make use of MyST, a Markdown variant specialized for formatting documentation and interactive books (https://myst-parser.readthedocs.io/en/latest/index.html). In particular, MyST extends Markdown with a few concepts from reStructuredText (an alternative plain-text format historically used by Sphinx), such as allowing plugins to add new element and block types. For example, the following MyST markup instructs the Sphinx toctree plugin to typeset a table of contents with depth 2, and include several pages in the generated ToC. ```markdown :::{toctree} --- maxdepth: 2 --- parser generator jit ::: ``` Currently, markdownlint seems to interpret the above as a section called `:::{toctree}` denoted with setext-style heading markers, and raises warnings about the use of setext versus atx: ``` Warning: docs/api-reference/index.md:3 MD003/heading-style/header-style Heading style [Expected: atx; Actual: setext] Warning: docs/api-reference/index.md:3 MD022/blanks-around-headings/blanks-around-headers Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: ":::{toctree}"] Warning: docs/api-reference/index.md:5 MD003/heading-style/header-style Heading style [Expected: atx; Actual: setext] Warning: docs/api-reference/index.md:5 MD022/blanks-around-headings/blanks-around-headers Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Above] [Context: "maxdepth: 2"] ``` If possible and reasonable, it would be really helpful to be able to provide an option that allows for markdownlint to ignore MyST-style syntax. Thank you for an awesome project! 💕

kerem

2026-03-03 01:26:30 +03:00

closed this issue
added the
question
label

kerem commented

2026-03-03 01:26:31 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jan 12, 2022):

The general way to do this is to reference a markdown-it plugin that supports the particular syntax you want. This is how support for math blocks is added, for example. I don't see a plugin for MyST, but perhaps you can find one or write one. I want to keep the core library as close to CommonMark as possible for the broadest utility.

https://www.npmjs.com/search?q=keywords:markdown-it-plugin

@DavidAnson commented on GitHub (Jan 12, 2022): The general way to do this is to reference a markdown-it plugin that supports the particular syntax you want. This is how support for math blocks is added, for example. I don't see a plugin for MyST, but perhaps you can find one or write one. I want to keep the core library as close to CommonMark as possible for the broadest utility. https://www.npmjs.com/search?q=keywords:markdown-it-plugin

kerem commented

2026-03-03 01:26:31 +03:00

Author

Owner

@micahjsmith commented on GitHub (Feb 8, 2023):

Also looking to figure this out. Looks like there is now https://www.npmjs.com/package/markdown-it-myst-extras Are there docs/snippets on how to configure markdownlint CLI to use this plugin?

@micahjsmith commented on GitHub (Feb 8, 2023): Also looking to figure this out. Looks like there is now https://www.npmjs.com/package/markdown-it-myst-extras Are there docs/snippets on how to configure markdownlint CLI to use this plugin?

kerem commented

2026-03-03 01:26:31 +03:00

Author

Owner

@DavidAnson commented on GitHub (Feb 8, 2023):

markdownlint-cli does not support markdown-it plugins, but markdownlint-cli2 does. Documentation is here and there are examples in the repo: https://github.com/DavidAnson/markdownlint-cli2#markdownlint-cli2jsonc

@DavidAnson commented on GitHub (Feb 8, 2023): markdownlint-cli does not support markdown-it plugins, but markdownlint-cli2 does. Documentation is here and there are examples in the repo: https://github.com/DavidAnson/markdownlint-cli2#markdownlint-cli2jsonc

kerem referenced this issue

2026-03-07 20:05:17 +03:00

[GH-ISSUE #392] Features contains a language reference: undefined #2177