Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/leo-buneev/eslint-plugin-md

Allows you to lint markdown code in your *.md files.
https://github.com/leo-buneev/eslint-plugin-md

eslint eslint-plugin eslintplugin markdown md remark remark-lint

Last synced: 2 months ago
JSON representation

Allows you to lint markdown code in your *.md files.

Awesome Lists containing this project

README 

        
# eslint-plugin-md



An ESLint plugin to lint and fix markdown files. It uses amazing [remark-lint](https://github.com/remarkjs/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](http://eslint.org):



```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](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-preset-lint-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](https://prettier.io/) 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](https://github.com/prettier/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](https://github.com/remarkjs/remark-lint/blob/master/doc/rules.md), and list of available presets

(=set of rules) [here](https://github.com/remarkjs/remark-lint#list-of-presets).



Remark also supports [External rules](https://github.com/remarkjs/remark-lint#list-of-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](https://github.com/vhf/remark-lint-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',

    },

  ],

}

```