Линтеры для MDX

MDX объединяет Markdown и JSX, позволяя писать компоненты React прямо в текстовых документах. Такой синтаксис открывает широкие возможности, но одновременно повышает риск ошибок: от некорректной разметки Markdown до неправильного использования JSX-компонентов. Линтеры для MDX помогают автоматически выявлять ошибки и поддерживать единый стиль кода.

Основы линтинга MDX

MDX-линтеры работают по принципу анализа абстрактного синтаксического дерева (AST). Документ MDX сначала парсится в AST, который содержит узлы Markdown и JSX. Линтер проверяет каждый узел на соответствие правилам:

  • корректность Markdown-разметки (heading-increment, no-trailing-spaces);
  • правильность JSX-структуры (react/jsx-uses-vars, react/jsx-no-undef);
  • согласованность между Markdown и JSX (mdx/no-unused-expressions, mdx/no-jsx-html-comments).

Проверки могут быть настроены через конфигурационные файлы, где включаются или отключаются отдельные правила, а также задаются кастомные правила для проекта.

Основные инструменты

1. eslint-plugin-mdx Этот плагин интегрируется с ESLint и позволяет проверять MDX-файлы так же, как обычные JavaScript или JSX-файлы. Основные возможности:

  • Поддержка JSX-валидаторов ESLint.
  • Настройка правил Markdown и MDX.
  • Возможность расширения правил с помощью собственного плагина ESLint.

Пример базовой конфигурации .eslintrc.js:

module.exports = {
  extends: [
    'eslint:recommended',
    'plugin:react/recommended',
    'plugin:mdx/recommended'
  ],
  overrides: [
    {
      files: ['*.mdx'],
      extends: ['plugin:mdx/recommended']
    }
  ],
  settings: {
    react: {
      version: 'detect'
    }
  }
};

2. remark-lint Используется для проверки чистого Markdown-кода внутри MDX. Позволяет выявлять проблемы вроде:

  • некорректной иерархии заголовков;
  • лишних пробелов в конце строки;
  • пустых ссылок или изображений.

Комбинируется с remark-mdx для полноценной поддержки MDX:

const remark = require('remark');
const remarkMdx = require('remark-mdx');
const remarkLint = require('remark-lint');

remark()
  .use(remarkMdx)
  .use(remarkLint)
  .processSync(mdxContent);

Настройка правил

Правила делятся на три группы:

  1. Стилизация Markdown Например, heading-increment проверяет, что заголовки увеличиваются последовательно (h1 → h2 → h3). no-trailing-spaces запрещает пробелы в конце строк.

  2. Проверка JSX Применяются стандартные правила ESLint для React: jsx-uses-react, jsx-uses-vars, jsx-no-undef. Эти правила помогают избежать ошибок при написании компонентов внутри MDX.

  3. MDX-специфические правила Сюда входят проверки, которые не относятся ни к Markdown, ни к JSX напрямую:

    • mdx/no-unused-expressions — выявляет JSX-выражения, которые не используются;
    • mdx/no-jsx-html-comments — запрещает HTML-комментарии внутри JSX;
    • mdx/no-missing-exports — проверяет, что все используемые компоненты импортированы или экспортированы.

Интеграция с CI/CD

MDX-линтеры легко интегрируются в пайплайны:

  • ESLint + Prettier проверяет MDX вместе с JavaScript/JSX;
  • remark-lint можно запускать отдельно для Markdown-проверок;
  • В CI/CD удобно запускать eslint --ext .js,.jsx,.mdx src/ и remark . одновременно, чтобы проверять весь проект.

Кастомные правила

MDX поддерживает написание собственных плагинов для линтинга:

  • Для ESLint создаются новые правила через createRule, где описывается функция проверки AST узлов;
  • Для Remark можно писать плагины, которые будут анализировать Markdown-узлы и выполнять проверки.

Пример кастомного правила для ESLint:

module.exports = {
  meta: {
    type: 'problem',
    docs: {
      description: 'Запрещает использование <div> без className'
    }
  },
  create(context) {
    return {
      JSXOpeningElement(node) {
        if (node.name.name === 'div' && !node.attributes.some(attr => attr.name.name === 'className')) {
          context.report({
            node,
            message: 'Все <div> должны иметь className'
          });
        }
      }
    };
  }
};

Советы по применению

  • Объединять линтеры: ESLint для JSX и JavaScript, remark-lint для Markdown.
  • Настроить автоматический фикс стиля с помощью Prettier.
  • Включить линтинг в pre-commit хуки через lint-staged для предотвращения коммитов с ошибками.
  • Разделять правила для MDX и обычных JS/TS файлов, чтобы избежать конфликтов.

Линтеры для MDX обеспечивают не только чистоту кода, но и предотвращают ошибки в работе компонентов и вёрстки, делая проект стабильным и поддерживаемым.

Оглавление