Базовый Markdown синтаксис

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

Заголовки

Заголовки создаются с помощью символа #. Количество символов # определяет уровень заголовка:

# Заголовок первого уровня
## Заголовок второго уровня
### Заголовок третьего уровня
#### Заголовок четвертого уровня
##### Заголовок пятого уровня
###### Заголовок шестого уровня

В MDX заголовки работают аналогично, но могут быть использованы для генерации компонентов или навигации по странице через автоматическую привязку к ID.

Абзацы и переносы строк

Абзацы создаются простым отделением текста одной или несколькими пустыми строками. Для переноса строки без создания нового абзаца используется два пробела в конце строки:

Это первый абзац.  
Это продолжение в том же абзаце.

Жирный и курсивный текст

Для выделения текста используются:

  • Жирный текст: **текст** или __текст__
  • Курсив: *текст* или _текст_
  • Комбинированный эффект: ***текст*** для жирного курсивного текста

MDX сохраняет эти стили, и их можно комбинировать с компонентами:

**Пример жирного текста с <Button>кнопкой</Button> внутри**

Списки

Списки делятся на маркированные и нумерованные.

Маркированный список:

- Пункт 1
- Пункт 2
  - Подпункт 2.1
  - Подпункт 2.2
* Альтернативный маркер

Нумерованный список:

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

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

- Пункт 1 <Badge text="новое" />

Ссылки и изображения

Ссылки оформляются так:

[Текст ссылки](https://example.com)

Можно добавлять заголовок при наведении:

[Текст ссылки](https://example.com "Описание ссылки")

Изображения используют аналогичный синтаксис с префиксом !:

![Альтернативный текст](https://example.com/image.png)

В MDX можно интегрировать React-компоненты для изображений:

<Image src="/logo.png" alt="Логотип" width={100} />

Цитаты

Цитаты оформляются с помощью символа >:

> Это цитата
> продолжается на следующей строке

Многоуровневые цитаты создаются добавлением нескольких >:

> Внешняя цитата
>> Внутренняя цитата

Код и блоки кода

Однострочный код оформляется с помощью одинарных обратных кавычек `код`. Блочные вставки кода — с помощью тройных обратных кавычек ```:

```javascript
function sum(a, b) {
  return a + b;
}

MDX позволяет использовать JSX в блоках кода, а также импортировать компоненты для визуализации примеров:

```markdown
<CodeBlock language="jsx">
{`
function Button() {
  return <button>Нажми меня</button>;
}
`}
</CodeBlock>

Горизонтальные линии

Горизонтальная линия создается тремя или более символами -, * или _:

---
***
___

В MDX горизонтальные линии могут визуально разделять контент, сохраняя семантику документа.

Таблицы

Таблицы оформляются с помощью вертикальных линий | и дефисов - для заголовка:

| Заголовок 1 | Заголовок 2 |
|------------|------------|
| Ячейка 1  | Ячейка 2  |
| Ячейка 3  | Ячейка 4  |

Выравнивание колонок:

| Лево   | Центр  | Право   |
|:-------|:------:|--------:|
| Текст  | Текст  | Текст   |

MDX позволяет вставлять в ячейки таблицы компоненты, например <Badge> или <Link>.

Экранирование символов

Для специальных символов Markdown (*, _, [, ], #) используется обратный слеш \:

\*Это не курсив\*

Это особенно важно при интеграции с JSX, чтобы символы не интерпретировались как синтаксис Markdown.

Заключение синтаксических основ

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

Оглавление