Навигация и оглавление

MDX сочетает возможности Markdown и React, позволяя создавать интерактивные и динамические документы. Для управления навигацией и оглавлением в документации ключевым является использование компонентов и API, предоставляемых MDX и сопутствующими инструментами, такими как @mdx-js/react и статические генераторы сайтов типа Next.js.

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

MDX позволяет автоматически генерировать оглавление на основе заголовков документа. Для этого можно использовать компонент, который обходит все заголовки h1, h2, h3 и формирует структуру списка. Пример подхода:

import { useEffect, useState } from 'react';

function TableOfContents({ children }) {
  const [headings, setHeadings] = useState([]);

  useEffect(() => {
    const elements = Array.from(document.querySelectorAll('h1, h2, h3'));
    const toc = elements.map(el => ({
      text: el.innerText,
      id: el.id,
      level: Number(el.tagName[1])
    }));
    setHeadings(toc);
  }, []);

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

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

  • Заголовки должны иметь уникальные id для корректной навигации.
  • Отступы для вложенных уровней позволяют визуально показать иерархию документа.
  • Компонент может быть размещён в боковой панели или в начале документа.

Сквозная навигация по документу

Для реализации навигации между разделами или страницами используется сочетание MDX и React Router или Next.js Link:

import Link from 'next/link';

function Navigation({ previous, next }) {
  return (
    <div style={{ display: 'flex', justifyContent: 'space-between' }}>
      {previous && <Link href={previous.href}>← {previous.title}</Link>}
      {next && <Link href={next.href}>{next.title} →</Link>}
    </div>
  );
}

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

  • previous и next передаются как объекты с заголовком и ссылкой.
  • Навигационные элементы можно фиксировать внизу страницы, создавая удобную линейку перемещения.

Внутридокументные ссылки

MDX позволяет использовать якорные ссылки напрямую в тексте:

## Раздел 1 {#section1}

[Перейти к Разделу 1](#section1)

Важные моменты:

  • Синтаксис {#id} добавляет явный идентификатор заголовку.
  • MDX корректно интерпретирует ссылки и позволяет переходить по документу без перезагрузки.

Генерация оглавления на этапе сборки

В больших документациях часто используется статическая генерация оглавления. Для этого применяются плагины, анализирующие Markdown AST (Abstract Syntax Tree):

import remark from 'remark';
import remarkParse from 'remark-parse';
import visit from 'unist-util-visit';

const generateTOC = (content) => {
  const tree = remark().use(remarkParse).parse(content);
  const toc = [];
  visit(tree, 'heading', (node) => {
    toc.push({
      text: node.children.map(child => child.value).join(''),
      level: node.depth
    });
  });
  return toc;
};

Преимущества подхода:

  • Генерация оглавления происходит один раз при сборке, снижая нагрузку на клиент.
  • Позволяет формировать JSON-структуру оглавления для динамического рендеринга через React.

Интерактивные элементы навигации

MDX позволяет внедрять React-компоненты прямо в документ. Это открывает возможности для создания:

  • Дропдаунов с разделами документа;
  • Кнопок «Вверх» для быстрого возврата к началу;
  • Фильтров и поиска по заголовкам внутри документа.

Пример кнопки возврата:

function ScrollToTop() {
  const handleClick = () => window.scrollTo({ top: 0, beh * avior: 'smooth' });
  return <button onCl ick={handleClick}>Наверх</button>;
}

Структурирование навигации в проекте

Для больших проектов рекомендуется:

  1. Разделять MDX-документы по темам.
  2. Создавать центральный конфиг навигации:
export const navConfig = [
  { title: 'Введение', href: '/docs/intro' },
  { title: 'Основы MDX', href: '/docs/basics' },
  { title: 'Навигация и оглавление', href: '/docs/navigation' },
];
  1. Использовать один компонент навигации, который получает конфиг и рендерит боковое меню.

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

  • Облегчает поддержку структуры документации.
  • Позволяет быстро менять порядок разделов без правки отдельных MDX-файлов.

Итоговая схема взаимодействия

  1. Создание заголовков с уникальными ID — основа для навигации и оглавления.
  2. Автоматическая генерация TOC — на клиенте через useEffect или на этапе сборки через AST.
  3. Сквозная навигация между страницами — через Link или React Router.
  4. Интерактивные элементы — кнопки, фильтры и дропдауны для удобства пользователя.
  5. Централизованный конфиг навигации — поддержка консистентной структуры документации.

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

Оглавление