Проблемы конвертации Markdown: таблицы, код и изображения

Ты написал чистый Markdown. Нажал «Конвертировать». А на выходе — каша: таблицы поехали, блоки кода превратились в plain text, картинки пропали, а формулы LaTeX стали обычным текстом.

После того как тысячи пользователей конвертировали Markdown в Word, PDF и HTML через MarkFlow, мы собрали самые частые проблемы и их решения. Здесь 15 реальных проблем с рабочими фиксами — без воды.

Шпаргалка: проблема и решение

---

Проблемы с таблицами

Проблема 1: Колонки таблицы разъехались или слиплись в Word

Что видишь: Аккуратная Markdown-таблица превращается в месиво — колонки слиплись, контент вылез за границы, или структура вообще пропала.

Почему так происходит:

Чаще всего — кривой синтаксис. Таблицы в Markdown на удивление строгие. Один пропущенный пайп или несовпадение в разделительной строке ломает всю таблицу.

Вот типичные ошибки:

<!-- СЛОМАНО: Нет пайпа в начале -->
Header 1 | Header 2
--- | ---
Cell 1 | Cell 2

<!-- СЛОМАНО: Разделитель не совпадает по количеству колонок -->
| Header 1 | Header 2 | Header 3 |
| --- | --- |
| Cell 1 | Cell 2 | Cell 3 |

Как исправить:

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

| Header 1 | Header 2 | Header 3 |
|:---------|:--------:|----------:|
| Left     | Center   | Right     |
| Cell 1   | Cell 2   | Cell 3    |

Основные правила:

• Начинай и заканчивай каждую строку пайпом |
• Разделительная строка должна содержать столько же колонок, сколько в заголовке
• Используй двоеточия для выравнивания — :--- влево, :---: по центру, ---: вправо
• Не пытайся объединять ячейки — стандартный Markdown этого не умеет. Если нужно объединение, делай это вручную в Word после конвертации

Совет: Перед конвертацией вставь таблицу в линтер или Markdown-превью. Большинство редакторов (VS Code, Typora, Obsidian) сразу покажут, если таблица сломана.

---

Проблема 2: Ширина колонок в Word неравномерная

Что видишь: В Markdown-редакторе таблица выглядит нормально, а в Word одна колонка занимает 80% страницы, остальные сжаты в кашу.

Почему так происходит:

Большинство конвертеров Markdown в Word рассчитывают ширину колонки по длине содержимого. Если в одной ячейке длинное предложение или URL, а в остальных — по два слова, распределение получается кривым. В отличие от HTML, в Markdown нет синтаксиса для задания ширины колонок.

Как исправить:

• Держи содержимое ячеек коротким. Длинные описания выноси в сноски или отдельные абзацы под таблицей
• Оформляй длинные URL как ссылки: [Текст ссылки](url) вместо голых URL в ячейках
• Используй MarkFlow — он по умолчанию применяет сбалансированное распределение ширины колонок

Если нужна точная ширина, правь таблицу в Word после конвертации: выдели таблицу, зайди в Свойства таблицы, вкладка Столбец, и задай нужную ширину.

---

Проблема 3: Спецсимволы в ячейках ломают таблицу

Что видишь: Символ пайпа | внутри ячейки ломает структуру колонок, или HTML-сущности рендерятся как сырой текст.

Почему так происходит:

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

Как исправить:

Экранируй пайп обратным слэшем:

| Команда | Описание |
|:--------|:------------|
| `echo "a \| b"` | Перенаправляет вывод через фильтр |
| `status: pass\|fail` | Показывает статус pass или fail |

Для других спецсимволов в ячейках:

• \| для литерального пайпа
• HTML-сущности вроде & для амперсанда, если нужно
• Оберни содержимое в инлайн-код (бэктики), чтобы предотвратить интерпретацию Markdown

---

Проблемы с блоками кода

Проблема 4: Подсветка синтаксиса пропадает после конвертации

Что видишь: Красиво подсвеченный Python или JavaScript превращается в монохромный plain text в Word-документе.

Почему так происходит:

Две типичные причины:

