6.5.0 • Published 4 months ago

@eslint/markdown v6.5.0

Weekly downloads
-
License
MIT
Repository
github
Last release
4 months ago

ESLint Markdown Language Plugin

npm Version Downloads Build Status

Lint Markdown with ESLint, as well JS, JSX, TypeScript, and more inside Markdown.

Usage

Installing

Install the plugin alongside ESLint v9 or greater:

npm install --save-dev eslint @eslint/markdown

Configurations

Configuration NameDescription
recommendedLints all .md files with the recommended rules and assumes CommonMark format.
processorEnables extracting code blocks from all .md files so code blocks can be individually linted.

In your eslint.config.js file, import @eslint/markdown and include the recommended config to enable Markdown parsing and linting:

// eslint.config.js
import { defineConfig } from "eslint/config";
import markdown from "@eslint/markdown";

export default defineConfig([
    markdown.configs.recommended

    // your other configs here
]);

You can also modify the recommended config by using extends:

// eslint.config.js
import { defineConfig } from "eslint/config";
import markdown from "@eslint/markdown";

export default defineConfig([
    {
        plugins: {
            markdown
        },
        extends: ["markdown/recommended"],
        rules: {
            "markdown/no-html": "error"
        }
    }

    // your other configs here
]);

Rules

Rule NameDescriptionRecommended
fenced-code-languageRequire languages for fenced code blocksyes
heading-incrementEnforce heading levels increment by oneyes
no-duplicate-definitionsDisallow duplicate definitionsyes
no-duplicate-headingsDisallow duplicate headings in the same documentno
no-empty-definitionsDisallow empty definitionsyes
no-empty-imagesDisallow empty imagesyes
no-empty-linksDisallow empty linksyes
no-htmlDisallow HTML tagsno
no-invalid-label-refsDisallow invalid label referencesyes
no-missing-atx-heading-spaceDisallow headings without a space after the hash charactersyes
no-missing-label-refsDisallow missing label referencesyes
no-multiple-h1Disallow multiple H1 headings in the same documentyes
require-alt-textRequire alternative text for imagesyes
table-column-countDisallow data rows in a GitHub Flavored Markdown table from having more cells than the header rowyes

Note: This plugin does not provide formatting rules. We recommend using a source code formatter such as Prettier for that purpose.

In order to individually configure a rule in your eslint.config.js file, import @eslint/markdown and configure each rule with a prefix:

// eslint.config.js
import { defineConfig } from "eslint/config";
import markdown from "@eslint/markdown";

export default defineConfig([
    {
        files: ["**/*.md"],
        plugins: {
            markdown
        },
        language: "markdown/commonmark",
        rules: {
            "markdown/no-html": "error"
        }
    }
]);

You can individually disable rules in Markdown using HTML comments, such as:

<!-- eslint-disable-next-line markdown/no-html -- I want to allow HTML here -->
<custom-element>Hello world!</custom-element>

<!-- eslint-disable markdown/no-html -- here too -->
<another-element>Goodbye world!</another-element>
<!-- eslint-enable markdown/no-html -- safe to re-enable now -->

[Object] <!-- eslint-disable-line markdown/no-missing-label-refs -- not meant to be a link ref -->

Languages

Language NameDescription
commonmarkParse using CommonMark Markdown format
gfmParse using GitHub-Flavored Markdown format

In order to individually configure a language in your eslint.config.js file, import @eslint/markdown and configure a language:

// eslint.config.js
import { defineConfig } from "eslint/config";
import markdown from "@eslint/markdown";

export default defineConfig([
    {
        files: ["**/*.md"],
        plugins: {
            markdown
        },
        language: "markdown/gfm",
        rules: {
            "markdown/no-html": "error"
        }
    }
]);

Language Options

Enabling Front Matter in both commonmark and gfm

By default, Markdown parsers do not support front matter. To enable front matter in both commonmark and gfm, you can use the frontmatter option in languageOptions.

@eslint/markdown internally uses micromark-extension-frontmatter and mdast-util-frontmatter to parse front matter.

Option ValueDescription
falseDisables front matter parsing in Markdown files. (Default)
"yaml"Enables YAML front matter parsing in Markdown files.
"toml"Enables TOML front matter parsing in Markdown files.
// eslint.config.js
import { defineConfig } from "eslint/config";
import markdown from "@eslint/markdown";

