docs: add migration docs #559

michaelfaith · 2025-10-12T19:59:29Z

Prerequisites checklist

I have read the contributing guidelines.

What changes did you make? (Give an overview)

This change adds a new migration.md file where details about major migrations can be documented. The first section is details about migrating from the previous implementation eslint-plugin-markdown.

fixes #517

This change adds a new migration.md file where details about major migrations can be documented. The first section is details about migrating from the previous implementation `eslint-plugin-markdown`.

lumirlumir

Hi @michaelfaith, could you take a look at the CI failures?

The failure related to the Markdown document will be resolved once we add the following line:

markdown/docs/rules/no-bare-urls.md

Lines 14 to 18 in 868153b

    
           ## Rule Details 
        
           > [!IMPORTANT] <!-- eslint-disable-line -- This should be fixed in https://github.com/eslint/markdown/issues/294 --> 
        
           > 
        
           > This rule requires `language: "markdown/gfm"`.

The Bun CI failure should be resolved once #555 is merged.

(If this PR needs to be merged quickly, it can be resolved by adding @types/unist, @types/mdast, and semver to the dev dependencies.)

michaelfaith · 2025-10-14T17:45:45Z

Hi @michaelfaith, could you take a look at the CI failures?

The failure related to the Markdown document will be resolved once we add the following line:



markdown/docs/rules/no-bare-urls.md

Lines 14 to 18 in 868153b

## Rule Details

> [!IMPORTANT] 

>

> This rule requires `language: "markdown/gfm"`.

The Bun CI failure should be resolved once #555 is merged.

(If this PR needs to be merged quickly, it can be resolved by adding @types/unist, @types/mdast, and semver to the dev dependencies.)

Thanks! I made those updates

lumirlumir

Thanks for working on this issue! The migration guide looks good.

However, I noticed a few things missing, so I've left some comments throughout the documentation.

lumirlumir · 2025-10-15T08:57:49Z

docs/migration.md

+
+<!-- eslint-disable-next-line markdown/no-missing-label-refs -- This should be fixed in https://github.com/eslint/markdown/issues/294 -->
+> [!NOTE]
+> `@eslint/markdown` requires that you're on at least ESLint v9.


Suggested change

> `@eslint/markdown` requires that you're on at least ESLint v9.

> `@eslint/markdown` requires that you're on at least ESLint v9.15.0.

Since @eslint/markdown uses meta.defaultOptions internally, which was introduced in ESLint 9.15.0, I think it would be helpful to specify version 9.15.0.

markdown/src/rules/no-multiple-h1.js

Lines 61 to 66 in 868153b

defaultOptions: [

{

frontmatterTitle:

"^(?!\\s*['\"]title[:=]['\"])\\s*\\{?\\s*['\"]?title['\"]?\\s*[:=]",

},

],

markdown/README.md

Line 20 in 868153b

Install the plugin alongside ESLint v9.15.0 or greater.

Sounds good. Should that be declared in the peerDeps for the package then?

docs/migration.md

lumirlumir · 2025-10-15T09:10:11Z

docs/migration.md

+```js
+// eslint.config.js
+import { defineConfig } from "eslint/config";
+import markdown from "@eslint/markdown";
+
+export default defineConfig([
+  markdown.configs.recommended,
+  markdown.configs.processor,
+
+  // your other configs
+]);
+```


Unfortunately, the current ESLint implementation does not support using processor and recommended configs together:

Bug: Cannon use processor and recommended configs together #353

Bug: Add combined mode to run Markdown rules and code-block linting concurrently for .md files #560

It might be helpful to update it and add a note that processor and recommended configs cannot be used together for now.

Updated and added a WARNING note about using them together. Let me know what you think.

docs/migration.md

lumirlumir · 2025-10-15T09:22:52Z

docs/migration.md

Could we also add a link in /README.md to docs/migration.md?

For example, adding a link in "## Migration from eslint-plugin-markdown" section, similar to the ## Usage or ## Editor Integrations sections, would be great.

markdown/README.md

Line 16 in 868153b

## Usage

markdown/README.md

Line 223 in 868153b

## Editor Integrations

Add the link to the README

michaelfaith · 2025-10-15T11:29:02Z

Thanks for the feedback. I believe I've addressed everything. Let me know if there are any other updates you'd recommend.

docs/migration.md

nzakas · 2025-10-15T19:04:37Z

docs/migration.md

+    },
+    extends: ["js/recommended"],
+  },
+  markdown.configs.recommended,


We're encouraging people to use extends now:

Suggested change

markdown.configs.recommended,

{

files: ["**/*.md"],

plugins: {

markdown

},

extends: ["markdown/recommended"]

}

Sounds good. And that's the case even for configs that already declare files and plugins in the configs?

docs/migration.md

docs: add migration docs

1ae2b0b

This change adds a new migration.md file where details about major migrations can be documented. The first section is details about migrating from the previous implementation `eslint-plugin-markdown`.

eslint-github-bot bot added the documentation label Oct 12, 2025

eslintbot added this to Triage Oct 12, 2025

eslint-github-bot bot mentioned this pull request Oct 12, 2025

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

Open

1 task

github-project-automation bot moved this to Needs Triage in Triage Oct 12, 2025

michaelfaith marked this pull request as ready for review October 12, 2025 19:59

aladdin-add moved this from Needs Triage to Implementing in Triage Oct 14, 2025

aladdin-add added the accepted label Oct 14, 2025

lumirlumir reviewed Oct 14, 2025

View reviewed changes

address lint errors

3f574bb

lumirlumir requested changes Oct 15, 2025

View reviewed changes

michaelfaith added 3 commits October 15, 2025 06:17

add additional package managers and fix important notices

4c9541a

update config section

517e57a

add link to README

cc39e9e

michaelfaith requested a review from lumirlumir October 15, 2025 11:29

nzakas reviewed Oct 15, 2025

View reviewed changes

address feedback

1ebbe17

	## Rule Details

	> [!IMPORTANT] <!-- eslint-disable-line -- This should be fixed in https://github.com/eslint/markdown/issues/294 -->
	>
	> This rule requires `language: "markdown/gfm"`.

	> `@eslint/markdown` requires that you're on at least ESLint v9.
	> `@eslint/markdown` requires that you're on at least ESLint v9.15.0.

	defaultOptions: [
	{
	frontmatterTitle:
	"^(?!\\s['\"]title[:=]['\"])\\s\\{?\\s['\"]?title['\"]?\\s[:=]",
	},
	],

-  markdown.configs.recommended,
+  {
+      files: ["**/*.md"],
+      plugins: {
+        markdown
+      },
+      extends: ["markdown/recommended"]
+  }

docs: add migration docs #559

Are you sure you want to change the base?

docs: add migration docs #559

Conversation

michaelfaith commented Oct 12, 2025

Prerequisites checklist

What changes did you make? (Give an overview)

Uh oh!

lumirlumir left a comment

Choose a reason for hiding this comment

Uh oh!

michaelfaith commented Oct 14, 2025

Uh oh!

lumirlumir left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lumirlumir Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

lumirlumir Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

michaelfaith commented Oct 15, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

lumirlumir left a comment •

edited

Loading

lumirlumir Oct 15, 2025 •

edited

Loading

lumirlumir Oct 15, 2025 •

edited

Loading