1. Не указан язык — ты использовал тройные бэктики без тега языка
2. Конвертер не поддерживает подсветку — многие базовые конвертеры вырезают подсветку синтаксиса при экспорте в Word/PDF

Разница:

<!-- БЕЗ подсветки — нет тега языка -->
```
function hello() {
  console.log("Hello");
}
```

<!-- С подсветкой — язык указан -->
```javascript
function hello() {
  console.log("Hello");
}
```

Как исправить:

Всегда указывай язык после открывающих тройных бэктиков. Популярные идентификаторы:

Если конвертер всё равно не даёт подсветку, MarkFlow сохраняет подсветку синтаксиса и в Word, и в PDF — код получается с правильными цветами, шрифтом и отступами.

---

Проблема 5: Инлайн-код теряет форматирование

Что видишь: Текст в одинарных бэктиках — config.yaml или npm install — выглядит как обычный текст в сконвертированном документе, без визуального отличия.

Почему так происходит:

Некоторые конвертеры обрабатывают инлайн-код как обычный текст и не применяют стили. Синтаксис бэктиков распознаётся, но выходной формат не включает моноширинный шрифт или фоновый цвет.

Как исправить:

• Используй конвертер, который уважает стили инлайн-кода. MarkFlow рендерит инлайн-код моноширинным шрифтом с фоном в Word
• Избегай вложенных бэктиков в инлайн-коде. Если в коде есть бэктик, используй двойные: `code with `backtick` превращается в ``code with `backtick` ``
• Не злоупотребляй инлайн-кодом для выделения — используй жирный или курсив. Бэктики — для реального кода, команд, имён файлов и технических идентификаторов

---

Проблема 6: Отступы и пробелы в коде поехали

Что видишь: Блоки кода в Word с кривыми отступами — либо всё прижато к левому краю, либо табы превратились в рандомные пробелы.

Почему так происходит:

Конвертация табов в пробелы отличается у разных Markdown-парсеров и рендеринг-движка Word. Некоторые конвертеры вырезают начальные пробелы или схлопывают несколько пробелов в один.

Как исправить:

• Используй пробелы, не табы, в блоках кода. Большинство стайлгайдов рекомендуют 2 или 4 пробела. Табы интерпретируются по-разному в разных конвертерах
• Используй fenced code blocks (тройные бэктики) вместо indented code blocks (4 пробела). Fenced-блоки парсятся надёжнее:

<!-- ПРАВИЛЬНО: Fenced code block -->
```python
def nested():
    if True:
        for i in range(10):
            print(i)
