[GH-ISSUE #1012] MD040: Add disallowed_languages #2440

New issue

Open

opened 2026-03-07 20:07:48 +03:00 by kerem · 2 comments

kerem commented

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

Owner

Originally created by @dsanders11 on GitHub (Oct 17, 2023).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1012

Currently MD040 lets you set allowed_languages, but that's not a good fit if you only want to disallow a couple of specific languages. Adding a disallowed_languages parameter could handle that case. Should probably only allow one of those parameters or the other, but not both, since they're contradictory.

Bonus points if disallowed_languages could be a string[] or a mapping of languages to their preferred alternative, e.g.:

"fenced-code-language": {
  "disallowed_languages": {
    "js": "javascript"
  }
}

would produce an error telling the user to use javascript instead of js as the language identifier.

Originally created by @dsanders11 on GitHub (Oct 17, 2023). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1012 Currently MD040 lets you set `allowed_languages`, but that's not a good fit if you only want to disallow a couple of specific languages. Adding a `disallowed_languages` parameter could handle that case. Should probably only allow one of those parameters or the other, but not both, since they're contradictory. Bonus points if `disallowed_languages` could be a `string[]` or a mapping of languages to their preferred alternative, e.g.: ```json "fenced-code-language": { "disallowed_languages": { "js": "javascript" } } ``` would produce an error telling the user to use `javascript` instead of `js` as the language identifier.

kerem added the

enhancement

label

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

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Oct 17, 2023):

I like the idea of providing alternate suggestions, though that could be incorporated into the current implementation. I'm curious why you think it's easier to exclude languages? In the proposed model, someone could accidentally use the identifier "javasript" and it would be okay unless you specifically blocked that in advance. Because the list of valid languages is so small, an allow list (like the current implementation) seems safer?

@DavidAnson commented on GitHub (Oct 17, 2023): I like the idea of providing alternate suggestions, though that could be incorporated into the current implementation. I'm curious why you think it's easier to exclude languages? In the proposed model, someone could accidentally use the identifier "javasript" and it would be okay unless you specifically blocked that in advance. Because the list of valid languages is so small, an allow list (like the current implementation) seems safer?

kerem commented

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

Author

Owner

@dsanders11 commented on GitHub (Oct 17, 2023):

Fair points.

In projects with a large amount of docs covering a wide range of topics (doing a quick count, the Electron docs would need to add 16+ languages to the allow list), I'd personally prefer using a disallow list as it is easier for new contributors who might be introducing a code block with a new language identifier. Usually linting failures just require you to modify your own added content to fix them, but with the allow list a contributor would need to find and understand the markdownlint configuration to update the allow list, which requires a bit more technical knowledge than a contributor adding to Markdown docs may have.

So for me I'd prefer to not add an additional potential barrier to entry for contributors, at the cost of potentially letting errors slip in (like your very valid "javasript" example). I can deal with the latter out-of-band without blocking contributors, and use the disallow list to still cover it 90% of the time (outright typos aren't very common compared to using javascript vs js, etc).

I think there's value in having both options supported, but I can understand if you'd prefer to keep it simpler for maintenance reasons.

@dsanders11 commented on GitHub (Oct 17, 2023): Fair points. In projects with a large amount of docs covering a wide range of topics (doing a quick count, the Electron docs would need to add 16+ languages to the allow list), I'd personally prefer using a disallow list as it is easier for new contributors who might be introducing a code block with a new language identifier. Usually linting failures just require you to modify your own added content to fix them, but with the allow list a contributor would need to find and understand the markdownlint configuration to update the allow list, which requires a bit more technical knowledge than a contributor adding to Markdown docs may have. So for me I'd prefer to not add an additional potential barrier to entry for contributors, at the cost of potentially letting errors slip in (like your very valid "javasript" example). I can deal with the latter out-of-band without blocking contributors, and use the disallow list to still cover it 90% of the time (outright typos aren't very common compared to using `javascript` vs `js`, etc). I think there's value in having both options supported, but I can understand if you'd prefer to keep it simpler for maintenance reasons.