Предыдущая и следующая страница

MDX сочетает возможности Markdown и React-компонентов, что позволяет создавать динамическую и структурированную документацию. Одним из важных аспектов построения многостраничной документации является организация перехода между страницами, особенно функции «Предыдущая» и «Следующая» страница.

Использование метаданных для навигации

В MDX каждая страница может содержать frontmatter, который задаёт ключевую информацию о странице:

---
title: "Основы MDX"
slug: "/mdx-basics"
order: 1
---
  • title — заголовок страницы.
  • slug — уникальный путь страницы.
  • order — числовой порядок, используемый для сортировки страниц.

Для построения навигации важно иметь упорядоченный список страниц. В большинстве проектов его формируют либо статически при сборке, либо динамически с помощью файловой системы и парсинга frontmatter.

Формирование структуры страниц

Создание массива объектов, представляющих страницы, позволяет реализовать навигацию:

import fs from 'fs';
import path from 'path';
import matter from 'gray-matter';

const pagesDirectory = path.join(process.cwd(), 'pages/mdx');
const files = fs.readdirSync(pagesDirectory);

const pages = files.map(filename => {
  const filePath = path.join(pagesDirectory, filename);
  const fileContents = fs.readFileSync(filePath, 'utf8');
  const { data } = matter(fileContents);

  return {
    title: data.title,
    slug: data.slug,
    order: data.order
  };
}).sort((a, b) => a.order - b.order);

После сортировки по order каждая страница получает индекс, по которому можно определить предыдущую и следующую страницы.

Компонент навигации

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

import Link from 'next/link';

export default function PageNavigation({ currentSlug, pages }) {
  const currentIndex = pages.findIndex(page => page.slug === currentSlug);
  const previousPage = pages[currentIndex - 1];
  const nextPage = pages[currentIndex + 1];

  return (
    <nav className="page-navigation">
      {previousPage && (
        <Link href={previousPage.slug}>
          <a className="previous-page">← {previousPage.title}</a>
        </Link>
      )}
      {nextPage && (
        <Link href={nextPage.slug}>
          <a className="next-page">{nextPage.title} →</a>
        </Link>
      )}
    </nav>
  );
}

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

  • Проверка существования предыдущей и следующей страницы предотвращает ошибки на первой и последней странице.
  • Компонент остаётся универсальным: достаточно передать текущий slug и массив pages.

Стилизация навигации

Навигация должна быть визуально понятной. Пример CSS для горизонтальной навигации:

.page-navigation {
  display: flex;
  justify-content: space-between;
  margin-top: 2rem;
  padding: 1rem 0;
  border-top: 1px solid #ddd;
}

.page-navigation a {
  color: #0070f3;
  text-decoration: none;
  font-weight: 500;
}

.page-navigation a:hover {
  text-decoration: underline;
}

Интеграция в MDX страницы

Встраивание компонента навигации на каждую MDX страницу:

import PageNavigation from '../components/PageNavigation';
import pages from '../pagesData';

# Основы MDX

MDX объединяет Markdown и JSX, что позволяет использовать React-компоненты внутри документации.

<PageNavigation currentSlug="/mdx-basics" pages={pages} />

Особенности интеграции:

  • currentSlug должен соответствовать slug страницы.
  • pages может быть импортирован как статический массив, либо сгенерирован динамически при сборке сайта.

Автоматическая генерация навигации

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

export function getStaticProps({ params }) {
  const pages = getAllPages(); // возвращает упорядоченный массив
  const currentPageIndex = pages.findIndex(p => p.slug === params.slug);
  
  return {
    props: {
      pages,
      currentSlug: params.slug,
      previousPage: pages[currentPageIndex - 1] || null,
      nextPage: pages[currentPageIndex + 1] || null
    }
  };
}

Такой подход позволяет:

  • Автоматически обновлять ссылки при добавлении новых страниц.
  • Исключить ошибки из-за пропущенных ссылок.
  • Поддерживать правильный порядок навигации без ручного вмешательства.

Расширенные возможности

  1. Многоуровневая навигация: Страницы могут содержать категории и подкатегории. Для этого массив страниц строится с вложенными объектами, а компонент навигации адаптируется к структуре.

  2. Динамическое выделение активной страницы: Использование класса active позволяет визуально подсвечивать текущую страницу в списке навигации.

  3. Интеграция с роутингом: В проектах Next.js или Gatsby маршруты автоматически связываются со slug из frontmatter, что упрощает навигацию.

Примеры практического применения

  • Документация библиотек и фреймворков, где страницы логично идут по шагам.
  • Учебные курсы с последовательными уроками.
  • Руководства пользователя с пошаговыми инструкциями.

Организация «Предыдущая» и «Следующая» страница в MDX позволяет сделать документацию интерактивной, логичной и удобной для чтения, сохраняя структуру и гибкость React-компонентов.

Оглавление