Списки и вложенность

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

Нумерованные и маркированные списки создаются стандартными способами:

1. Первый элемент
2. Второй элемент
3. Третий элемент

- Пункт A
- Пункт B
- Пункт C

Нумерованные списки поддерживают автоматическую последовательность, а маркированные списки могут использовать -, * или + в качестве маркеров. Важный момент: для корректного рендеринга вложенных списков необходимо соблюдать отступы — обычно 2–4 пробела или один таб.

Вложенные списки

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

1. Элемент первого уровня
  - Подпункт A
  - Подпункт B
    1. Подподпункт 1
    2. Подподпункт 2
2. Второй элемент

Ключевые правила вложенности:

  • Каждый уровень вложенности отделяется двумя пробелами или одним табом от предыдущего.
  • Смешивание маркеров (-, *, +) и нумерации возможно, но последовательность вложенности должна быть логичной для читателя и рендерера.
  • Внутри элементов списка можно использовать любые MDX- или JSX-компоненты, например:
- Пункт с компонентом

Списки и JSX

MDX позволяет вставлять JSX внутри элементов списка, что открывает новые возможности для интерактивной документации. Компоненты могут быть встроены как отдельные блоки, так и inline:

1. Пункт с inline-компонентом 
2. Пункт с блоковым компонентом:
  
    Важное предупреждение!

Особенности работы с JSX внутри списков:

  • Блоковые компоненты должны быть сдвинуты на уровень вложенности списка, иначе парсер может некорректно интерпретировать структуру.
  • Inline-компоненты могут располагаться прямо в тексте элемента списка без дополнительного форматирования.
  • Использование JSX позволяет динамически изменять содержимое элементов списков на основе пропсов или состояния.

Вложенные списки с абзацами и блоками кода

Элементы списка могут содержать не только текст, но и целые блоки Markdown или MDX:

- Пункт с абзацем

  Дополнительный текст, который продолжается на новой строке с отступом.

- Пункт с кодом

  ```javascript
  function greet(name) {
    return `Привет, ${name}!`;
  }

**Важно:**

- Абзацы внутри элементов списка должны иметь пустую строку перед ними и корректный отступ.
- Блоки кода требуют дополнительного отступа на 2 пробела относительно маркера списка, иначе рендерер может не распознать их как часть элемента.

---

### Практические советы по структуре списков в MDX

1. **Поддерживать единообразие маркеров:** избегать смешивания `-`, `*`, `+` на одном уровне вложенности.
2. **Соблюдать отступы:** особенно при вставке блоков JSX и многострочных абзацев.
3. **Использовать нумерованные списки для пошаговых инструкций**, а маркированные для перечислений без строгого порядка.
4. **Не забывать про совместимость с Markdown-рендерерами**, если MDX будет преобразовываться в HTML или другие форматы.

---

### Комбинация списков и компонентов

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

```mdx
1. Установите пакет
  npm install mdx-package
2. Импортируйте компонент
  
    import { Component } from 'mdx-package';
  
3. Используйте компонент в списке
  - Первый пример 
  - Второй пример

Такой подход упрощает создание интерактивных учебников и документации, где каждый шаг сопровождается демонстрацией кода и компонентами интерфейса.

Оглавление