export default defineConfig([
    {
        files: ["**/*.md"],
        plugins: {
            markdown
        },
        language: "markdown/gfm",
        languageOptions: {
            frontmatter: "yaml", // Or pass `"toml"` to enable TOML front matter parsing.
        },
        rules: {
            "markdown/no-html": "error"
        }
    }
]);

Processors

Processor NameDescription
markdownExtract fenced code blocks from the Markdown code so they can be linted separately.

Editor Integrations

VSCode

vscode-eslint has built-in support for the Markdown processor.

File Name Details

This processor will use file names from blocks if a filename meta is present.

For example, the following block will result in a parsed file name of src/index.js:

```js filename="src/index.js"
export const value = "Hello, world!";
```

This can be useful for user configurations that include linting overrides for specific file paths. In this example, you could then target the specific code block in your configuration using "file-name.md/*src/index.js".

Contributing

$ git clone https://github.com/eslint/markdown.git
$ cd markdown
$ npm install
$ npm test

This project follows the ESLint contribution guidelines.

Sponsors

The following companies, organizations, and individuals support ESLint's ongoing maintenance and development. Become a Sponsor to get your logo on our READMEs and website.

@rotki/eslint-configlintroll@wangyjhh/eslint-config@whoj/eslint-config@ver0/eslint-config@vinicunca/eslint-config@xiaohe01/eslint-config@youcan/lint@xwbx/eslint-config@zeronejs/eslint-config-vue3@zemd/eslint-flat-config@itcase/lint@isentinel/eslint-config@cluerise/tools@2030/eslint-config@2digits/eslint-config@hadronomy/eslint-config@adrianub/eslint-config@ajiu9/eslint-config@bruhabruh/eslint-config@kurone-kito/eslint-config-base@lemonbot.fun/eslint-config@lincy/eslint-config@liou666/eslint-config-flat@mutoe/eslint-config@neosjs/eslint-config@keksiqc/eslint-config@kolhe/eslint-config@kirklin/eslint-config@sarast/eslint-config@peggyjs/eslint-config@pengzhanbo/eslint-config@pagoda-tools/eslint-config@removify/eslint-config@stacksjs/eslint-config@storm-software/eslint@subframe7536/eslint-config@svrbc/eslint-config@sunshj/eslint-config@svifty7/eslint-config@sxzz/eslint-configefiand-sharedeslint-config-jlmeslint-config-uneslint-config-ash-nazgeslint-config-current-thing@snowball-tech/eslint-snowball-config@m1rn/eslint-config@jiangweiye/eslint-config@lvce-editor/eslint-config@jhqn/eslint-config@luxass/eslint-config@mastondzn/eslint@andabove/eslint-config@anatolychesnokov/eslint-config@ivanmaxlogiudice/eslint-config@itzcull/eslint-config@itsneufox/eslint-config@anolilab/eslint-config@antfu/eslint-config@imyangyong/eslint-config@inrupt/eslint-config-base@fledra/eslint-config@dkshs/eslint-config@flowr/eslint@flowr/eslint-config@freaktechnik/eslint-config-base@arianrhodsandlot/eslint-config@dixidan/eslint-config@dimrak/eslint-config@directus/eslint-config@ileostar/eslint-config@jobinjia/eslint-config@ntnyq/eslint-config@nirtamir2/eslint-config@nyxb/eslint-config@elora-cloud/eslint-config@eonova/eslint-config@hexadrop/eslint-config@estjs/eslint-config@ethang/eslint-config@exbotanical/eslint-config@hellolin/eslint-config@davidsneighbour/eslint-config@debbl/eslint-config@hyperupcall/scripts-nodejs@fabdeh/eslint-config@hunghg255/eslint-config@oliver139/eslint-config@open-xchange/linter-presets@ocavue/eslint-config@jsse/eslint-config@gcko/eslint-config@ggbondz/eslint-flat-config@ghettoddos/eslint-config@simonbiennier/eslint-config@rainbowatcher/eslint-config-md@radum/eslint-config
6.3.0

8 months ago

6.5.0

4 months ago

6.4.0

6 months ago

6.2.2

9 months ago

6.2.1

1 year ago

6.2.0

1 year ago

6.1.1

1 year ago

6.1.0

1 year ago

6.0.0

1 year ago