eslint-plugin-markdown-preferences

0.41.1 verified Sat Apr 25 auth: no javascript

An ESLint plugin (v0.41.1, active development) that enforces consistent formatting and style in Markdown files. It provides over 30 rules covering heading casing, list markers, inline code, link references, table formatting, and more. Supports extended Markdown syntax (custom containers, math) and integrates with @eslint/markdown v7/v8. Auto-fix support for most rules. Alternative to remark-lint with ESLint-native integration, focused on opinionated style enforcement.

Common errors

error Error: Cannot find module 'eslint-plugin-markdown-preferences' ↓

cause Missing npm installation or incorrect import path.

fix

Run 'npm install --save-dev eslint-plugin-markdown-preferences' and ensure package.json includes it.

error TypeError: markdownPreferences is not a function ↓

cause Using CommonJS require() instead of ESM import.

fix

Use 'import markdownPreferences from "eslint-plugin-markdown-preferences"' in eslint.config.js.

error Error: 'markdown-preferences/unknown-rule' was not found ↓

cause Rule name misspelled or does not exist.

fix

Check the rule list at https://ota-meshi.github.io/eslint-plugin-markdown-preferences/rules/ for valid rule names.

error Parsing error: The keyword 'import' is reserved ↓

cause Using ESM import in a CommonJS file without correct configuration.

fix

Add 'type': 'module' to package.json or rename file to .mjs extension.

Warnings

breaking Requires Node.js ^20.19.0 || ^22.12.0 || >=24.0.0. Older Node versions are unsupported. ↓

fix Update Node.js to ^20.19.0, ^22.12.0, or >=24.0.0.

breaking ESLint >=9.0.0 required for flat config; legacy .eslintrc configs are not supported. ↓

fix Migrate to eslint.config.js flat config using defineConfig.

deprecated Support for @eslint/markdown v7 may be dropped in future versions; v8 is recommended. ↓

fix Update @eslint/markdown to ^8.0.0.

gotcha Plugin uses ESM exclusively; CommonJS require() will fail. Must use import syntax and 'type': 'module' in package.json or .mjs extension. ↓

fix Use import statements and ensure your project is configured for ESM.

gotcha The markdown-preferences/no-tabs rule conflicts with editor settings; ensure your editor does not insert tabs in Markdown files. ↓

fix Configure your editor to use spaces in Markdown files.

deprecated Some rules like 'markdown-preferences/prefer-linked-words' may be renamed in future versions; check changelog before upgrading. ↓

fix Review release notes for rule deprecations before upgrading.

Install

npm install eslint-plugin-markdown-preferences

yarn add eslint-plugin-markdown-preferences

pnpm add eslint-plugin-markdown-preferences

Imports

markdownPreferences

wrong

const markdownPreferences = require('eslint-plugin-markdown-preferences')

correct

import markdownPreferences from 'eslint-plugin-markdown-preferences'

ESM-only; requires Node.js >=20.19.0 or >=22.12.0 or >=24.0.0. Use default import in flat config.

configs.recommended
wrong
```
require('eslint-plugin-markdown-preferences').configs.recommended
```
correct
```
markdownPreferences.configs.recommended
```
Access via the default import object. The recommended config enables a curated set of rules.
configs.standard
```
markdownPreferences.configs.standard
```
Stricter opinionated config for style enforcement. Override specific rules as needed.

Quickstart

Demonstrates flat config setup for ESLint v9+ with recommended and custom rules.

// eslint.config.js
import { defineConfig } from 'eslint/config';
import markdown from '@eslint/markdown';
import markdownPreferences from 'eslint-plugin-markdown-preferences';

export default defineConfig([
  // Enable ESLint's built-in Markdown processor
  markdown.configs.recommended,
  // Enable the plugin's recommended config
  markdownPreferences.configs.recommended,
  {
    files: ['**/*.md', '*.md'],
    rules: {
      // Enforce sentence case headings
      'markdown-preferences/heading-casing': ['error', 'sentence-case'],
      // Disallow trailing punctuation in headings
      'markdown-preferences/no-heading-trailing-punctuation': 'error',
      // Require consistent ordered list markers
      'markdown-preferences/ordered-list-marker-sequence': ['error', { increment: 1 }],
      // Enforce max line length
      'markdown-preferences/max-len': ['error', { code: 80 }],
      // Prefer reference links over inline URLs
      'markdown-preferences/prefer-linked-words': 'warn',
    },
  },
]);