Гайд по возможностям Markdown в блоге

В этом посте — все расширения разметки, которые поддерживает наш блог. Каждый пример показан рядом: слева код, справа результат.

Базовые элементы

Жирный, курсив, зачёркивание

**Жирный текст**, *курсив*, ~~зачёркнутый~~

Блоки кода

Три бэктика с указанием языка — и Pygments раскрасит синтаксис:

```python
def greet(name: str) -> str:
    """Приветствие."""
    return f"Привет, {name}!"
```

Результат:

def greet(name: str) -> str:
    """Приветствие."""
    return f"Привет, {name}!"

Язык можно не указывать — подсветка определится автоматически (guess_lang). Поддерживается любой язык из Pygments: python, javascript, bash, html, css, json, yaml, go, rust и ещё сотни.

Таблицы

| Параметр | Значение | Описание |
| ---: | :---: | :--- |
| Скорость | 100 Мбит/с | Очень быстро |
| Надежность | 99.9% | Стабильно |
| Цена | $0 | Бесплатно |

Списки задач (Task-lists)

- [x] Настроить Django
- [x] Подключить Pygments
- [ ] Добавить поддержку LaTeX
- [x] Реализовать переключение тем

Обычные списки

- обычный пункт
- ещё один пункт
    - вложенный подпункт
- последний пункт

1. сначала
2. потом
3. наконец

Блоки уведомлений (Admonition)

!!! note "Примечание"
    Здесь полезный дополнительный контекст — например, ссылка на документацию.

!!! tip "Совет"
    Используйте admonition, чтобы выделить важные блоки в тексте.

!!! warning "Внимание"
    Обратите внимание на лимиты размеров при загрузке файлов.

!!! danger "Осторожно"
    Не публикуйте ключи и пароли в открытых статьях.

Результат:

Цитаты

> Markdown — это не только про форматирование текста,
> но и про удобство написания.
> — Принцип проектирования

> quotes
>> quotes

Продвинутые расширения

Вкладки (Tabbed)

=== "Python"
    ```python
    print("Hello from Python!")
    ```
=== "JavaScript"
    ```javascript
    console.log("Hello from JS!");
    ```
=== "Bash"
    ```bash
    echo "Hello from Bash!"
    ```

Результат:

print("Hello from Python!")

console.log("Hello from JS!");

echo "Hello from Bash!"

Сворачивающиеся блоки (Details)

??? "Нажми, чтобы узнать секрет"
    Секрет в том, что весь этот текст рендерится с помощью
    `pymdown-extensions`! :sparkles:

Результат:

Математика (MathJax)

Инлайн формула: \( E = mc^2 \)

Блочная формула:

$$ \int_{a}^{b} x^2 \, dx = \frac{b^3 - a^3}{3} $$

Схемы (Mermaid)

```mermaid
graph TD
    Start --> Process
    Process --> End
    End -->|Retry| Process
```

Результат:

graph TD
    Start --> Process
    Process --> End
    End -->|Retry| Process

Списки определений (Definition Lists)

Markdown
:  Язык разметки для создания структурированного текста.

Django
:  Высокоуровневый Python-фреймворк для веб-разработки.

Колонки (Columns)

```columns
**Плюсы**

- Только Markdown-блок
- Адаптивная сетка
- Работает в обеих темах

:::

**Минусы**

- Нужно помнить про разделитель `:::`
- На узких экранах — одна колонка
```

Результат:

Карточки (Cards)

То же самое, но с фоном и рамкой — fence cards:

```cards
**Карточка 1**

- Фон и рамка
- Скруглённые углы

:::

**Карточка 2**

- Тот же разделитель `:::`
- Адаптивная сетка
```

Результат:

Число колонок в ряду

По умолчанию колонки и карточки раскладываются адаптивно. Классы .n-1….n-4 на открывающей строке fence задают точное число колонок или карточек в ряду:

```cards {: .n-3}
**1**

Три карточки
в одном ряду

:::

**2**

Класс `.n-3` —
на fence

:::

**3**

На телефоне —
одна колонка
```

Результат:

То же работает для columns: класс ставится на открывающую строку fence и задаёт число колонок независимо от ширины экрана.

Контейнер (Box)

Fence box — универсальная обёртка: содержимое рендерится как обычный Markdown внутри одного блока, а классы с attr_list вешаются прямо на него. Типовой случай — широкая таблица, которая не должна ломать вёрстку страницы:

```box {: .h-scroll-narrow}
| Модель | Контекст | Цена за 1000 | Режимы |
|--------|----------|--------------|--------|
| gpt-oss-20b | 128K | 0,10 ₽ | sync, batch |
| deepseek-v4-flash | 1M | 0,30 ₽ | sync, async, batch |
| qwen3.6-35b-a3b | 256K | 0,42 ₽ | sync, async, batch |
| yandexgpt-pro-5.1 | 32K | 1,20 ₽ | sync, async |
```

Результат:

На узком экране таблица прокручивается внутри контейнера (класс .h-scroll-narrow), на широком — просто занимает колонку статьи. У box нет фона и рамки — при необходимости добавьте bg-card, border-card или shadow.

Адаптивная видимость

Классы .only-wide и .only-narrow показывают элемент только на широких (≥641px) или только на узких (≤640px) экранах. Классика жанра — две версии одной схемы: горизонтальная для десктопа, вертикальная для телефона; читатель увидит ровно одну:

```mermaid {: .only-wide}
graph LR; A --> B --> C;
```

```mermaid {: .only-narrow}
graph TD; A --> B --> C;
```

Результат:

graph LR; A --> B --> C;

graph TD; A --> B --> C;

