[GH-ISSUE #221] Use a markdown interpreter that doesn't rely on CommonMark #190

New issue

Closed

opened 2026-03-03 01:24:33 +03:00 by kerem · 3 comments

kerem commented

2026-03-03 01:24:33 +03:00

Owner

Originally created by @TheJaredWilcurt on GitHub (Sep 13, 2019).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/221

I've had to add a new section to my MarkdownLint ruleset called "Unfixable Issues" because CommonMark doesn't know how to make bulleted lists inside numbered lists consistently.

https://github.com/tjw-lint/tjw-markdownlint-rules#unfixible-issues

The only fix for this from MarkdownLint's perspective would be to use a different interpreter that does not rely on CommonMark, since markdown-it's goal seems to be to exclusively support CommonMark for some reason.

A better alternative would be to use marked.js instead of markdown-it as an interpretter. Marked.js supports CommonMark, but also supports other flavors as well. Upon switching, you could default to CommonMark, so those updating MarkdownLint would not see breaking changes, but would allow for adding a setting to .markdownlint.yml files to disable CommonMark or use GFM (or potentially pass along an entire options object through MarkdownLint directly to Marked.js).

This would be a much more logical approach, as different projects use different interpreters and could use MarkdownLint on all of them without any problems.

Also comparing the repos for marked.js and markdown-it, Marked.js is twice as Used, Watched, Starred, and Forked.

Originally created by @TheJaredWilcurt on GitHub (Sep 13, 2019). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/221 I've had to add a new section to my MarkdownLint ruleset called "Unfixable Issues" because CommonMark doesn't know how to make bulleted lists inside numbered lists consistently. * https://github.com/tjw-lint/tjw-markdownlint-rules#unfixible-issues The only fix for this from MarkdownLint's perspective would be to use a different interpreter that does not rely on CommonMark, since markdown-it's goal seems to be to exclusively support CommonMark for some reason. A better alternative would be to use `marked.js` instead of `markdown-it` as an interpretter. Marked.js supports CommonMark, but also supports other flavors as well. Upon switching, you could default to CommonMark, so those updating MarkdownLint would not see breaking changes, but would allow for adding a setting to `.markdownlint.yml` files to disable CommonMark or use GFM (or potentially pass along an entire options object through MarkdownLint directly to Marked.js). This would be a much more logical approach, as different projects use different interpreters and could use MarkdownLint on all of them without any problems. Also comparing the repos for `marked.js` and `markdown-it`, Marked.js is twice as Used, Watched, Starred, and Forked.

kerem

2026-03-03 01:24:33 +03:00

closed this issue
added the
refactoring
label

kerem commented

2026-03-03 01:24:34 +03:00

Author

Owner

@DavidAnson commented on GitHub (Sep 13, 2019):

This would be an enormous, likely-breaking change. When I started markdownlint, I did evaluate other options. I don't recall all of my priorities at the time - and some of my concerns may have been addressed in the years since - but markdown-it seemed like the best option to me. CommonMark is generally excellent to work with because the specification is so thorough and explicit about what the correct behavior should be. The original PERL script for Markdown is notoriously vague and inconsistent. Looking very briefly at the marked.js documentation just now, it's not clear that it surfaces the level of detail necessary for this project. However, I will leave this issue open and revisit it when I have time to do a more in-depth analysis.

@DavidAnson commented on GitHub (Sep 13, 2019): This would be an enormous, likely-breaking change. When I started markdownlint, I did evaluate other options. I don't recall all of my priorities at the time - and some of my concerns may have been addressed in the years since - but markdown-it seemed like the best option to me. CommonMark is generally excellent to work with because the specification is so thorough and explicit about what the correct behavior should be. The original PERL script for Markdown is notoriously vague and inconsistent. Looking very briefly at the marked.js documentation just now, it's not clear that it surfaces the level of detail necessary for this project. However, I will leave this issue open and revisit it when I have time to do a more in-depth analysis.

kerem commented

2026-03-03 01:24:34 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jun 13, 2021):

I don't foresee changing from CommonMark and will close this issue.

@DavidAnson commented on GitHub (Jun 13, 2021): I don't foresee changing from CommonMark and will close this issue.

kerem commented

2026-03-03 01:24:34 +03:00

Author

Owner

@TheJaredWilcurt commented on GitHub (Jun 19, 2021):