ESLint Markdown Cannoli Plugins

A collection of ESLint plugins for linting Markdown files with custom rules.

Installation

npm install --save-dev eslint-md-cannoli-plugins @eslint/markdown eslint

Usage

Add the plugins to your ESLint configuration (eslint.config.js or eslint.config.ts):

import markdown from "@eslint/markdown";

import {
  enforceLinkConvention,
  inlineMathAloneOnLine,
  noH1Headers,
  requireBlankLineAfterHtml,
  requireDisplayMathFormatting,
  requireFrontmatter,
  validateLatexDelimiters,
} from "eslint-md-cannoli-plugins";

export default [
  {
    files: ["**/*.md"],
    plugins: {
      markdown,
      cannoli: {
        rules: {
          "require-frontmatter": requireFrontmatter,
          "no-h1-headers": noH1Headers,
          "require-blank-line-after-html": requireBlankLineAfterHtml,
          "require-display-math-formatting": requireDisplayMathFormatting,
          "inline-math-alone-on-line": inlineMathAloneOnLine,
          "validate-latex-delimiters": validateLatexDelimiters,
          "enforce-link-convention": enforceLinkConvention,
        },
      },
    },
    language: "markdown/gfm",
    languageOptions: {
      parser: "@eslint/markdown",
      frontmatter: "yaml",
    },
    extends: ["markdown/recommended"],
    rules: {
      "cannoli/require-frontmatter": "error",
      "cannoli/no-h1-headers": "error",
      "cannoli/require-blank-line-after-html": "error",
      "cannoli/require-display-math-formatting": "error",
      "cannoli/inline-math-alone-on-line": "warn",
      "cannoli/validate-latex-delimiters": "error",
      "cannoli/enforce-link-convention": "warn",
    },
  },
];

Available Rules

• require-frontmatter - Ensure markdown files have frontmatter

• no-h1-headers - Disallow H1 headers (use frontmatter title instead)

• require-blank-line-after-html - Require blank lines after HTML blocks

• require-display-math-formatting - Enforce proper display math formatting

• inline-math-alone-on-line - Ensure inline math equations are on their own line

• validate-latex-delimiters - Validate LaTeX delimiter usage

• enforce-link-convention - Enforce link naming conventions

• enforce-frontmatter-schema - Enforce frontmatter field presence and value patterns

  Each key in the options object is a required field path (__ denotes nesting), and each value is a wildcard string, a RegExp, or an array of either. A field passes if it is present and matches at least one pattern.

  "cannoli/enforce-frontmatter-schema": ["error", {
    title: "Lecture *",              // wildcard string — * matches anything
    "course__code": /^[A-Z]{4}-\d{3}$/, // regex
    tags: ["math*", "csci*"],        // array — passes if any pattern matches
  }]

License

ISC