Работает на любых элементах с attr_list: картинках, абзацах, обёртках fence-блоков (columns, box, mermaid).

Эмодзи

Мы поддерживаем встроенные эмодзи: :smile: :fire: :heart: :star2:

Атрибуты элементов (Attr List)

Расширение attr_list позволяет добавлять CSS-классы, ID и произвольные атрибуты к элементам.

Инлайн-элементы

Атрибуты ставятся в {} сразу после элемента:

[Ссылка](https://example.com){ .btn .btn-primary }
![Картинка](/media/pic.jpg){ width=50% .rounded }

Блочные элементы

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

Текст абзаца
{.highlight #intro}

Результат: <p class="highlight" id="intro">Текст абзаца</p>.

Заголовки

У заголовков синтаксис чуть другой — через {:}:

### Заголовок {: #my-heading .title }

Результат: <h3 class="title" id="my-heading">Заголовок</h3>.

Полный пример

### Контакты {: #contacts .section-title }

Напишите нам
{.contact-block}

[Написать письмо](mailto:hi@bl0g.ru){ .btn .btn-primary }

Результат:

Контакты

Напишите нам

Написать письмо

Нейтральный инлайн-спан (%%текст%%)

«Голое» слово нельзя покрасить через {} — атрибуты цепляются только к элементу. Для таких случаев есть спан-носитель на двойных процентах:

Обычный текст %%внимание%%{.accent}, а это %%второстепенное%%{.muted}.

Внутри работает обычная разметка (%%**жирный**%%{.info}), непарный %% и проценты вида «50%» остаются обычным текстом, инлайн-код не срабатывает.

Ещё возможности

Горячие клавиши, выделение и индексы

++ctrl+shift+s++ сохраняет изменения.
Вода — H~2~O, степень — x^2^.
==Выделенный фрагмент== привлекает внимание.

Правки (Critic Markup)

При совместной работе удобно показывать изменения:

Вот так выглядит правка целого предложения:

старая формулировка новая формулировка.

Или замена целиком: старая формулировкановая формулировка.

Подсветка инлайн-кода

Нужен язык — просто: `#!python sorted(items, key=lambda x: x.id)`.
Или bash: `#!bash tar -czf backup.tar.gz ./media`.

Списки с буквами и символами

a) первый пункт
b) второй пункт
c) третий пункт

i) римские
ii) тоже работают

Умные символы

(c) 2026 → знак ©, стрелки --> и <--, дробные: 1/2 и 3/4 —
преобразуются автоматически.

Ссылки и якоря

Ссылки работают автоматически: вставьте полный URL — и он станет кликабельным:

Сайт Markdown: https://www.markdownguide.org

Результат: Сайт Markdown: https://www.markdownguide.org

Именованные ссылки — классический синтаксис:

[Документация Django](https://docs.djangoproject.com)

Результат: Документация Django

Ссылки на якоря внутри статьи — заголовки автоматически получают id:

См. раздел [Графики](#графики-vega-lite) ниже.

Сгенерированные id — транслитерация заголовка в нижнем регистре: Заголовок {: #custom-id } задаёт свой id вручную (через Attr List).

Изображения

![Подпись к картинке](/media/pic.jpg)

Результат: ![Подпись](/media/pic.jpg) — полноценный HTML-тег <img> с подписью-ALT.

Размер — через Attr List:

![Широкая картинка](/media/pic.jpg){ width=100% }
![Маленькая иконка](/media/icon.png){ width=48 }

Классы — скругление, тень, рамка:

![Картинка](/media/pic.jpg){ .rounded .shadow }
![Картинка с рамкой](/media/pic.jpg){ .bordered }

Ленивая загрузка — все изображения получают loading="lazy" decoding="async" автоматически (в пайплайне рендера).

Обложки статей — загружаются отдельно при редактировании статьи; пропорция 4:1.

Графики (Vega-Lite)

Блок vega принимает JSON-спеку Vega-Lite v5 и рендерит интерактивный график:

```vega
{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "width": "container", "height": 230,
  "data": {"values": [
    {"x": "A", "y": 10},
    {"x": "B", "y": 25},
    {"x": "C", "y": 18}
  ]},
  "mark": "bar",
  "encoding": {
    "x": {"field": "x", "type": "nominal"},
    "y": {"field": "y", "type": "quantitative"}
  }
}
```

Типы графиков — mark определяет вид:

Слои — несколько графиков в одном блоке:

```vega
{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "width": "container", "height": 240,
  "data": {"values": [
    {"x": 1, "y": 3.1}, {"x": 2, "y": 4.2}, {"x": 3, "y": 5.9}
  ]},
  "layer": [
    {"mark": {"type": "circle", "size": 90},
     "encoding": {
       "x": {"field": "x", "type": "quantitative"},
       "y": {"field": "y", "type": "quantitative"}
     }},
    {"mark": {"type": "line", "color": "#e5534b", "strokeDash": [6, 4]},
     "transform": [{"regression": "y", "on": "x"}],
     "encoding": {
       "x": {"field": "x", "type": "quantitative"},
       "y": {"field": "y", "type": "quantitative"}
     }}
  ]
}
```

Интерактивность — params с bind: "scales":

```vega
{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "width": "container", "height": 260,
  "params": [{"name": "grid", "select": "interval", "bind": "scales"}],
  "data": {"sequence": {"start": 0, "stop": 120, "step": 1, "as": "x"}},
  "transform": [{"calculate": "sin(datum.x/6)*10", "as": "y"}],
  "mark": {"type": "line", "point": true},
  "encoding": {
    "x": {"field": "x", "type": "quantitative"},
    "y": {"field": "y", "type": "quantitative"}
  }
}
```

Такой график можно масштабировать мышью и перетаскивать.