@343dev/markdown-lint

Консольная утилита для проверки Markdown-файлов на соответствие указанным стандартам качества.

Основана на Prettier, Remark и Typograf.

Мотивация

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

В то же время мы решили проверять синтаксис Markdown-файлов, как мы проверяем JS, CSS и иные файлы проекта. Потому создали этот линтер.

Установка

Для глобальной установки и использования CLI-утилиты:

npm install -g @343dev/markdown-lint

Для установки в проект:

npm install --dev @343dev/markdown-lint

Работа с CLI

Для ручной проверки файлов или директорий можно обращаться к markdown-lint из командной строки:

# проверка файла на наличие ошибок
markdown-lint README.md

# проверка файлов внутри директории (без поиска в поддиректориях)
markdown-lint ./docs

# проверка файлов внутри директории (с поиском в поддиректориях)
markdown-lint -r ./docs

# проверка файла и автоматическое исправление ошибок
markdown-lint --fix README.md

Доступные флаги

• --fix — автоматическое исправление ошибок;
• --ext <value> — указание расширений файлов; допустимо последовательное указание нескольких расширений, например --ext apib --ext txt. По умолчанию md;
• -t, --typograph — типографирование текста;
• -r, --recursive — поиск файлов не только внутри указанной директории, но и во всех поддиректориях;
• -c, --config <file> — подключение внешнего файла с конфигурацией линтера;
• -v, --version — вывод текущей версии линтера;
• -h, --help — вывод справки.

Конфигурация линтера

Работа линтера основана на Markdown-процессоре remark.

Линтинг производится с помощью библиотеки remark-lint и набора правил remark-preset-lint-markdown-style-guide.

Для тонкой настройки линтера нужно создать файл конфигурации и с помощью флага --config указать путь до него:

markdown-lint --fix --config ~/.markdownlintrc.cjs README.md

Пример конфигурации:

module.exports = {
  // prettier обрабатывает тексты, когда `--fix` передан
  prettier: {
    // автоматически ограничиваем длину строки в 120 символов
    printWidth: '120'
  },

  remark: {
    // применяем настройки для remark-lint
    plugins: [
      // объявляем линтеру, что максимальная длина строки теперь равна 120 символам
      ['remark-lint-maximum-line-length', 120],

      // отключаем правило `no-inline-padding`
      ['remark-lint-no-inline-padding', false],

      // объявляем линтеру, что мы теперь используем `*` как маркер списка
      ['remark-lint-unordered-list-marker-style', '*']
    ],

    // remark-stringify обрабатывает тексты, когда `--fix` передан
    stringifySettings: {
      // автоматически заменяем все маркеры списка на `*`
      bullet: '*'
    }
  },

  typograf: {
    // API настроек — https://github.com/typograf/typograf/blob/dev/docs/api_rules.md
    // список правил — https://github.com/typograf/typograf/blob/dev/docs/RULES.ru.md
    locale: ['ru', 'en-US'],
    enableRules: [],
    disableRules: [
      // обязательное отключение следующих правил требуется для правильной работы типографа
      'common/space/delTrailingBlanks',
      'common/space/trimLeft',
      'common/space/trimRight'
    ],
    rulesSettings: []
  }
};

Пример работы

До обработки с флагом --fix

Linux kernel
============

There are several guides for kernel developers and users. These guides can be rendered in a number of formats, like HTML and PDF. Please read Documentation/admin-guide/README.rst first.

In order to build the documentation, use ``make htmldocs`` or ``make pdfdocs``.  The formatted documentation can also be read online at:

    https://www.kernel.org/doc/html/latest/

There are various text files in the Documentation/ subdirectory, several of them using the Restructured Text markup notation.

Please read the Documentation/process/changes.rst file, as it contains the requirements for building and running the kernel, and information about the problems which may result by upgrading your kernel.

__Useful links__

* [Linux kernel licensing rules](https://www.kernel.org/doc/html/latest/process/license-rules.html#kernel-licensing)
* [Reporting bugs](https://www.kernel.org/doc/html/latest/admin-guide/reporting-bugs.html)

После обработки

# Linux kernel

There are several guides for kernel developers and users. These guides can be
rendered in a number of formats, like HTML and PDF. Please read
Documentation/admin-guide/README.rst first.

In order to build the documentation, use `make htmldocs` or `make pdfdocs`. The
formatted documentation can also be read online at:

```
https://www.kernel.org/doc/html/latest/
```

There are various text files in the Documentation/ subdirectory, several of them
using the Restructured Text markup notation.

Please read the Documentation/process/changes.rst file, as it contains the
requirements for building and running the kernel, and information about the
problems which may result by upgrading your kernel.

**Useful links**

- [Linux kernel licensing rules](https://www.kernel.org/doc/html/latest/process/license-rules.html#kernel-licensing)
- [Reporting bugs](https://www.kernel.org/doc/html/latest/admin-guide/reporting-bugs.html)

Благодарности

Яркую картинку для репозитория нарисовал Игорь Гарибальди.