Интеграция с git hooks

Для интеграции Remark и Rehype с Git Hooks обычно используются хуки pre-commit или pre-push. Это позволяет автоматически проверять и форматировать Markdown и HTML перед фиксацией изменений в репозиторий, обеспечивая единый стиль документации и предотвращая попадание некорректного кода в основную ветку.

npm install husky lint-staged --save-dev
  • Husky управляет Git Hooks и позволяет запускать скрипты на этапах commit или push.
  • Lint-staged позволяет запускать проверки только на тех файлах, которые изменяются, что ускоряет процесс.

Создание хуков:

npx husky install
npx husky add .husky/pre-commit "npx lint-staged"

В package.json добавляется секция lint-staged:

"lint-staged": {
  "*.md": [
    "npx remark . --output",
    "git add"
  ]
}

Это гарантирует, что перед коммитом каждый Markdown-файл будет обработан Remark, а исправленные файлы автоматически добавлены в индекс Git.

Конфигурация Remark для автоматической обработки Markdown

Remark позволяет создавать кастомные плагины или использовать готовые для проверки стиля, линтинга и форматирования документации.

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

module.exports = {
  plugins: [
    require('remark-preset-lint-recommended'),
    require('remark-lint-list-item-indent'),
    require('remark-lint-no-duplicate-headings'),
    require('remark-stringify')
  ],
  settings: {
    bullet: '-',
    emphasis: '*'
  }
};
  • remark-preset-lint-recommended — базовый набор правил для корректного оформления Markdown.
  • remark-lint-list-item-indent — проверяет отступы списков.
  • remark-lint-no-duplicate-headings — предотвращает дублирование заголовков.
  • remark-stringify — преобразует AST обратно в Markdown с единым форматированием.

Запуск через Git Hook гарантирует автоматическое применение этих правил к каждому изменяемому файлу.

Интеграция Rehype для HTML и статических сайтов

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

Пример использования Rehype с Remark через unified:

const fs = require('fs');
const { unified } = require('unified');
const remarkParse = require('remark-parse');
const remarkRehype = require('remark-rehype');
const rehypeStringify = require('rehype-stringify');
const rehypeLint = require('rehype-lint');

unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeLint)
  .use(rehypeStringify)
  .process(fs.readFileSync('README.md'))
  .then(file => {
    fs.writeFileSync('README.html', String(file));
  });
  • remarkParse преобразует Markdown в AST.
  • remarkRehype конвертирует Markdown AST в HTML AST.
  • rehypeLint проверяет HTML на ошибки и соблюдение правил.
  • rehypeStringify генерирует готовый HTML-файл.

Для автоматизации через Git Hook этот процесс можно обернуть в скрипт, который запускается pre-commit и обновляет HTML-версию документации при каждом изменении Markdown.

Настройка сложных цепочек хуков

Для проектов с большим количеством файлов можно комбинировать несколько этапов обработки:

  1. Lint Markdown: npx remark . --output
  2. Lint HTML: npx rehype-lint ./public/**/*.html
  3. Форматирование кода: prettier --write ./docs/**/*.md

В package.json это может выглядеть так:

"lint-staged": {
  "*.md": [
    "npx remark . --output",
    "prettier --write",
    "git add"
  ],
  "*.html": [
    "npx rehype-lint",
    "prettier --write",
    "git add"
  ]
}

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

Использование кастомных плагинов в хуках

Remark и Rehype поддерживают написание собственных плагинов. Например, для проверки ссылок в Markdown:

module.exports = function remarkCheckLinks() {
  return (tree, file) => {
    const visit = require('unist-util-visit');
    visit(tree, 'link', node => {
      if (!node.url.startsWith('https://')) {
        file.message(`Ссылка должна использовать HTTPS: ${node.url}`);
      }
    });
  };
};

Подключение плагина в .remarkrc.js:

module.exports = {
  plugins: [
    require('./plugins/remarkCheckLinks')
  ]
};

Такой плагин будет автоматически запускаться при каждом коммите и выводить предупреждения или ошибки.

Автоматическое исправление ошибок

Remark поддерживает автоматическую коррекцию стиля через флаг --output или --fix. Использование этого флага в Git Hook позволяет не только выявлять проблемы, но и исправлять их без дополнительного вмешательства:

npx remark . --output

С Rehype автоматическая коррекция возможна через плагины для форматирования и минификации. Комбинированное использование Remark + Rehype в Git Hooks позволяет поддерживать Markdown и HTML документацию в строгом соответствии с заданными стандартами, предотвращая накопление ошибок и упрощая поддержку больших проектов.

Оглавление