```

<!-- НЕ НАДО: Indented code block (4 пробела) -->
    def nested():
        if True:
            for i in range(10):
                print(i)

• Проверяй результат сразу после конвертации. Если пробелы поехали — проблема в конвертере, а не в твоём Markdown. Попробуй другой инструмент или репортни баг

---

Проблемы с изображениями

Проблема 7: Картинки не отображаются после конвертации

Что видишь: В сконвертированном Word или PDF — сломанные иконки картинок, пустые места или alt-текст вместо самих изображений.

Почему так происходит:

Это жалоба номер один, и почти всегда дело в путях к изображениям:

1. Относительные пути, которые конвертер не может разрезолвить — ![Alt](./images/photo.png) работает в редакторе, потому что он знает, где файл. Конвертер — может и не знать
2. Удалённые URL, требующие авторизации — картинки из приватных репозиториев GitHub, Google Drive или Notion не скачаются при конвертации
3. Проблемы с протоколом — некоторые конвертеры не обрабатывают пути file:// или локальные абсолютные пути
4. Неподдерживаемый формат — часть конвертеров не справляется с SVG, WebP или TIFF

Как исправить:

Самый надёжный подход — публично доступные URL:

<!-- Самый надёжный вариант: абсолютный URL -->
![Architecture diagram](https://your-domain.com/images/diagram.png)

<!-- Тоже надёжно: base64 (для маленьких картинок) -->
![Icon](data:image/png;base64,iVBORw0KGgo...)

В MarkFlow: Перетащи .md-файл вместе с папкой картинок — относительные пути разрезолвятся автоматически. Можно также вставить Markdown с URL картинок — они встроятся в Word-документ.

---

Проблема 8: Картинки слишком большие или слишком маленькие в Word

Что видишь: Изображение, которое идеально смотрится в Markdown-превью, в Word выглядит или крошечным, или огромным, ломая вёрстку страницы.

Почему так происходит:

В Markdown нет нативного синтаксиса для размеров изображений. Формат ![alt](url) не принимает параметры ширины и высоты. Большинство конвертеров вставляют картинки в оригинальных пиксельных размерах, которые могут не соответствовать ширине страницы Word.

Как исправить:

Некоторые диалекты Markdown поддерживают размеры через HTML:

<!-- Управление размером через HTML -->
<img src="./diagram.png" alt="Архитектура системы" width="600" />

Но не все конвертеры Markdown в Word обрабатывают HTML-теги. Варианты:

• Измени размер исходной картинки до примерно 600-800px по ширине перед добавлением в Markdown — это подходит для большинства макетов Word
• Используй HTML-тег img с width, если конвертер поддерживает инлайн-HTML
• Измени размер после конвертации в Word: правый клик по картинке, Размер и положение, задай нужную ширину

Рекомендуемые размеры для Word:

• Полноширинные картинки: 600-800px
• Инлайн-диаграммы: 400-500px
• Иконки и бейджи: 100-200px

---

Проблема 9: Base64-картинки не конвертируются

Что видишь: Картинки, встроенные через data URI в base64, работают в превью, но в сконвертированном документе показываются как битые или полностью пропадают.

Почему так происходит:

Base64-кодирование увеличивает размер файла примерно на 33%. Некоторые конвертеры имеют ограничения на размер инлайн data URI, или просто не парсят формат data:image/...;base64,....

Как исправить:

• Держи base64-картинки маленькими — до 100KB в закодированном виде (примерно 75KB в оригинале). Иконки и мелкие логотипы — ок; скриншоты и фотографии — обычно нет
• Для больших картинок используй файлы. Захости их или положи рядом с .md-файлом
• Проверь документацию конвертера на предмет поддержки data URI. MarkFlow обрабатывает base64-картинки в Word и PDF, но с практическим лимитом около 2MB на картинку

---

Проблемы с LaTeX и диаграммами Mermaid

Проблема 10: Формулы LaTeX отображаются как plain text

Что видишь: Вместо красивой формулы — сырой LaTeX: $E = mc^2$ или $$\int_{0}^{1} x^2 dx$$ в виде обычного текста.

Почему так происходит:

Поддержка математики LaTeX не является частью стандартного Markdown или GFM. Это расширение, которое требует специальных движков рендеринга (KaTeX или MathJax). Большинство базовых конвертеров — включая Pandoc без нужных флагов, VS Code без расширений и Dillinger — не обрабатывают LaTeX-синтаксис.

Как исправить:

Сначала проверь синтаксис:

<!-- Инлайн-формула: одинарные доллары -->
Формула $E = mc^2$ описывает эквивалентность массы и энергии.

<!-- Блочная формула: двойные доллары -->
$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

Затем используй конвертер с поддержкой LaTeX:

Типичные ошибки LaTeX, которые ломают рендеринг:

<!-- НЕПРАВИЛЬНО: Пробел после открывающего $ -->
$ E = mc^2 $

<!-- ПРАВИЛЬНО: Без пробела после $ -->
$E = mc^2$

<!-- НЕПРАВИЛЬНО: Нет закрывающего разделителя -->
$$\int_{0}^{1} x^2 dx

<!-- ПРАВИЛЬНО: Парные разделители -->
$$\int_{0}^{1} x^2 dx$$

---

Проблема 11: Диаграммы Mermaid не отображаются

Что видишь: Вместо красивой блок-схемы или sequence-диаграммы — сырой код Mermaid в виде обычного блока кода.

Почему так происходит:

Mermaid — движок рендеринга на JavaScript. Ему нужен браузер или Node.js-окружение для генерации диаграммы. Большинство конвертеров Markdown в Word обрабатывают Markdown как чистый текст и не исполняют JavaScript, поэтому Mermaid-блоки для них — просто код.

Как исправить:

Проверь синтаксис Mermaid:

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
```

Инструменты с поддержкой Mermaid в Word/PDF:

