Заголовки и якоря

MDX сочетает возможности Markdown и React-компонентов, что делает управление заголовками и якорями особенно гибким. Заголовки создаются стандартными Markdown-синтаксисом #–###### и автоматически преобразуются в HTML-теги <h1>–<h6>.

# Заголовок первого уровня
## Заголовок второго уровня
### Заголовок третьего уровня

Автоматическое создание якорей

MDX, как правило, используется совместно с системой сборки (например, Next.js или Gatsby), которая поддерживает автоматическое создание якорей для заголовков. Каждому заголовку присваивается уникальный идентификатор (id), который формируется из текста заголовка.

Пример с React-компонентом Heading в MDX:

import { Heading } from '@theme-ui/mdx'

<Heading as="h2" id="second-heading">
  Заголовок второго уровня
</Heading>

В этом примере заголовку явно присвоен id, что позволяет ссылаться на него из других частей документа:

[Перейти к заголовку](#second-heading)

Генерация якорей автоматически

Большинство инструментов для MDX поддерживают автоматическое присвоение id заголовкам без необходимости явно их указывать. Текст заголовка преобразуется в “чистый” формат для ссылки, например:

## Мой заголовок с пробелами

Автоматически получит:

<h2 id="мой-заголовок-с-пробелами">Мой заголовок с пробелами</h2>

Таким образом можно формировать внутренние ссылки на заголовки:

[Ссылка на заголовок](#мой-заголовок-с-пробелами)

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

MDX позволяет заменять стандартные заголовки на кастомные React-компоненты для управления стилем, функционалом или поведением якорей:

import { AnchorHeading } from './components/AnchorHeading'

<AnchorHeading level={3}>
  Заголовок с кастомным якорем
</AnchorHeading>

Компонент AnchorHeading может автоматически добавлять иконку якоря, прокрутку к заголовку и другие визуальные эффекты. Пример реализации:

export function AnchorHeading({ level, children }) {
  const Tag = `h${level}`
  const id = children.toString().toLowerCase().replace(/\s+/g, '-')
  
  return (
    <Tag id={id}>
      <a href={`#${id}`} style={{ textDecoration: 'none', color: 'inherit' }}>
        {children}
      </a>
    </Tag>
  )
}

Внутренние ссылки и навигация

Использование якорей особенно полезно для длинных документов и оглавлений. В MDX можно динамически генерировать оглавление, получая все заголовки с их id:

const headings = [
  { id: 'заголовок-первый', text: 'Заголовок первый', level: 2 },
  { id: 'заголовок-второй', text: 'Заголовок второй', level: 2 },
]

function TableOfContents() {
  return (
    <ul>
      {headings.map(h => (
        <li key={h.id} style={{ marginLeft: (h.level - 1) * 10 }}>
          <a href={`#${h.id}`}>{h.text}</a>
        </li>
      ))}
    </ul>
  )
}

Это позволяет создавать интерактивное оглавление, полностью управляемое React-компонентами, с прокруткой к нужным разделам страницы.

Особенности SEO и доступности

  • Заголовки должны сохранять иерархию: <h1>–<h6>.
  • id якорей должен быть уникальным на странице для корректной работы ссылок.
  • Добавление ссылок с видимым текстом, а не только иконкой, повышает доступность для пользователей экранных читалок.

Рекомендации по стилю и структуре

  1. Для документации лучше использовать <h2>–<h4>, <h1> оставляя для главного заголовка страницы.
  2. Автоматическое формирование id следует проверять на корректность кириллицы и специальных символов.
  3. Для интерактивных компонентов заголовков использовать отдельные React-компоненты, чтобы централизованно управлять стилем и функционалом якорей.

Пример интеграции всего подхода

import { AnchorHeading } from './components/AnchorHeading'
import TableOfContents from './components/TableOfContents'

<TableOfContents />

<AnchorHeading level={2}>Введение</AnchorHeading>
<p>Основные концепции MDX.</p>

<AnchorHeading level={2}>Заголовки и якоря</AnchorHeading>
<p>Использование стандартных и кастомных компонентов для навигации.</p>

<AnchorHeading level={3}>Автоматические якоря</AnchorHeading>
<p>Как генерируются `id` и ссылки на заголовки.</p>

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

Оглавление