eslint-plugin-md

An ESLint plugin to lint and fix markdown files. It uses amazing remark-lint
under the hood. Also enables using prettier to automatically format your markdown files right from eslint!

Motivation

ESLint is a tool for linting Javascript. There is another plugin called eslint-plugin-markdown, however it is still
only linting Javascript parts inside *.md files, and leaves Markdown itself untouched.

Wouldn't it be cool, if we could use ESLint to enforce style of Markdown itself? That is what this plugin is for!

Installation

You'll first need to install ESLint:

``bash
$ npm i eslint --save-dev


or


$ yarn add -D eslint
`

Next, install eslint-plugin-md:

`bash
$ npm install eslint-plugin-md --save-dev


or


$ yarn add -D eslint-plugin-md
`

Note: If you installed ESLint globally (using the npm -g or yarn global) then you must also install
eslint-plugin-md globally.

Usage

Add plugin:md/recommended config to extends section of your your .eslintrc configuration file

`js
// .eslintrc.js
module.exports = {
extends: ['plugin:md/recommended'],
overrides: [
{
files: ['*.md'],
parser: 'markdown-eslint-parser',
},
],
}
`

And this is it! By default it will apply all rules from
Markdown style guide.

Note: By default ESLint won't lint \*.md files. So:

- If you use ESLint from CLI, use --ext parameter (e.g. eslint . --ext js,md)
- If you use VSCode with ESLint plugin, add "eslint.validate": ["markdown"] in your VSCode preferences

Usage with eslint-plugin-prettier

Prettier is an amazing code formatter that supports many languages, including markdown. It is
common to use prettier as a rule in ESLint via amazing
eslint-plugin-prettier.

This plugin can play nicely together with eslint-plugin-prettier (meaning that first code will be formatted via
prettier, and then remark rules will be applied). Typical eslint configuration will look like this:

`bash
yarn add -D eslint eslint-plugin-prettier eslint-plugin-md
`

`js
// .eslintrc.js
module.exports = {
extends: ['plugin:prettier/recommended', 'plugin:md/recommended'],
overrides: [
{
files: ['*.md'],
parser: 'markdown-eslint-parser',
rules: {
'prettier/prettier': [
'error',
// Important to force prettier to use "markdown" parser - otherwise it wouldn't be able to parse *.md files.
// You also can configure other options supported by prettier here - "prose-wrap" is
// particularly useful for *.md files
{ parser: 'markdown' },
],
},
},
],
}
`

Modifying eslint setup for js code inside \*.md files

By default, code inside fenced code block marked as js language ( ``js ) will be linted against your default eslint
configuration for js files. However, that may be undesirable - usually you will want less strict rules for JS code in
\*.md files.

To modify setup, you can use "overrides" section in your eslintrc in this way:

``js
// .eslintrc.js
module.exports = {
extends: ['plugin:md/recommended'],
overrides: [
{
files: ['*.md'],
parser: 'markdown-eslint-parser',
},
{
files: ['.md.js'], // Will match js code inside .md files
rules: {
// Example - disable 2 core eslint rules 'no-unused-vars' and 'no-undef'
'no-unused-vars': 'off',
'no-undef': 'off',
},
},
],
}
`

Supported Rules

This plugin exposes only one eslint rule - md/remark. However, you can customize remark configuration however you
wish.

`js
// .eslintrc.js
module.exports = {
extends: ['plugin:md/recommended'],
rules: {
'md/remark': [
'error',
{
// This object corresponds to object you would export in .remarkrc file
plugins: ['preset-lint-markdown-style-guide', 'frontmatter', ['lint-maximum-line-length', false]],
},
],
},
overrides: [
{
files: ['*.md'],
parser: 'markdown-eslint-parser',
},
],
}
`

"Plugin" in remark can mean many things, but for our purposes it can be either remark rule or remark preset. See list of
available rules here, and list of available presets
(=set of rules) here.

Remark also supports External rules. You can use those
as well, just make sure to install corresponding package first. For example, if you want to use
alphabetize-lists external rule:

`bash
yarn add -D remark-lint-alphabetize-lists
`

`js
// .eslintrc.js
module.exports = {
extends: ['plugin:md/recommended'],
rules: {
'md/remark': [
'error',
{
// This object corresponds to object you would export in .remarkrc file
plugins: ['preset-lint-markdown-style-guide', 'frontmatter', 'remark-lint-alphabetize-lists'],
},
],
},
overrides: [
{
files: ['*.md'],
parser: 'markdown-eslint-parser',
},
],
}
``