6. MDX и кастомные компоненты

Ваш модуль 20-mdx показывает, как в Next.js:

• подключать MDX‑файлы (.mdx) как страницы,
• переопределять стандартные теги (например, <h1>),
• создавать общий layout для MDX‑страниц,
• работать с кастомными компонентами через useMDXComponents.

6.1. Базовая интеграция MDX: страница с импортом .mdx

В Next.js MDX‑страницы можно использовать как обычные React‑компоненты:

• когда вы импортируете .mdx файл, он становится компонентом,
• вы можете передать ему components, чтобы переопределить встроенные элементы.

Пример страницы app/20-mdx/page.tsx:

// @ts-nocheck

import Welcome from '@/markdown/welcome.mdx';

function CustomH1({ children }) {
  return <h1 style={{ color: 'blue', fontSize: '100px' }}>{children}</h1>;
}

const overrideComponents = {
  h1: CustomH1,
};

export default function Page() {
  return <Welcome components={overrideComponents} />;
}

Принципы:

• Любой MDX‑файл можно отрендерить как компонент <Welcome />.
• Через проп components можно подменять поведение стандартных тегов:
  • h1, h2, p, a, img, ul, li и т.д.

6.2. Общий layout для MDX‑страниц

Файл app/20-mdx/layout.tsx задаёт:

• общий layout для маршрута /20-mdx,
• единое оформление для всех дочерних страниц (в т.ч. MDX).

Пример:

// @ts-nocheck

export default function MdxLayout({ children }: { children: React.ReactNode }) {
  // Общие стили/оформление для всех MDX‑страниц в этом маршруте
  return <div style={{ color: 'blue' }}>{children}</div>;
}

Принципы:

• Layout для MDX‑страниц ничем не отличается от обычного layout.tsx.
• Удобно использовать для:
  • оформления документации,
  • боковой навигации, заголовков, футера,
  • общей типографики для MDX‑контента.

6.3. useMDXComponents: глобовое переопределение элементов

Файл src/mdx-components.tsx предоставляет функцию useMDXComponents:

• позволяет задать глобовые компоненты для MDX,
• возвращает объект, который интегрируется через Next.js/MDX‑конфигурацию.

Пример:

import type { MDXComponents } from 'mdx/types';
import Image, { ImageProps } from 'next/image';

export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    // Кастомный <h1> для всего MDX
    h1: ({ children }) => (
      <h1 style={{ color: 'red', fontSize: '48px' }}>{children}</h1>
    ),

    // Кастомный <img>, обёрнутый в next/image
    img: (props) => (
      <Image
        sizes="100vw"
        style={{ width: '100%', height: 'auto' }}
        {...(props as ImageProps)}
      />
    ),

    // Не забываем прокинуть переданные компоненты
    ...components,
  };
}

Принципы:

• Через useMDXComponents вы задаёте дефолтные компоненты для всех MDX‑страниц.
• Это удобно для:
  • единообразного стиля заголовков и текста,
  • интеграции next/image вместо обычных <img>,
  • подключения компонентов дизайна‑систем (кнопки, карточки, блоки).

6.4. Пример MDX‑файла с использованием кастомных компонентов

Предположим, у вас есть файл markdown/welcome.mdx:

# Добро пожаловать в документацию

Это пример MDX‑страницы, где:

- мы можем использовать **Markdown** синтаксис;
- вставлять React‑компоненты прямо внутрь;
- использовать кастомные компоненты для `h1`, `img` и других тегов.

![Картинка](./image.png)

<CustomButton>Нажми меня</CustomButton>

При рендере:

• # Добро пожаловать... превратится в кастомный <h1> из useMDXComponents или overrideComponents,
• ![Картинка] превратится в ваш кастомный img → <Image />,
• <CustomButton> будет отрисован, если вы передадите его через components или глобово определите в useMDXComponents.

6.5. Паттерн для документации на MDX

Ваш модуль 20-mdx отлично подходит как основа для собственной документации:

• создайте структуру:

src/
  markdown/
    intro.mdx
    getting-started.mdx
    forms.mdx
    isr.mdx
app/
  docs/
    layout.tsx        // общий layout для документации
    page.tsx          // список разделов/оглавление
    [slug]/
      page.tsx        // рендер определённого MDX по slug

• используйте useMDXComponents для глобового стиля;
• переопределяйте компоненты локально через components при необходимости.

Пример рендера раздела документации по slug:

// app/docs/[slug]/page.tsx
import Intro from '@/markdown/intro.mdx';
import Forms from '@/markdown/forms.mdx';

const map = {
  intro: Intro,
  forms: Forms,
} as const;

export default function DocsPage({ params }: { params: { slug: string } }) {
  const MDX = map[params.slug as keyof typeof map] ?? Intro;
  return <MDX />;
}

6.6. Общие принципы работы с MDX в Next.js

С учётом ваших примеров:

• MDX — это React‑компонент + Markdown:
  • всё, что можно в React, можно и в MDX (с некоторыми ограничениями),
  • удобно для документации, блога, страниц помощи.
• Переопределяйте стандартные элементы:
  • через useMDXComponents для глобового влияния,
  • через components={...} для локального переопределения.
• Используйте layout’ы для единообразия:
  • общий layout.tsx для ветки app/20-mdx или app/docs,
  • боковая навигация, заголовки, футер, темизация.
• Интегрируйте next/image и дизайн‑систему:
  • заменяйте img на <Image />,
  • используйте типы MDXComponents для строгой типизации.

Этот модуль‑конспект поможет быстро вспомнить, как устроена связка Next.js + MDX в вашем проекте и как расширять её под свою документацию или блог.