README.ru.md

@funboxteam/babel-plugin-typograf

Babel-плагин для автоматического типографирования текста.

Назначение

Текст — один из основных инструментов, используемых в интерфейсах для описания действия. Помимо этого, зачастую страницы могут полностью состоять из текста в разных его проявлениях: лэндинги, разделы «О сервисе» и «Вопросы на ответы» и подобные им. Фронтенд-разработчики должны не забывать о том, какие кавычки и чёрточки и когда использовать, когда ставить неразрывный пробел, а когда нет, и так далее.

Этот Babel-плагин нужен для автоматизации подобной рутины. Он улучшает типографику текста на этапе сборки проекта.

Установка

npm install --save-dev @funboxteam/babel-plugin-typograf

Настройка

Важно: В секции plugins этот плагин должен быть выше остальных, обрабатывающих шаблонные строки (например, plugin-transform-template-literals), чтобы конвертирование теговых шаблонов было выполнено раньше, чем начнётся работа этих плагинов над шаблонными строки.

После установки, необходимо добавить плагин в конфигурацию Babel:

{
  plugins: [
    // ...
    ['@funboxteam/babel-plugin-typograf', {
      // Замена символов происходит с учётом локали
      locale: ['ru', 'en-US'],

      // Конвертация символов в HTML-сущности (по умолчанию отключена)
      htmlEntity: {
        type: 'name',        // 'name' или 'digit'
        onlyInvisible: true, // Установите `true`, чтобы конвертировать только невидимые символы
      },

      // Здесь можно включить дополнительные правила
      enableRules: [
        'common/nbsp/afterNumber',
      ],
      
      // А здесь отключить те, что включены по умолчанию в Typograf
      disableRules: [
        'common/punctuation/quote',
      ],

      // Настройки для правил
      ruleSettings: [
        ['common/nbsp/beforeShortLastWord', 'lengthLastWord', 8],
      ],
    }],
  ]
}

Использование

Для обозначения строк, которые нужно обработать, используется специальный тег:

// Исходная строка
T`Отформатированная "строка".  `;

// Строка после обработки плагином
// Теговый шаблон с тегом `T` конвертируется в обычную шаблонную строку
`Отформатированная «строка».`;

Typograf

Для обработки текста плагин использует библиотеку Typograf. Он ищет теговые шаблоны, помеченные тегом T:

T`"строка"`

Дорабатывает типографику внутри этих шаблонов, а затем конвертирует из в обычные шаблонные строки, удаляя тег:

`«строка»`

Основные возможности Typograf

• Удаление лишних пробелов.
• Автоматическая расстановка неразрывных пробелов.
• Конвертация двойных кавычек в «ёлочки».
• Конвертация HTML-сущностей ( , «, » и т.д.) в Unicode-символы.

Правила Typograf

В Typograf есть список правил, которые включены по умолчанию.

Не рекомендуется включать

• ru/money/ruble
  Преобразует все руб. в ₽. Рекомендуется указывать знак ₽ точечно во избежание рисков комплексной автозамены там, где это может не потребоваться. Например, в динамических текстах, где необходимо указывать именно руб., и которые отследить заранее практически невозможно. Или в разметке, где требуется указать руб. в связи с тем, что знак ₽ корректно отображается не во всех используемых шрифтах.

• common/space/delBeforePunctuation
  Удаляет пробелы перед знаками препинания. Но есть нюанс. Например, фраза «Нам нужен .Net-разработчик.» превратится в «Нам нужен.Net-разработчик.». На данный момент это решается только отключением правила, но, возможно, в будущем можно будет добавлять исключения.

• common/space/afterPunctuation
  Добавляет пробелы после знаков пунктуации. Может добавить пробел в случаях, когда он не нужен. Например, фраза разделитель запятая «,» превратится в разделитель запятая «, », а из-за этого неправильно сработает правило common/punctuation/quote, и в результате получится разделитель запятая «, «.