Соглашения по именованию

Общая структура пакетов

Библиотеки Remark и Rehype организованы по модульному принципу. Основной модуль выполняет базовую функциональность: парсинг и генерацию AST (Abstract Syntax Tree). Дополнительные возможности реализуются через плагины. Названия пакетов строго следуют соглашениям, обеспечивая предсказуемость и удобство поиска в экосистеме.

  • remark-* — пакеты, расширяющие функциональность Remark, например, remark-parse, remark-stringify.
  • rehype-* — пакеты для работы с Rehype, например, rehype-parse, rehype-stringify.
  • remark--plugin или rehype--plugin — встречается реже, иногда используется для указания на специфический плагин, но современная практика предпочитает просто remark-* или rehype-*.

Использование таких стандартов позволяет автоматически отличать плагины от ядра и минимизировать риск конфликтов имен.

Формат именования плагинов

Плагины для Remark и Rehype делятся на три категории по именам:

  1. Парсеры (-parse) — преобразуют текст в AST.

    • remark-parse — Markdown → MDAST.
    • rehype-parse — HTML → HAST.

  2. Генераторы (-stringify) — преобразуют AST обратно в текст.

    • remark-stringify — MDAST → Markdown.
    • rehype-stringify — HAST → HTML.

  3. Трансформеры (-plugin или без суффикса) — изменяют AST без изменения исходного формата.

    • remark-lint — проверка стиля Markdown.
    • rehype-slug — добавление идентификаторов к заголовкам HTML.

Ключевое соглашение: имя плагина должно отражать его функциональность. Любой разработчик, взглянув на пакет remark-footnotes, сразу понимает, что плагин работает с сносками в Markdown.

CamelCase и kebab-case

В экосистеме Remark/Rehype применяется kebab-case (с маленькими буквами, слова разделяются дефисом) для имен npm-пакетов. Примеры:

  • remark-autolink-headings
  • rehype-highlight

Внутри кода, при экспорте функций или классов, допускается CamelCase для читаемости:

import { remark } from 'remark';
import AutolinkHeadings from 'remark-autolink-headings';

const processor = remark().use(AutolinkHeadings);

Такое разделение облегчает различие между именем пакета в npm и именем переменной в коде.

Пространства имен и префиксы

  • Все плагины должны начинаться с remark- или rehype-. Это не только единообразие, но и предотвращение конфликтов с другими пакетами.

  • Для организации плагинов внутри крупного проекта можно использовать дополнительный префикс, отражающий авторство или домен. Например:

    • @myorg/remark-custom-toc
    • @myorg/rehype-custom-syntax

Использование scoped packages (@scope/package) помогает группировать плагины и выделять их среди сторонних.

Соглашения по версиям

Remark и Rehype придерживаются семантического версионирования (semver):

  • MAJOR — изменения API, несовместимые с предыдущими версиями.
  • MINOR — добавление новых возможностей без нарушения существующего API.
  • PATCH — исправление ошибок.

Имя пакета вместе с версией играет ключевую роль для интеграции плагинов и предотвращения конфликта зависимостей.

Рекомендации по именованию локальных плагинов

Для локальных плагинов, которые не публикуются в npm, также рекомендуется придерживаться той же структуры:

  • remark-myplugin — плагин для Remark.
  • rehype-myplugin — плагин для Rehype.

Это сохраняет единообразие, облегчает поиск и поддержку кода даже в пределах одного проекта.

Итоговые принципы

  1. Использовать kebab-case для npm-пакетов.
  2. Явно указывать принадлежность: remark- для Markdown, rehype- для HTML.
  3. Отражать функциональность в имени: parse, stringify, lint, slug.
  4. Scoped packages использовать для группировки или авторства: @scope/remark-*.
  5. Локальные плагины именовать по аналогии с публичными.
  6. CamelCase использовать для экспортируемых объектов и функций в коде.

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

Оглавление