eslint-plugin-markdown-preferences

A specialized ESLint plugin that helps enforce consistent writing style and formatting conventions in Markdown files. Perfect for documentation projects, blog posts, and any Markdown content where consistency matters.

📛 Features

• 📝 Comprehensive style enforcement Enforces consistent heading casing, table header casing, inline code/link usage, emoji notation, and more for unified document style.
• 🧩 Powerful formatting consistency Strongly standardizes Markdown formatting: whitespace, indentation, spacing, line breaks, list markers, code fences, links, references, thematic breaks, tables, and decorative elements—ensuring documents are clean and uniform.
• 🚀 Extended Markdown syntax support Supports custom containers, mathematical expressions, and other extended syntax for high compatibility with VitePress.
• 🔧 Auto-fix support Most rules support ESLint's --fix option for automatic correction.
• 🌐 Online Demo & Documentation Try it instantly in the Online Demo and see full documentation.

📖 Documentation

For detailed usage instructions, rule configurations, and examples, visit our comprehensive documentation site.

💿 Installation

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

📖 Usage

Configuration

New Config (eslint.config.js)

Use eslint.config.js file to configure rules. See also: https://eslint.org/docs/latest/use/configure/configuration-files-new.

Example eslint.config.js:

import { defineConfig } from "eslint/config";
// import markdown from "@eslint/markdown";
import markdownPreferences from "eslint-plugin-markdown-preferences";
export default defineConfig([
  // add more generic rule sets here, such as:
  // markdown.configs.recommended,
  markdownPreferences.configs.recommended,
  {
    files: ["**/*.md", "*.md"],
    rules: {
      // override/add rules settings here, such as:
      // 'markdown-preferences/prefer-linked-words': 'error'
    },
  },
]);

This plugin provides configs:

• *.configs.recommended ... Recommended config provided by the plugin.
• *.configs.standard ... Enforces opinionated stylistic conventions. You can extend this to enforce any stylistic conventions you like.

See the rule list to get the rules that this plugin provides.

Using Extended Syntax

This plugin experimentally supports some extended Markdown syntax.
To use these extended syntaxes, set the markdown-preferences/extended-syntax language option.

import { defineConfig } from "eslint/config";
import markdownPreferences from "eslint-plugin-markdown-preferences";
export default defineConfig([
  {
    extends: [markdownPreferences.configs.recommended],
    language: "markdown-preferences/extended-syntax",
  },
]);

The following syntaxes are supported:

• Custom Containers
  Example:

  ::: warning
  This is a warning box.
  :::

• Mathematical Expressions
  Example:

  $$
  E = mc^2
  $$

• VitePress-style Import Code Snippets syntax using triple left angle brackets
  Example:

  <<< @/filepath

Legacy Config (.eslintrc)

Is not supported.

✅ Rules

The --fix option on the command line automatically fixes problems reported by rules which have a wrench 🔧 below.
The rules with the following ⭐ are included in the recommended config.
The rules with the following 💄 are included in the standard config.

Preference Rules

• Rules to unify the expression and description style of documents.

| Rule ID | Description | Fixable | Config | | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------- | :-----: | :----: | | markdown-preferences/canonical-code-block-language | enforce canonical language names in code blocks | 🔧 | | | markdown-preferences/emoji-notation | enforce consistent emoji notation style in Markdown files. | 🔧 | | | markdown-preferences/heading-casing | enforce consistent casing in headings. | 🔧 | | | markdown-preferences/no-heading-trailing-punctuation | disallow trailing punctuation in headings. | | | | markdown-preferences/ordered-list-marker-start | enforce that ordered list markers start with 1 or 0 | 🔧 | 💄 | | markdown-preferences/prefer-inline-code-words | enforce the use of inline code for specific words. | 🔧 | | | markdown-preferences/prefer-linked-words | enforce the specified word to be a link. | 🔧 | | | markdown-preferences/table-header-casing | enforce consistent casing in table header cells. | 🔧 | |

Notation Rules

• Rules related to notation styles in Markdown.

| Rule ID | Description | Fixable | Config | | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- | :-----: | :----: | | markdown-preferences/bullet-list-marker-style | enforce consistent bullet list (unordered list) marker style | 🔧 | 💄 | | markdown-preferences/code-fence-style | enforce a consistent code fence style (backtick or tilde) in Markdown fenced code blocks. | 🔧 | 💄 | | markdown-preferences/definitions-last | require link definitions and footnote definitions to be placed at the end of the document | 🔧 | | | markdown-preferences/emphasis-delimiters-style | enforce a consistent delimiter style for emphasis and strong emphasis | 🔧 | 💄 | | markdown-preferences/hard-linebreak-style | enforce consistent hard linebreak style. | 🔧 | ⭐💄 | | markdown-preferences/level1-heading-style | enforce consistent style for level 1 headings | 🔧 | 💄 | | markdown-preferences/level2-heading-style | enforce consistent style for level 2 headings | 🔧 | 💄 | | markdown-preferences/link-destination-style | enforce a consistent style for link destinations | 🔧 | 💄 | | markdown-preferences/link-title-style | enforce a consistent style for link titles | 🔧 | 💄 | | markdown-preferences/no-implicit-block-closing | disallow implicit block closing for fenced code blocks, math blocks, and custom containers | 🔧 | ⭐💄 | | markdown-preferences/no-text-backslash-linebreak | disallow text backslash at the end of a line. | | ⭐💄 | | markdown-preferences/ordered-list-marker-style | enforce consistent ordered list marker style | 🔧 | 💄 | | markdown-preferences/prefer-autolinks | enforce the use of autolinks for URLs | 🔧 | ⭐💄 | | markdown-preferences/prefer-fenced-code-blocks | enforce the use of fenced code blocks over indented code blocks | 🔧 | ⭐💄 | | markdown-preferences/prefer-link-reference-definitions | enforce using link reference definitions instead of inline links | 🔧 | | | markdown-preferences/strikethrough-delimiters-style | enforce a consistent delimiter style for strikethrough | 🔧 | 💄 | | markdown-preferences/thematic-break-character-style | enforce consistent character style for thematic breaks (horizontal rules) in Markdown. | 🔧 | 💄 |

