Docs: When updating from `eslint-plugin-markdown` other plugins start throwing errors

[michaelfaith]

Docs page(s)

Getting Started section

What documentation issue do you want to solve?

When updating from eslint-plugin-markdown (v5) to @eslint/markdown (v7), which now uses the language feature in its recommended config, rules from other plugins (including ESLint's core recommended config) started throwing errors about various sourceCode functions not being available when attempting to lint a markdown file.

That led me to add a whole number of shareable configs to a big "extends" block with ignores: ['**/*.md'], which doesn't feel like the best approach, but the documentation doesn't really provide any guidance around using the new version of the plugin with other plugins. Before the switch to using language, it worked fine beside other js-oriented configs. Now, it doesn't really, but the docs don't provide any tips or guidance around that.

Example error:

Oops! Something went wrong! :(

ESLint: 9.34.0

TypeError: Error while loading rule 'no-irregular-whitespace': sourceCode.getAllComments is not a function
Occurred while linting C:\Users\michael\src\eslint-plugin-package-json\.github\CODE_OF_CONDUCT.md
    at Object.create (C:\Users\michael\src\eslint-plugin-package-json\node_modules\.pnpm\eslint@9.34.0_jiti@2.5.0\node_modules\eslint\lib\rules\no-irregular-whitespace.js:92:35)
    at createRuleListeners (C:\Users\michael\src\eslint-plugin-package-json\node_modules\.pnpm\eslint@9.34.0_jiti@2.5.0\node_modules\eslint\lib\linter\linter.js:1019:15)
    at C:\Users\michael\src\eslint-plugin-package-json\node_modules\.pnpm\eslint@9.34.0_jiti@2.5.0\node_modules\eslint\lib\linter\linter.js:1151:7

Example config to get around it

{
	extends: [
		eslintPlugin.configs.recommended,
		jsdoc.configs["flat/contents-typescript-error"],
		jsdoc.configs["flat/logical-typescript-error"],
		jsdoc.configs["flat/stylistic-typescript-error"],
		jsonc.configs["flat/recommended-with-json"],
		n.configs["flat/recommended"],
		perfectionist.configs["recommended-natural"],
	],
	ignores: ["**/*.md"],
}

What do you think is the correct solution?

I'm not sure this new feature might help with this eslint/eslint#19462? But, until that lands, it seems like the docs should make onboarding to this plugin a bit easier?

Participation

• I am willing to submit a pull request for this change.

Additional comments

Also, it might be worth mentioning, that it took me forever to realize there was a new package name, in part because the original package name is not deprecated and doesn't point users towards the new name: https://www.npmjs.com/package/eslint-plugin-markdown It might be worth considering marking that package as deprecated with a note about the name change?

[lumirlumir]

Hi, @michaelfaith

It's understandable that @eslint/markdown lacks detailed information about its relationship with eslint-plugin-markdown. I think adding a more detailed explanation would be helpful. Any thoughts on this @eslint/eslint-team?

[nzakas]

Rather than putting this in the README, I'd prefer a separate doc file that's a migration guide from eslint-plugin-markdown to @eslint/markdown. That way we'll have the space for details without making the README too long. (We can link to it from the README, of course.)

I just marked the eslint-plugin-markdown package as deprecated. Thanks for pointing that out.

[michaelfaith]

Thanks

Rather than putting this in the README, I'd prefer a separate doc file that's a migration guide from eslint-plugin-markdown to @eslint/markdown. That way we'll have the space for details without making the README too long. (We can link to it from the README, of course.)

Sounds good. As far as recommended migration path. Is this kind of big ignores block what you'd recommend for using other configs alongside this one, or is there another method that you'd encourage?

{
	extends: [
		eslintPlugin.configs.recommended,
		jsdoc.configs["flat/contents-typescript-error"],
		jsdoc.configs["flat/logical-typescript-error"],
		jsdoc.configs["flat/stylistic-typescript-error"],
		jsonc.configs["flat/recommended-with-json"],
		n.configs["flat/recommended"],
		perfectionist.configs["recommended-natural"],
	],
	ignores: ["**/*.md"],
}

[nzakas]

We recommend using files to narrowly define where you want the configs to be applied.

[Martinspire]

I also think that the ignores or files shouldn't be required for the markdown plugin to not break on other plugins imo or causing problems on other files. Especially when it is only being applied on only markdown files. Also, it could very well just be a problem generated by the @eslint/js package that needs to be fixed, but overall somewhere somebody messed up.

[nzakas]

@Martinspire files or ignores are the only way to guarantee that everything works correctly. That's by design. In the future, we will have better error messaging but fundamentally you'll still need to use files or ignores to avoid issues like this.

[CyberT33N]

So, the issue arises when you use other ESLint plugins alongside the shared flat config. These plugins then get applied to all files, which leads to conflicts with this markdown plugin here — for example, the regular ESLint rules or the Stylistic ESLint plugin. That’s what causes this error.

In other words, it doesn’t help to apply the ESLint Markdown plugin only to Markdown files. You must define proper boundaries (i.e., file patterns) for the other ESLint plugins that conflict with this one and trigger the error.

In general, it’s also considered best practice to restrict each ESLint plugin to the specific file types it should run on. That means you don’t just need a “files” pattern for the plugin, but also ensure that the plugin itself is only executed for those matching files.

{
    files: TS_JS_FILES_PATTERNS,
    name: `${CONFIG_NAMESPACE}:${CONFIG_UPSTREAM_NAME}`,
    plugins: {
        '@stylistic': stylistic
    },
    rules: {
        ...stylistic.configs.all.rules
    }
}