• MarkFlow — рендерит Mermaid-диаграммы как встроенные изображения в Word
• Typora — рендерит Mermaid в превью и экспортирует в PDF
• Pandoc — нужен плагин mermaid-filter (npm install -g mermaid-filter)

Воркэраунд для конвертеров без Mermaid:

1. Используй Mermaid Live Editor для рендеринга диаграммы
2. Экспортируй в PNG или SVG
3. Замени Mermaid-блок на ссылку на изображение в Markdown
4. Конвертируй как обычно

Это добавляет ручной шаг, но гарантирует, что диаграмма появится в выводе любого конвертера.

---

Проблемы форматирования и структуры

Проблема 12: Уровни заголовков неправильные в Word

Что видишь: Иерархия заголовков в Word не совпадает с Markdown. H2 показываются как H1, или все заголовки одного размера.

Почему так происходит:

Две типичные причины:

1. Несколько H1 в Markdown. Документ должен иметь один H1 (заголовок). Некоторые конвертеры объединяют или переназначают заголовки, если видят несколько H1
2. Конвертер маппит Markdown-заголовки на Word-стили по-своему. Часть инструментов считает первый заголовок заголовком документа независимо от уровня

Как исправить:

Соблюдай правильную иерархию:

# Заголовок документа (H1 — используй ровно один раз)

## Заголовок раздела (H2 — основные разделы)

### Подраздел (H3 — внутри разделов)

#### Деталь (H4 — редко нужен)

• Не пропускай уровни — не прыгай с H2 сразу на H4
• Используй H1 только один раз в начале документа, или пусть конвертер добавит его из метаданных
• Проверь панель стилей в Word — заголовки должны отображаться как «Заголовок 1», «Заголовок 2» и т.д. Если они показаны как «Обычный», конвертер замаппил их некорректно

---

Проблема 13: Вложенные списки теряют вложенность

Что видишь: Тщательно оформленный вложенный список — нумерованный или маркированный — в Word выглядит плоским, все элементы на одном уровне.

Почему так происходит:

Непоследовательные отступы. Markdown требует одинаковых отступов для определения уровней вложенности. Смешение табов и пробелов или 2 пробела в одном месте и 3 в другом сбивает парсер.

Как исправить:

Используй 4 пробела (или 1 таб) на каждый уровень вложенности:

- Первый уровень
    - Второй уровень
        - Третий уровень
    - Снова второй уровень
- Снова первый уровень

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

Типичные ошибки:

<!-- СЛОМАНО: Непоследовательные отступы (2 пробела, потом 3) -->
- Элемент А
  - Под А (2 пробела)
   - Под Б (3 пробела — парсер путается)

<!-- ПРАВИЛЬНО: Стабильные 4 пробела -->
- Элемент А
    - Под А
    - Под Б

Если конвертер всё равно делает списки плоскими, попробуй другой. MarkFlow сохраняет вложенность списков в Word, включая смешанные нумерованные/маркированные списки.

---

Проблема 14: Сноски пропадают или ломаются

Что видишь: Ссылки на сноски вроде [^1] отображаются как обычный текст, а содержимое сноски внизу Markdown-файла либо пропало, либо отрисовано как обычный абзац.

Почему так происходит:

Сноски — расширение GFM, не часть оригинальной спецификации Markdown. Конвертеры, которые поддерживают только базовый Markdown, не обработают синтаксис сносок.

Как исправить:

Правильный синтаксис:

Это утверждение требует источника[^1]. Ещё один момент[^note].

[^1]: Smith, J. (2025). "Research Paper Title." Journal Name.
[^note]: Это длинная сноска с несколькими предложениями.
    Продолжение с отступом в 4 пробела.

Убедись, что:

• Ссылка [^id] и определение [^id]: используют одинаковый идентификатор
• Определения сносок расположены в конце документа (или хотя бы после всех ссылок)
• Конвертер поддерживает сноски GFM — MarkFlow, Pandoc и Typora справляются

---

Проблема 15: Эмодзи отображаются как пустые квадратики

Что видишь: Галочки, ракеты, предупреждения и прочие эмодзи превращаются в пустые прямоугольники или знаки вопроса в Word.

