Добавление классов и атрибутов

Для работы с библиотекой Markdown-it необходимо подключить её через npm или yarn:

const MarkdownIt = require('markdown-it');
const md = new MarkdownIt();

После инициализации создается объект md, который отвечает за разбор и генерацию HTML из Markdown. Базовые опции включают управление HTML-тегами, ссылками, переносами строк и прочими стандартными функциями Markdown.

Использование плагинов для расширения функциональности

Markdown-it поддерживает плагины, которые позволяют добавлять нестандартные возможности, включая управление классами и атрибутами HTML-элементов. Для работы с атрибутами применяется плагин markdown-it-attrs.

Установка плагина:

npm install markdown-it-attrs

Подключение к Markdown-it:

const mdAttrs = require('markdown-it-attrs');
md.use(mdAttrs);

После подключения плагина можно добавлять классы и id прямо в Markdown:

# Заголовок {.title #main-title}

Параграф с классом {.text-center .highlight}

Результирующий HTML будет следующим:

<h1 id="main-title" class="title">Заголовок</h1>
<p class="text-center highlight">Параграф с классом</p>

Синтаксис атрибутов

Ключевые особенности синтаксиса:

  • .class-name — добавление класса к элементу.
  • #id-name — назначение id.
  • [attr=value] — добавление произвольного атрибута.
  • Несколько классов можно перечислять через пробел, например: {.class1 .class2}.

Пример с атрибутами и классами:

![Альтернативный текст](image.png){.responsive width=300 title="Пример изображения"}

HTML:

<img src="image.png" alt="Альтернативный текст" class="responsive" width="300" title="Пример изображения">

Программное добавление атрибутов через рендереры

Markdown-it предоставляет возможность переопределять рендереры отдельных токенов, что позволяет добавлять атрибуты программно, без использования синтаксиса в Markdown.

Пример добавления класса ко всем ссылкам:

const defaultRender = md.renderer.rules.link_open || function(tokens, idx, options, env, self) {
  return self.renderToken(tokens, idx, options);
};

md.renderer.rules.link_open = function(tokens, idx, options, env, self) {
  const token = tokens[idx];
  token.attrPush(['class', 'external-link']); // добавление класса
  return defaultRender(tokens, idx, options, env, self);
};

const result = md.render('[Ссылка](https://example.com)');
console.log(result);

Результат:

<p><a href="https://example.com" class="external-link">Ссылка</a></p>

Модификация заголовков

Для автоматического добавления классов и id к заголовкам можно использовать встроенные события токенов:

md.core.ruler.push('add_header_class', function(state) {
  state.tokens.forEach(token => {
    if (token.type === 'heading_open') {
      token.attrSet('class', 'custom-heading');
    }
  });
});

const html = md.render('# Пример заголовка');
console.log(html);

HTML:

<h1 class="custom-heading">Пример заголовка</h1>

Управление атрибутами списков и элементов

Атрибуты могут добавляться к любым блокам Markdown. Например, списки и элементы списка:

- Пункт 1 {.important}
- Пункт 2 {.secondary}

Результат:

<ul>
  <li class="important">Пункт 1</li>
  <li class="secondary">Пункт 2</li>
</ul>

Также можно комбинировать плагин markdown-it-attrs с пользовательскими рендерерами для сложной логики, например, динамического добавления data-атрибутов на основе содержимого:

md.renderer.rules.bullet_list_open = function(tokens, idx, options, env, self) {
  tokens[idx].attrSet('data-list', 'true');
  return self.renderToken(tokens, idx, options);
};

const htmlList = md.render('- Элемент списка');
console.log(htmlList);

Результат:

<ul data-list="true">
  <li>Элемент списка</li>
</ul>

Использование атрибутов для таблиц

Markdown-it поддерживает расширения для таблиц. С помощью markdown-it-attrs можно добавлять классы и стили:

| Заголовок 1 | Заголовок 2 |
|-------------|-------------|
| Ячейка 1    | Ячейка 2    {.highlight} |

HTML:

<table>
  <thead>
    <tr>
      <th>Заголовок 1</th>
      <th>Заголовок 2</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Ячейка 1</td>
      <td class="highlight">Ячейка 2</td>
    </tr>
  </tbody>
</table>

Практические рекомендации

  • Для единообразного оформления лучше сочетать плагин markdown-it-attrs с пользовательскими рендерерами.
  • Атрибуты можно использовать для стилей, идентификаторов, data-атрибутов, что позволяет интегрировать Markdown в сложные фронтенд-приложения.
  • Программное управление токенами предоставляет гибкость при создании динамического контента, например, добавления классов к определённым типам элементов на основе условий.

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

Оглавление