Советы по форматированию Markdown для профессиональных PDF

Правильно отформатированный Markdown создаёт правильно отформатированные PDF. Это руководство охватывает методы, которые оказывают наибольшее влияние на конечный результат — от структуры заголовков до оформления таблиц и стилизации блоков кода.

Иерархия заголовков имеет значение

Структура ваших заголовков определяет план документа. Используйте логическую иерархию:

# Заголовок документа (h1)
## Основной раздел (h2)
### Подраздел (h3)
#### Уровень детализации (h4)

Советы:

Один h1 на документ — он становится заголовком PDF.
Используйте h2 для основных разделов (Введение, Методы, Результаты, Заключение).
Используйте h3 для подразделов внутри каждого раздела.
Избегайте пропуска уровней (h2 → h4 без h3).

Шаблон Legal автоматически нумерует разделы верхнего уровня, поэтому чёткая иерархия заголовков делает эту нумерацию осмысленной. В любом шаблоне логичная иерархия создаёт более понятную структуру документа.

Таблицы, которые выглядят отлично

Таблицы — одна из самых мощных функций. Вот как заставить их хорошо работать в PDF:

| Проект | Статус | Бюджет | Руководитель |
| --- | --- | --- | --- |
| Редизайн сайта | В процессе | 45 000 ₽ | Анна |
| Мобильное приложение | Планирование | 30 000 ₽ | Иван |
| Миграция API | Завершено | 15 000 ₽ | Мария |

Выравнивание столбцов

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

| Товар | Кол-во | Цена |
| :--- | ---: | :---: |
| Выравнивание влево | Выравнивание вправо | По центру |
| Виджет | 5 | 2 400 ₽ |
| Услуга | 12 | 12 000 ₽ |

:--- — выравнивание влево (по умолчанию)
---: — выравнивание вправо (хорошо для чисел)
:---: — выравнивание по центру

Экранирование символа вертикальной черты

Если содержимое ячейки содержит |, экранируйте его обратной косой чертой:

| Команда | Описание |
| --- | --- |
| `cat file \| grep error` | Поиск ошибок в журналах |

Советы:

Делайте заголовки столбцов короткими: длинные заголовки создают широкие столбцы, которые могут переполняться.
Ограничьтесь 4–5 столбцами: большее количество столбцов становится трудно читать на бумаге A4/Letter.
Предварительный просмотр перед экспортом: для широких таблиц могут потребоваться более короткие заголовки.

Блоки кода с подсветкой синтаксиса

Оборачивайте код в тройные обратные кавычки с тегом языка. PDF автоматически применит подсветку синтаксиса.

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

```python
def calculate_growth(revenue: list[float]) -> float:
    if len(revenue) < 2:
        return 0.0
    return (revenue[-1] - revenue[-2]) / revenue[-2] * 100
```

Распространённые языки

Язык	Тег
Python	`python`
JavaScript	`javascript`
TypeScript	`typescript`
Bash / Shell	`bash`
SQL	`sql`
JSON	`json`
YAML	`yaml`
HTML	`html`
CSS	`css`
Rust	`rust`
Go	`go`
Java	`java`
C++	`cpp`

Пример: JSON-конфигурация

```json
{
  "name": "quarterly-report",
  "templateId": "executive",
  "options": {
    "pageNumbers": true
  }
}
```

Пример: Команды Shell

```bash
curl -X POST https://api.example.com/v1/reports \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"period": "Q3", "format": "pdf"}'
```

Советы:

Всегда указывайте тег языка — без него подсветка не работает.
Используйте строчные `код` кавычки для коротких ссылок, таких как имя_файла или true.
Держите блоки короче 50 строк для чистой разбивки на страницы.

Изображения в ваших PDF