Whitespace Rules

• Rules related to whitespace styles in Markdown.

| Rule ID | Description | Fixable | Config | | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------- | :-----: | :----: | | markdown-preferences/blockquote-marker-alignment | enforce consistent alignment of blockquote markers | 🔧 | ⭐💄 | | markdown-preferences/code-fence-spacing | require or disallow spacing between opening code fence and language identifier | 🔧 | 💄 | | markdown-preferences/custom-container-marker-spacing | require or disallow spacing between opening custom container marker and info | 🔧 | 💄 | | markdown-preferences/indent | enforce consistent indentation in Markdown files | 🔧 | 💄 | | markdown-preferences/link-bracket-newline | enforce linebreaks after opening and before closing link brackets | 🔧 | 💄 | | markdown-preferences/link-bracket-spacing | enforce consistent spacing inside link brackets | 🔧 | 💄 | | markdown-preferences/link-paren-newline | enforce linebreaks after opening and before closing link parentheses | 🔧 | 💄 | | markdown-preferences/link-paren-spacing | enforce consistent spacing inside link parentheses | 🔧 | 💄 | | markdown-preferences/list-marker-alignment | enforce consistent alignment of list markers | 🔧 | ⭐💄 | | markdown-preferences/no-multi-spaces | disallow multiple spaces | 🔧 | 💄 | | markdown-preferences/no-multiple-empty-lines | disallow multiple empty lines in Markdown files. | 🔧 | 💄 | | markdown-preferences/no-tabs | disallow tab characters in Markdown files. | 🔧 | 💄 | | markdown-preferences/no-trailing-spaces | disallow trailing whitespace at the end of lines in Markdown files. | 🔧 | 💄 | | markdown-preferences/padded-custom-containers | disallow or require padding inside custom containers | 🔧 | 💄 | | markdown-preferences/padding-line-between-blocks | require or disallow padding lines between blocks | 🔧 | 💄 | | markdown-preferences/table-pipe-spacing | enforce consistent spacing around table pipes | 🔧 | 💄 |

Decorative Rules

• Rules related to visual or stylistic decorations in Markdown.

| Rule ID | Description | Fixable | Config | | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------- | :-----: | :----: | | markdown-preferences/atx-heading-closing-sequence-length | enforce consistent length for the closing sequence (trailing #s) in ATX headings. | 🔧 | 💄 | | markdown-preferences/atx-heading-closing-sequence | enforce consistent use of closing sequence in ATX headings. | 🔧 | 💄 | | markdown-preferences/code-fence-length | enforce consistent code fence length in fenced code blocks. | 🔧 | 💄 | | markdown-preferences/max-len | enforce maximum length for various Markdown entities | | | | markdown-preferences/no-laziness-blockquotes | disallow laziness in blockquotes | | ⭐💄 | | markdown-preferences/ordered-list-marker-sequence | enforce consistent ordered list marker numbering (sequential or flat) | 🔧 | 💄 | | markdown-preferences/setext-heading-underline-length | enforce setext heading underline length | 🔧 | 💄 | | markdown-preferences/sort-definitions | enforce a specific order for link definitions and footnote definitions | 🔧 | 💄 | | markdown-preferences/table-leading-trailing-pipes | enforce consistent use of leading and trailing pipes in tables. | 🔧 | 💄 | | markdown-preferences/table-pipe-alignment | enforce consistent alignment of table pipes | 🔧 | 💄 | | markdown-preferences/thematic-break-length | enforce consistent length for thematic breaks (horizontal rules) in Markdown. | 🔧 | 💄 | | markdown-preferences/thematic-break-sequence-pattern | enforce consistent repeating patterns for thematic breaks (horizontal rules) in Markdown. | 🔧 | 💄 |

👫 Related Packages

• eslint-plugin-markdown-links ... ESLint plugin with powerful checking rules related to Markdown links.

🍻 Contributing

Welcome contributing!

Please use GitHub's Issues/PRs.

Development Tools

• npm test runs tests and measures coverage.
• npm run update runs in order to update readme and recommended configuration.

🔒 License

See the LICENSE file for license rights and limitations (MIT).