@sheplu/eslint-config-markdown

@sheplu/eslint-config-markdown

Opinionated, exhaustive configuration for @eslint/markdown — ready to drop into an ESLint 10+ flat config for Markdown files.

Every non-deprecated upstream rule is configured explicitly, so nothing is left to defaults and nothing silently changes when @eslint/markdown ships a new rule — a scheduled CI job diffs the package against the upstream rule index every week and opens an issue on drift.

Installation

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

Requires eslint >= 10 (flat config), @eslint/markdown >= 8, and Node >= 24.

Usage

The drop-in defaultMarkdownConfig wires the plugin, the language (GFM, YAML frontmatter), and the rules in one object:

import { defineConfig } from 'eslint/config';
import { defaultMarkdownConfig } from '@sheplu/eslint-config-markdown';

export default defineConfig([
    defaultMarkdownConfig,
]);

Or use markdownRules on its own if you want to supply your own files glob, plugins, or language:

import { defineConfig } from 'eslint/config';
import markdown from '@eslint/markdown';
import { markdownRules } from '@sheplu/eslint-config-markdown';

export default defineConfig([
    {
        files: [ '**/*.md' ],
        plugins: { markdown },
        language: 'markdown/gfm',
        extends: [ markdownRules ],
    },
]);

Exports

Export	Type	Purpose
markdownRules	Linter.Config[]	Rule bundle only — bring your own files/plugins/language.
defaultMarkdownConfig	Linter.Config	Ready-to-use flat-config object for **/*.md (GFM, YAML frontmatter) — supply the plugin.

Every rule is set to error with options spelled out explicitly. If you need a more permissive baseline, override rules individually in your own config.

Scripts

npm test                 # run the test suite (includes upstream drift check)
npm run test:coverage    # run tests with coverage
npm run lint             # lint the package itself
npm run lint:fix         # lint with autofix
npm run setup:hooks      # wire .githooks/ as the git hooks path (run once)

Upstream drift

test/review-rules.js fetches the eslint/markdown rule docs index via the GitHub contents API and diffs it against the configured rule set. This runs:

• as part of npm test,
• on a weekly schedule (.github/workflows/eslint-rules-drift.yaml), which opens a GitHub issue if new rules appear, are renamed, or are removed upstream.

Contributing

See AGENTS.md for the short version of how this repo is laid out and the CI quality gates. A few things worth knowing up front:

• Git hooks live in .githooks/. Run npm run setup:hooks once after cloning to point core.hooksPath there. The pre-commit hook runs lint and tests; the pre-push hook adds coverage and npm audit, and blocks direct pushes to main. (Hooks are opt-in because .npmrc sets ignore-scripts=true for supply-chain safety.)
• AI tooling assets (agent rules, prompts) are distributed via apkg rather than committed. apkg.json and apkg-lock.json are in the repo; the resolved files under .codex/, .claude/, .cursor/, etc. are gitignored and materialized by running apkg install. CI does this automatically in quality-gates.yaml. If you contribute using an AI agent and want those rule files locally, install apkg and run it against this repo.