Почему так происходит:

Word-документ использует шрифт без глифов эмодзи. Когда конвертер маппит текст из Markdown в Word, он применяет стандартный шрифт (Calibri, Times New Roman), который может не содержать Unicode-символы эмодзи.

Как исправить:

• После конвертации: Выдели символы эмодзи в Word, смени шрифт на «Segoe UI Emoji» (Windows) или «Apple Color Emoji» (macOS)
• До конвертации: Если отображение эмодзи критично, замени их на текстовые эквиваленты или картинки
• Используй конвертер с поддержкой шрифтов эмодзи: MarkFlow маппит символы эмодзи на подходящий системный шрифт

---

Профилактика: как избежать проблем при конвертации

Большинство проблем можно предотвратить. Встрой эти привычки в свой рабочий процесс.

Валидируй перед конвертацией

Прогони файл через Markdown-линтер, чтобы поймать ошибки синтаксиса до конвертации:

# Установи markdownlint CLI
npm install -g markdownlint-cli

# Проверь файл
markdownlint document.md

Если сидишь в VS Code — поставь расширение «markdownlint» для проверки в реальном времени.

Используй превью, которое соответствует выводу

Превью редактора и вывод конвертера используют разные движки рендеринга. То, что выглядит нормально в VS Code, может сломаться в Word. Всегда делай тестовую конвертацию перед финальным экспортом.

Стандартизируй стиль Markdown

Выбери конвенции и придерживайся их:

• Отступы: 4 пробела для вложенности
• Переводы строк: Одна пустая строка между блоками
• Блоки кода: Всегда fenced (не indented), всегда с тегом языка
• Изображения: Одинаковый формат путей (все относительные или все абсолютные)
• Таблицы: Пайпы в начале и конце каждой строки

Если ты только начинаешь с Markdown, наш гайд по базовому синтаксису покрывает все элементы. Для продвинутых фич вроде сносок и чек-листов — гайд по расширенному синтаксису.

Держи тестовый документ

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

---

Какой конвертер для чего

Разные инструменты решают разные задачи:

---

Часто задаваемые вопросы

В: Почему моя Markdown-таблица ломается при конвертации в Word? О: Чаще всего — кривой синтаксис пайпов: пропущены начальные/концевые пайпы или разделительная строка не совпадает по количеству колонок. Проверь синтаксис таблицы в превью перед конвертацией.

В: Как сохранить подсветку синтаксиса в блоках кода при конвертации в Word? О: Всегда указывай язык после тройных бэктиков (например, ```python). Затем используй конвертер вроде MarkFlow, который сохраняет подсветку в Word.

В: Почему картинки пропали после конвертации Markdown в Word? О: Конвертер не может разрезолвить пути к картинкам. Используй абсолютные URL для удалённых картинок или инструмент вроде MarkFlow, который обрабатывает относительные пути при загрузке .md-файла с папкой картинок.

В: Можно ли сконвертировать формулы LaTeX в Word без потери форматирования? О: Да, но нужен конвертер с поддержкой LaTeX. MarkFlow, Pandoc (с флагами для математики) и Typora рендерят LaTeX корректно. Базовые конвертеры выведут сырой LaTeX как plain text.

В: Почему диаграммы Mermaid показываются как код в сконвертированном документе? О: Большинство конвертеров не исполняют JavaScript, который нужен Mermaid. Используй MarkFlow для автоматического рендеринга или предварительно отрисуй диаграммы как картинки в Mermaid Live Editor.

В: Как исправить отступы вложенных списков в Word? О: Используй ровно 4 пробела на уровень вложенности. Не мешай табы и пробелы. Если проблема не уходит — попробуй другой конвертер, некоторые справляются с вложенными списками лучше.

---

Полезные ссылки

• Конвертер Markdown в Word — Конвертация с полной поддержкой форматирования
• Конвертер Markdown в PDF — PDF, готовый к печати
• Конвертер Markdown в HTML — Чистый семантический HTML
• Базовый синтаксис Markdown — Основы разметки
• Расширенный синтаксис Markdown — Продвинутые фичи и расширения GFM
• Полный гайд: Markdown в Word — Весь процесс конвертации от и до