diff --git a/website/.vitepress/config.js b/website/.vitepress/config.js index 1a86f5cc..d9c7889d 100644 --- a/website/.vitepress/config.js +++ b/website/.vitepress/config.js @@ -186,6 +186,10 @@ export default defineConfig({ text: 'Configurations', link: 'configurations', }, + { + text: 'Migration', + link: 'migration', + }, { text: 'Dependency Versions', link: 'dependency-versions', @@ -200,7 +204,7 @@ export default defineConfig({ { base: '/docs/community/', text: 'Community', - collapsed: true, + collapsed: false, items: [ { text: 'Code of Conduct', diff --git a/website/docs/get-started/configurations.md b/website/docs/get-started/configurations.md index c4d96454..c40c0237 100644 --- a/website/docs/get-started/configurations.md +++ b/website/docs/get-started/configurations.md @@ -1,8 +1,18 @@ # Shared Configurations -[ESLint shareable configurations](https://eslint.org/docs/latest/extend/shareable-configs) exist to provide a comprehensive list of rules settings that you can start with. `eslint-plugin-mark` includes built-in configurations you can extend from to pull in the recommended starting rules. +[ESLint shareable configurations](https://eslint.org/docs/latest/extend/shareable-configs) exist to provide a comprehensive list of rules settings that you can start with. [`eslint-markdown`](https://github.com/lumirlumir/npm-eslint-plugin-mark) includes built-in configurations you can extend from to pull in the recommended starting rules. -::: danger +::: warning Stability of Configurations + +With the exception of [`all`](#all), every configuration is considered "stable". Rule additions and removals are treated as ***breaking changes*** and will only be done in major version bumps. + +--- + +NOTE: `eslint-markdown` is currently in active `0.x` development, so configurations may receive ***breaking changes*** in minor version bumps until it reaches `1.0.0`. + +::: + +::: danger Supported Environments - This plugin only supports ***ECMAScript Modules (ESM)*** configurations. CommonJS configurations are not supported. - This plugin only supports ***ESLint [`v9.15.0`](https://github.com/eslint/eslint/releases/tag/v9.15.0) and above***. @@ -11,41 +21,41 @@ ## Configuration File Location -Create an `eslint.config.mjs` or `eslint.config.mts` config file in the root of your project, and populate it with the following: +Create an `eslint.config.{js,mjs}` or `eslint.config.{ts,mts}` config file in the root of your project, and populate it with the following: ::: code-group ```js [eslint.config.mjs] // @ts-check -import mark from 'eslint-plugin-mark'; +import { defineConfig } from 'eslint/config'; +import markdown from 'eslint-markdown'; -/** @type {import("eslint").Linter.Config[]} */ -export default [ - mark.configs.recommendedGfm, -]; +export default defineConfig([ + markdown.configs.recommended, +]); ``` ```ts [eslint.config.mts] -import mark from 'eslint-plugin-mark'; -import type { Linter } from 'eslint'; +import { defineConfig } from 'eslint/config'; +import markdown from 'eslint-markdown'; -export default [ - mark.configs.recommendedGfm, -] as Linter.Config[]; +export default defineConfig([ + markdown.configs.recommended, +]); ``` ::: ## Configurations -### `mark.configs.recommendedCommonmark` +### `recommended` -### `mark.configs.recommendedGfm` +### `stylistic` -### `mark.configs.allCommonmark` +### `base` -### `mark.configs.allGfm` +### `all` ## Running ESLint diff --git a/website/docs/get-started/introduction.md b/website/docs/get-started/introduction.md index b6320719..a19fe664 100644 --- a/website/docs/get-started/introduction.md +++ b/website/docs/get-started/introduction.md @@ -6,6 +6,10 @@ This project aims to align with this trend by providing various rules to improve Simply lint your Markdown files using the same tool you use for JavaScript, TypeScript, and other source code files. +## GOAL + +Our goal is to provide a set of ESLint rules that help you write better Markdown documents and also provide a complete way to migrate from other famous existing Markdown linters like `markdownlint`, `remark-lint`, and `textlint`. + ## Limitations This plugin **does not include any formatting rules**. It only includes rules that check for common issues in Markdown files. diff --git a/website/docs/get-started/migration.md b/website/docs/get-started/migration.md new file mode 100644 index 00000000..633c6fc2 --- /dev/null +++ b/website/docs/get-started/migration.md @@ -0,0 +1,27 @@ +# Migration Guide + +This chapter provides guidance for migrating to `eslint-markdown` from other popular Markdown linting tools like [`@eslint/markdown`](https://github.com/eslint/markdown), [`markdownlint`](https://github.com/DavidAnson/markdownlint), `remark-lint`, and `textlint`. + +## Migrating from [`@eslint/markdown`](https://github.com/eslint/markdown) + +`eslint-markdown` is a complete super-set of `@eslint/markdown`, so migration is straightforward. + +You can use `eslint-markdown` as a drop-in replacement for `@eslint/markdown` by updating your ESLint configuration to use `eslint-markdown`'s recommended configuration. + +Every rule provided by `@eslint/markdown` is included in this package. (NOTE: I'm also a dedicated maintainer of `@eslint/markdown`) + +Follow these steps to migrate your project: + +## Migrating from [`markdownlint`](https://github.com/DavidAnson/markdownlint) + +If you are a user of [`markdownlint`](https://github.com/DavidAnson/markdownlint), [`markdownlint-cli`](https://github.com/igorshubovych/markdownlint-cli), or [`markdownlint-cli2`](https://github.com/DavidAnson/markdownlint-cli2) + +TODO + +## Migrating from `remark-lint` + +TODO + +## Mirating from `textlint` + +TODO