Заголовки страниц

MDX — это расширение Markdown, которое позволяет использовать JSX внутри Markdown-файлов. Работа с заголовками страниц в MDX сочетает возможности стандартного Markdown с динамикой React-компонентов, что делает процесс управления структурой контента более гибким.

Использование стандартных заголовков Markdown

MDX поддерживает синтаксис Markdown для заголовков:

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

Каждый заголовок автоматически преобразуется в соответствующий HTML-тег <h1>, <h2>, <h3> и так далее. Это важно для SEO и семантики страницы.

Ключевые моменты:

Заголовки уровня h1 рекомендуется использовать только один раз на страницу.
Заголовки более низких уровней (h2, h3) создают иерархию и помогают навигации по содержимому.
MDX позволяет сочетать заголовки с JSX-компонентами, например, для добавления кнопок или интерактивных элементов внутри заголовка.

Динамические заголовки с JSX

MDX позволяет внедрять React-компоненты прямо в заголовки:

# Welcome <Button label="Click me" />

В этом примере <Button /> будет отрисован внутри заголовка, сохраняя при этом семантику h1.

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

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

Создание автоматической генерации заголовков

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

export const pageTitle = "MDX Заголовки";

# {pageTitle}

MDX автоматически подставляет значение переменной pageTitle в заголовок.

Применение:

Генерация заголовков из API или CMS.
Возможность создавать шаблоны страниц с одинаковой структурой, где уникальная часть заголовка подставляется через переменные.

Стилизация заголовков

MDX поддерживает как стандартные CSS-классы, так и стилизованные компоненты:

import { styled } from '@emotion/react';

const H2 = styled.h2`
  color: #4a90e2;
  font-weight: bold;
`;

<H2>Стилизованный заголовок второго уровня</H2>

Преимущества:

Полная контроль над визуальным представлением.
Возможность интеграции с темами и глобальными стилями.
Возможность создания повторно используемых компонентных заголовков для унифицированного оформления.

Использование MDX в рамках маршрутизации

MDX-файлы часто применяются вместе с системами маршрутизации, такими как Next.js или Gatsby. Заголовки играют ключевую роль в SEO и навигации. Например, Next.js позволяет автоматически извлекать заголовки для генерации meta title и оглавления:

import { getMDXContent } from '../lib/mdx';

export async function getStaticProps() {
  const content = await getMDXContent('page.mdx');
  const title = content.match(/^#\s+(.*)/m)?.[1] || 'Default Title';
  return { props: { title, content } };
}

Важные аспекты:

Первый заголовок h1 страницы можно использовать для метатегов.
Заголовки h2–h6 помогают строить динамическое оглавление.
Обеспечивается согласованная семантика и улучшается SEO.

Автоматическое оглавление (TOC)

MDX позволяет создавать оглавление на основе заголовков страницы:

import { Toc } from './components/Toc';

<Toc headings={['Введение', 'Использование', 'Стилизация']} />

Toc может генерироваться автоматически, извлекая все заголовки h2–h4 с страницы.
Это особенно полезно для больших статей и документаций.
С помощью JS можно реализовать плавную прокрутку к соответствующим разделам при клике по ссылке в TOC.