docs: add migration docs

[michaelfaith]

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

[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:

<!-- eslint-disable-line -- This should be fixed in https://github.com/eslint/markdown/issues/294 -->

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]

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:

<!-- eslint-disable-line -- This should be fixed in https://github.com/eslint/markdown/issues/294 -->

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.)

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.

[michaelfaith]

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

[nzakas]

We're encouraging people to use extends now:

Suggested change

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

[michaelfaith]

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

[michaelfaith]

Updated

[lumirlumir]

LGTM, thanks!

Would like @nzakas and others to verify before merging.

[nzakas]

LGTM. Thanks.