Структура документации

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

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

Документы MDX используют стандартные Markdown-заголовки (#, ##, ###) для организации содержания:

# Основной заголовок
## Подраздел
### Подподраздел

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

  • Заголовки формируют структуру документации и используются для генерации навигации.
  • В больших проектах рекомендуется единообразное использование заголовков для обеспечения читаемости и поддержки автогенерации TOC (Table of Contents).

Параграфы и текстовое форматирование

MDX поддерживает Markdown-синтаксис для форматирования текста:

  • Жирный текст: **важное**

  • Курсив: *выделение*

  • Списки:

    • Нумерованные: 1. Первый пункт
    • Маркированные: - Второй пункт

Важное отличие MDX от обычного Markdown — возможность вставки JSX-компонентов в любом месте текста:

Текст параграфа с интерактивной кнопкой:
<Button onCl ick={() => alert('Пример')}>Нажми меня</Button>

Вставка компонентов

MDX позволяет комбинировать Markdown и JSX. Любой React-компонент может быть встроен в текст документации:

import { Alert, CodeBlock } from './components'

<Alert type="warning">
  Внимание: этот пример важен для понимания структуры.
</Alert>

<CodeBlock language="js">
{`console.log('MDX позволяет писать интерактивную документацию')`}
</CodeBlock>

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

  • Компоненты можно импортировать из внешних файлов или локальных директорий.
  • JSX-код обрабатывается как часть документации и может содержать состояния, обработчики событий и стили.

Секции и навигация

Для крупных документов рекомендуется делить текст на логические блоки, используя секции с заголовками второго уровня (##). Каждая секция может включать:

  • Описание концепции
  • Примеры кода
  • Встроенные компоненты

Пример структуры секции:

## Работа с состоянием

React-компоненты в MDX могут использовать хуки:

<Counter initial={0} />

Примеры и демонстрации

MDX особенно удобен для интерактивных примеров кода:

import { Counter } from './Counter'

<Counter initial={5} step={2} />

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

  • Каждый пример можно сопровождать текстовым объяснением.
  • Код можно оформлять в виде блоков (```) или как живой компонент, который реагирует на действия пользователя.

Метаданные документа

MDX поддерживает метаданные (frontmatter) для описания документа:

---
title: "Пример документации"
description: "Документ описывает использование MDX с компонентами React"
tags: ["MDX", "React", "Документация"]
---

Метаданные помогают:

  • Автоматически генерировать списки документации
  • Формировать SEO-описания
  • Категоризировать материалы по темам

Встраивание внешних ресурсов

MDX позволяет включать внешние файлы и изображения:

![Логотип](./logo.png)

import VideoPlayer from './VideoPlayer'

<VideoPlayer src="intro.mp4" />

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

  • Поддерживаются локальные и внешние ресурсы
  • Изображения и видео можно сопровождать текстом и интерактивными элементами

Структура больших проектов

В крупных проектах документацию обычно делят на модули:

docs/
├─ introduction.mdx
├─ guides/
│  ├─ setup.mdx
│  ├─ components.mdx
├─ examples/
│  ├─ basic.mdx
│  ├─ advanced.mdx

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

  • Поддержка модульной структуры
  • Упрощение навигации и поиска
  • Возможность повторного использования компонентов в разных частях документации

Заключение по структуре

MDX сочетает простоту Markdown с мощью React-компонентов. Ключевой принцип организации документации:

  • Четкая иерархия заголовков
  • Логическое деление на секции
  • Использование интерактивных компонентов для демонстрации
  • Метаданные для управления и генерации навигации
  • Встраивание внешних ресурсов для наглядности

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

Оглавление