Проверка орфографии (cspell)

В проекте для проверки орфографии в Markdown используется cspell. Проверяются русская и английская документация: словарь @cspell/dict-ru_ru и английские словари (американское и британское написание). Код и фрагменты в parts/ не проверяются.

Запуск проверки

Из корня репозитория:

• pnpm run spellcheck:changed — проверяет Markdown-файлы, изменённые с момента ответвления от origin/master, и сообщает только об ошибках в изменённых строках: старые опечатки в остальных строках файла не мешают (сначала выполните git fetch; другую базу задаёт CHECK_BASE=origin/<ветка>). Ту же проверку CI запускает в PR, меняющих docs/, относительно базовой ветки PR, поэтому перед отправкой правок удобнее всего она.
• pnpm run spellcheck — проверяет всю документацию и выводит отчёт по всем найденным ошибкам (файл, строка, слово).
• pnpm run spellcheck:fix — та же проверка с выводом вариантов исправления (подсказок) для каждого неизвестного слова; исправления в файлы вносятся вручную или слово добавляется в cspell.json.

После установки зависимостей (pnpm install) команды доступны без дополнительной настройки.

Проверка одного файла или папки

Удобно при правке конкретной страницы:

pnpm run spellcheck docs/components/ajaxform.md
pnpm run spellcheck docs/guide

Если по пути нет файлов для проверки (опечатка в пути или только фрагменты parts/), скрипт сообщит об этом и завершится с ошибкой. Вместе с --changed пути не указываются. Опции cspell передаются в виде --флаг или --флаг=значение.

Конфигурация

Файл конфигурации — cspell.json в корне проекта.

• language — "en,en-GB,ru": проверка по русскому и английским словарям (американское и британское написание).
• words — массив дополнительных «правильных» слов: технические термины (MODX, miniShop2, Fenom), имена компонентов и сниппетов, домены (modstore, modx.pro) и т.п. Эти слова не считаются ошибками.
• ignoreRegExpList — не проверяются код (блоки кода и всё, что в обратных кавычках) и адреса: цели Markdown-ссылок и link: во frontmatter. Имена сниппетов, параметров и переменных оформляйте кодом — тогда их не нужно добавлять в словарь.
• ignorePaths — пути, которые cspell не проверяет: **/parts/**, lock-файлы, node_modules, plop-templates.

Так мы избегаем ложных срабатываний на названиях пакетов, тегов и путей.

Добавление слов

Названия компонентов и авторов добавлять не нужно: scripts/spellcheck.mjs собирает их сам — имена файлов docs/components/*.md и папок docs/components/*/ со словами из их title, а также ключи, слова из имён и ники (последний сегмент ссылки на профиль) из docs/authors.json.

Если cspell помечает корректное слово как ошибку (например, термин или жаргон), добавьте его в массив words в cspell.json. Слова задаются в нижнем регистре; cspell сопоставляет без учёта регистра.

Пример фрагмента cspell.json:

{
  "words": ["кукисов", "брейкпоинтом"]
}

• words — словарь проекта: имена пакетов, хуки, редкие аббревиатуры.
• ignorePaths — целые пути не проверять (фрагменты parts/, шаблоны plop и т.д.). Не злоупотребляйте: лучше добавить термин в words, чем отключать проверку целых разделов без причины.

Фрагменты в parts/ не проверяются: они вставляются в другие страницы и проверяются вместе с ними.

Проверка в CI

Workflow Spellcheck запускается в каждом PR, который меняет docs/, и проверяет изменённые строки (pnpm run spellcheck:changed). Если он упал, исправьте опечатку или добавьте слово в words.

Подробнее о настройке — в документации cspell.