@tailwindcss/typography

Официальный плагин Tailwind CSS Typography предоставляет набор prose классов, которые вы можете использовать для добавления красивых типографических настроек к любому простому HTML, которым вы не управляете, например, HTML, сгенерированному из Markdown или полученному из CMS.

<article class="prose lg:prose-xl">
  {{ markdown }}
</article>

Чтобы увидеть, как это работает, ознакомьтесь с нашей живой демонстрацией на Tailwind Play.

Установка

Установите плагин из npm:

npm install -D @tailwindcss/typography

Затем добавьте плагин в свой tailwind.config.js файл:

module.exports = {
  theme: {
    // ...
  },
  plugins: [
    require('@tailwindcss/typography'),
    // ...
  ],
}

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

Теперь вы можете использовать prose классы для добавления осмысленных стилей типографики к любому простому HTML:

<article class="prose lg:prose-xl">
  <h1>Garlic bread with cheese: What the science tells us</h1>
  <p>
    For years parents have espoused the health benefits of eating garlic bread with cheese to their
    children, with the food earning such an iconic status in our culture that kids will often dress
    up as warm, cheesy loaf for Halloween.
  </p>
  <p>
    But a recent study shows that the celebrated appetizer may be linked to a series of rabies cases
    springing up around the country.
  </p>
  <!-- ... -->
</article>

Выбор шкалы серого

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

<article class="prose prose-slate">
  {{ markdown }}
</article>

Вот классы, сгенерированные с использованием полностью стандартной сборки Tailwind CSS v2.0:

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

<article class="prose prose-stone">
  {{ markdown }}
</article>

Чтобы узнать о создании собственных цветовых тем, прочитайте документацию по добавлению пользовательских цветовых тем.

Применение шкалы типов

Модификаторы размера позволяют настраивать общий размер вашей типографики для различных контекстов.

<article class="prose prose-xl">
  {{ markdown }}
</article>

Пять различных размеров типографики включены по умолчанию:

Их можно использовать в сочетании с модификаторами точек разрыва Tailwind для изменения общего размера шрифта части контента при разных размерах экрана:

<article class="prose md:prose-lg lg:prose-xl">
  {{ markdown }}
</article>

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

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

<article class="prose prose-lg">
  {{ markdown }}
</article>

Чтобы узнать о настройке включенных шкал типов, прочитайте документацию по настройке CSS.

Адаптация к тёмной теме

Каждая стандартная цветовая тема включает в себя разработанную вручную тёмную версию, которую вы можете активировать, добавив prose-invert класс:

<article class="prose dark:prose-invert">
  {{ markdown }}
</article>

Чтобы узнать о создании собственных цветовых тем, прочитайте документацию по добавлению пользовательских цветовых тем.

Модификаторы элементов

Используйте модификаторы элементов для настройки стиля отдельных элементов в вашем контенте непосредственно в вашем HTML:

<article class="prose prose-img:rounded-xl prose-headings:underline prose-a:text-blue-600">
  {{ markdown }}
</article>

Это упрощает такие задачи, как стилизация ссылок в соответствии с вашим брендом, добавление скругления к изображениям и многое другое.

Вот полный список доступных модификаторов элементов:

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

<article class="prose prose-a:text-blue-600 hover:prose-a:text-blue-500">
  {{ markdown }}
</article>

Прочитайте документацию Tailwind CSS по порядку применения составных модификаторов для получения дополнительной информации.

Переопределение максимальной ширины

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

В таких случаях вам нужно просто добавить max-w-none к вашему контенту, чтобы переопределить встроенную максимальную ширину:

<div class="grid grid-cols-4">
  <div class="col-span-1">
    <!-- ... -->
  </div>
  <div class="col-span-3">
    <article class="prose max-w-none">
      {{ markdown }}
    </article>
  </div>
</div>

Расширенные темы

Отмена стилей типографики

Если у вас есть блок разметки, вставленный в некоторый контент, который не должен наследоваться prose стили, используйте not-prose класс для изоляции:

<article class="prose">
  <h1>My Heading</h1>
  <p>...</p>

  <div class="not-prose">
    <!-- Some example or demo that needs to be prose-free -->
  </div>

  <p>...</p>
  <!-- ... -->
</article>

Обратите внимание, что в настоящее время вы не можете вкладывать новые prose экземпляры в блок not-prose.

Добавление пользовательских цветовых тем

Вы можете создать свою собственную цветовую тему, добавив новый ключ в раздел typography вашего tailwind.config.js файла и предоставив свои цвета под ключом css:

module.exports = {
  theme: {
    extend: {
      typography: ({ theme }) => ({
        pink: {
          css: {
            '--tw-prose-body': theme('colors.pink[800]'),
            '--tw-prose-headings': theme('colors.pink[900]'),
            '--tw-prose-lead': theme('colors.pink[700]'),
            '--tw-prose-links': theme('colors.pink[900]'),
            '--tw-prose-bold': theme('colors.pink[900]'),
            '--tw-prose-counters': theme('colors.pink[600]'),
            '--tw-prose-bullets': theme('colors.pink[400]'),
            '--tw-prose-hr': theme('colors.pink[300]'),
            '--tw-prose-quotes': theme('colors.pink[900]'),
            '--tw-prose-quote-borders': theme('colors.pink[300]'),
            '--tw-prose-captions': theme('colors.pink[700]'),
            '--tw-prose-code': theme('colors.pink[900]'),
            '--tw-prose-pre-code': theme('colors.pink[100]'),
            '--tw-prose-pre-bg': theme('colors.pink[900]'),
            '--tw-prose-th-borders': theme('colors.pink[300]'),
            '--tw-prose-td-borders': theme('colors.pink[200]'),
            '--tw-prose-invert-body': theme('colors.pink[200]'),
            '--tw-prose-invert-headings': theme('colors.white'),
            '--tw-prose-invert-lead': theme('colors.pink[300]'),
            '--tw-prose-invert-links': theme('colors.white'),
            '--tw-prose-invert-bold': theme('colors.white'),
            '--tw-prose-invert-counters': theme('colors.pink[400]'),
            '--tw-prose-invert-bullets': theme('colors.pink[600]'),
            '--tw-prose-invert-hr': theme('colors.pink[700]'),
            '--tw-prose-invert-quotes': theme('colors.pink[100]'),
            '--tw-prose-invert-quote-borders': theme('colors.pink[700]'),
            '--tw-prose-invert-captions': theme('colors.pink[400]'),
            '--tw-prose-invert-code': theme('colors.white'),
            '--tw-prose-invert-pre-code': theme('colors.pink[300]'),
            '--tw-prose-invert-pre-bg': 'rgb(0 0 0 / 50%)',
            '--tw-prose-invert-th-borders': theme('colors.pink[600]'),
            '--tw-prose-invert-td-borders': theme('colors.pink[700]'),
          },
        },
      }),
    },
  },
  plugins: [
    require('@tailwindcss/typography'),
    // ...
  ],
}

Посмотрите наши внутренние определения стилей для получения дополнительных примеров.

Изменение имени класса по умолчанию

Если вам нужно использовать другое имя класса вместо prose по какой-либо причине, вы можете сделать это, используя параметр className при регистрации плагина:

module.exports = {
  theme: {
    // ...
  },
  plugins: [
    require('@tailwindcss/typography')({
      className: 'wysiwyg',
    }),
  ]
  ...
}

Теперь каждый экземпляр prose в стандартных именах классов будет заменён вашим пользовательским именем класса:

<article class="wysiwyg wysiwyg-slate lg:wysiwyg-xl">
  <h1>My Heading</h1>
  <p>...</p>

  <div class="not-wysiwyg">
    <!-- Some example or demo that needs to be prose-free -->
  </div>

  <p>...</p>
  <!-- ... -->
</article>

Настройка CSS

Если вы хотите настроить исходный CSS, сгенерированный этим плагином, добавьте свои переопределения под ключом typography в разделе theme вашего tailwind.config.js файла:

module.exports = {
  theme: {
    extend: {
      typography: {
        DEFAULT: {
          css: {
            color: '#333',
            a: {
              color: '#3182ce',
              '&:hover': {
                color: '#2c5282',
              },
            },
          },
        },
      },
    },
  },
  plugins: [
    require('@tailwindcss/typography'),
    // ...
  ],
}

Как и при всех настройках тем в Tailwind, вы также можете определить ключ typography как функцию, если вам нужен доступ к вспомогательной функции theme:

module.exports = {
  theme: {
    extend: {
      typography: (theme) => ({
        DEFAULT: {
          css: {
            color: theme('colors.gray.800'),

            // ...
          },
        },
      }),
    },
  },
  plugins: [
    require('@tailwindcss/typography'),
    // ...
  ],
}

Настройки должны применяться к конкретному модификатору, например, DEFAULT или xl, и должны добавляться под свойством css. Настройки создаются в том же синтаксисе CSS-в-JS, что используется для написания плагинов Tailwind.

См. стандартные стили этого плагина для более подробных примеров настройки каждого модификатора.