![Логотип компании](https://example.com/logo.png)

Требования:

Изображения должны быть общедоступными URL (не локальными файлами).
Поддерживаемые форматы: PNG, JPEG, WebP.
Изображения автоматически масштабируются по ширине страницы.

Советы:

Для логотипов в пользовательских шаблонах используйте функцию загрузки изображений вместо изображений Markdown.
Держите изображения меньше 2 МБ для быстрой визуализации.
Используйте описательный альтернативный текст — он отображается, если изображение не загружается.

Цитаты для выделения

> **Ключевой вывод**: Выручка выросла на 15% по сравнению с прошлым годом, превысив наш прогноз на третий квартал на 3 процентных пункта.

Цитаты отображаются с левой границей и отступом. Используйте их для:

Ключевых выводов или результатов
Цитат клиентов или отзывов
Важных заметок или предупреждений
Выдержек из внешних источников

Списки — маркированные и нумерованные

### Ключевые результаты

- Маркетинговый план на Q4
  - Календарь социальных сетей
  - График кампаний по email
- Распределение бюджета
  - Разбивка по отделам
  - Резервный фонд

### Действия

1. Проверить черновик с заинтересованными сторонами
2. Внести правки до пятницы
3. Отправить финальную версию на утверждение
4. Архивировать предыдущие версии

Советы:

Используйте маркированные списки для неупорядоченных элементов.
Используйте нумерованные списки для последовательных шагов.
Вкладывайте списки до 3 уровней глубины.
Оставляйте пустую строку до и после списков для правильного интервала.

Ссылки и сноски

Подробнее см. в [документации API](https://markdowntopdfconverter.com/api-docs).

По вопросам обращайтесь по адресу [support@markdowntopdfconverter.com](mailto:support@markdowntopdfconverter.com).

Ссылки кликабельны в PDF. Используйте описательный текст ссылок — избегайте «нажмите здесь».

Диаграммы Mermaid

Добавляйте диаграммы прямо в Markdown с помощью синтаксиса Mermaid. Они отображаются в виде чёткой векторной графики в PDF. Для отображения Mermaid требуется премиум-план.

Каждая диаграмма начинается с ```mermaid и ключевого слова типа на следующей строке.

Блок-схема

Показывайте процессы, решения и рабочие процессы.

```mermaid
graph TD
    A[Start] --> B{Is approved?}
    B -->|Yes| C[Publish]
    B -->|No| D[Revise]
    D --> B
    C --> E[Done]
```

Ключевые моменты: graph TD = сверху вниз. Используйте LR для направления слева направо. [] = прямоугольник, () = скруглённый, {} = ромб, --> = стрелка, -->|метка| = стрелка с меткой.

Диаграмма последовательности

Показывайте взаимодействие между участниками во времени.

```mermaid
sequenceDiagram
    Client->>Server: POST /api/convert
    Server->>Gotenberg: Render PDF
    Gotenberg-->>Server: PDF binary
    Server-->>Client: 200 OK (PDF)
```

Ключевые моменты: ->> = сплошная стрелка, -->> = пунктирный ответ. Участники создаются автоматически из имён.

Диаграмма Ганта

Планируйте проекты с временными шкалами.

```mermaid
gantt
    title Q3 Launch
    dateFormat  YYYY-MM-DD
    section Design
    Wireframes    :2026-07-01, 7d
    Prototype     :2026-07-08, 5d
    section Build
    Frontend      :2026-07-13, 10d
    Backend       :2026-07-13, 12d
    section Launch
    QA            :2026-07-25, 4d
    Go Live       :milestone, 2026-07-30, 0d
```

Ключевые моменты: section группирует задачи. Формат: ИмяЗадачи :начало, длительность. milestone отмечает одну дату.

Круговая диаграмма

Простые пропорциональные данные.

```mermaid
pie title Revenue by Region
    "North America" : 45
    "Europe" : 30
    "APAC" : 25
```

Диаграмма классов

Показывайте отношения объектов для технической документации.

```mermaid
classDiagram
    User <|-- Admin
    User : +String email
    User : +login()
    Admin : +manageUsers()
    Report *-- User
    Report : +String title
    Report : +generatePdf()
```

Ключевые моменты: <|-- = наследование, *-- = композиция. + = публичный метод/поле.

Дополнительные типы

Также поддерживаются: диаграммы состояний, диаграммы сущность-связь, карты путешествий, git-графы и квадрантные диаграммы. Полный справочник синтаксиса на mermaid.js.org.

Советы:

Mermaid отображается как SVG — остаётся чётким при любом увеличении.
Используйте шаблон Creative для документов с большим количеством диаграмм (он предварительно задаёт размеры контейнеров диаграмм).
Диаграммы автоматически подстраиваются под ширину страницы. Делайте подписи узлов краткими, чтобы избежать переполнения.
Тестируйте сложные диаграммы в предварительном просмотре перед экспортом.

Контрольный список структуры документа

Перед экспортом проверьте:

Один заголовок h1 в начале
Логическая иерархия заголовков (h1 → h2 → h3)
Таблицы имеют одинаковое количество столбцов
Блоки кода имеют метки языка
Изображения имеют описательный альтернативный текст
Ссылки используют описательный текст
Списки имеют пустые строки до и после
Нет HTML-тегов (используйте чистый Markdown)

Следующие шаги

Попробуйте эти техники в конвертере с предварительным просмотром.
Узнайте, как создать пользовательский шаблон, использующий типографику вашего бренда.
Сравните все девять встроенных шаблонов, чтобы найти подходящий для вашего контента.