Семантическая разметка

MDX (Markdown for JSX) позволяет объединять возможности Markdown и React-компонентов, создавая удобный инструмент для написания документации и контента с интерактивными элементами. Семантическая разметка в MDX играет ключевую роль, обеспечивая структурированное представление контента и улучшая доступность.

Заголовки и структурирование документа

В MDX заголовки создаются так же, как в Markdown, с помощью символа #:

# Основной заголовок
## Подзаголовок второго уровня
### Подзаголовок третьего уровня

Особенности:

  • Заголовки формируют иерархию документа, что важно для навигации и SEO.
  • Встраивание React-компонентов внутри заголовков возможно, но следует учитывать визуальное оформление и семантическую ценность:
## <Badge text="Новый" /> Подзаголовок

Абзацы и семантические блоки

MDX использует обычные Markdown-абзацы, которые автоматически рендерятся как <p> в HTML. Для логического выделения информации применяются блоки цитат и списки.

Цитаты:

> Это цитата, которая передается через MDX как <blockquote>.

Списки:

- Пункт списка
- Еще один пункт

Нумерованные списки создаются с помощью цифр:

1. Первый шаг
2. Второй шаг

Списки можно комбинировать с React-компонентами для создания интерактивных элементов:

- <InteractiveButton label="Кликни меня" />

Семантические элементы HTML

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

  • <section> — логический блок документа.
  • <article> — самостоятельный фрагмент контента.
  • <aside> — вспомогательная информация, например подсказки или примечания.
  • <header> и <footer> — заголовки и нижние колонтитулы блоков.

Пример:

<section>
  <header>
    <h2>Пример секции</h2>
  </header>
  <p>Текст секции с семантическим выделением.</p>
  <aside>Вспомогательная информация</aside>
  <footer>Примечание к секции</footer>
</section>

Классы и стилизация компонентов

MDX позволяет передавать пропсы и классы React-компонентам для управления стилем и семантикой. Использование классов и атрибутов role улучшает доступность:

<Callout className="warning" role="alert">
  Важно: соблюдайте семантику при использовании интерактивных элементов.
</Callout>

Таблицы и семантическое выделение данных

Таблицы в MDX создаются стандартным синтаксисом Markdown и рендерятся как <table>. Важно использовать заголовки колонок через | и --- для правильной семантики:

| Имя | Возраст | Должность |
|-----|--------|-----------|
| Иван | 30 | Разработчик |
| Анна | 25 | Дизайнер |

Для расширенной семантики можно использовать HTML-таблицы с <thead>, <tbody> и <th>:

<table>
  <thead>
    <tr><th>Имя</th><th>Возраст</th></tr>
  </thead>
  <tbody>
    <tr><td>Иван</td><td>30</td></tr>
    <tr><td>Анна</td><td>25</td></tr>
  </tbody>
</table>

Интерактивные и динамические элементы

MDX позволяет включать компоненты React, сохраняя при этом семантическую структуру. Например, кнопки, вкладки и аккордеоны должны использовать корректные HTML-ролики:

<Tabs role="tablist">
  <Tab label="Описание">Контент вкладки 1</Tab>
  <Tab label="Пример">Контент вкладки 2</Tab>
</Tabs>

Использование правильных атрибутов role, aria-expanded и aria-controls делает контент доступным для скринридеров.

Выделение кода и блоки с подсветкой

MDX поддерживает блоки кода через тройные обратные кавычки:

```javascript
function sum(a, b) {
  return a + b;
}

**Рекомендации по семантике:**
- Указывать язык для подсветки синтаксиса.
- Использовать `code` и `pre` теги корректно для доступности.
- Можно внедрять React-компоненты для интерактивного кода:

```mdx
<LiveCode code={`console.log("Hello MDX")`} />

Ссылки и навигация

Семантически правильные ссылки оформляются через Markdown или JSX:

[Документация MDX](https://mdxjs.com/)

Для кастомных компонентов важно использовать a или Link с атрибутами href и rel:

<Link href="/guide" rel="noopener">Перейти к руководству</Link>

Итоги по семантике MDX

  • Использование стандартных Markdown-элементов обеспечивает базовую семантику.
  • HTML-теги позволяют уточнять структуру документа и создавать сложные блоки.
  • React-компоненты должны сохранять семантическую целостность и доступность.
  • Атрибуты role и aria-* помогают пользователям с ограничениями восприятия.

Соблюдение этих принципов делает MDX-документы структурированными, удобными для восприятия людьми и машинами, и готовыми к интеграции в сложные веб-приложения.

Оглавление