Markdown в Word через командную строку: гайд по Pandoc

Если нужно конвертировать md в docx через командную строку, ответ — pandoc, и вся работа умещается в одну строку:

pandoc report.md -f gfm -o report.docx

Этой команды хватает для большинства документов. О чём однострочные туториалы молчат — так это о том, где она перестаёт работать; к тому же часть написанного об ограничениях pandoc попросту устарела. Я прогнал pandoc 3.7.0.2 на тестовом документе, набитом таблицами, списками задач, формулами LaTeX и диаграммой Mermaid, а затем распаковал полученный .docx, чтобы посмотреть, что вышло на самом деле. Кое-что меня удивило.

В этом гайде — установка, команды, которые стоит знать, стилизация DOCX, пакетная конвертация и, по итогам того теста, честная карта мест, где pandoc ломается, и ситуаций, когда онлайн-конвертер — решение получше.

👉 К результатам теста | К сравнению CLI и онлайн-конвертера

Установка Pandoc

Pandoc — это один бинарный файл с установщиками под все основные платформы:

• macOS: brew install pandoc
• Windows: winget install --id JohnMacFarlane.Pandoc (или MSI-установщик)
• Debian/Ubuntu: sudo apt install pandoc

Одно предостережение, прежде чем доверять старому системному пакету: репозитории дистрибутивов нередко поставляют версии pandoc с отставанием в годы. Ubuntu LTS долго распространяла 2.x, тогда как актуальная линейка релизов — 3.x, и, как вы увидите ниже, возраст версии влияет на то, что конвертируется чисто. Проверьте свою командой pandoc --version.

Базовая конвертация: разбор

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

pandoc report.md -f gfm -o report.docx --toc

Почему -f gfm, а не диалект Markdown, который у pandoc по умолчанию? Потому что Markdown, который сегодня пишет большинство — в README на GitHub, в ответах ChatGPT и Claude, в экспортах из Notion, — это GFM. Диалект pandoc по умолчанию более академичный: он включает сноски и цитирование источников, но некоторые конструкции трактует иначе. Если исходник пришёл от ИИ-ассистента или инструмента разработчика, gfm — более надёжный вариант ридера.

Замечание о формулах: с ридером GFM конструкции $...$ и $$...$$ в актуальном pandoc просто работают. Формулы становятся нативными уравнениями Word, а не картинками. К этому вернёмся ниже, потому что это самое перевираемое в интернете поведение pandoc.

Стилизация результата через reference document

DOCX, созданный pandoc, открывается в Word с безликим оформлением. Если документ должен соответствовать корпоративному шаблону, флагами это не чинится — нужен reference document.

Процесс состоит из трёх шагов:

1. Сгенерируйте стандартный шаблон pandoc как отправную точку:

   pandoc -o custom-reference.docx --print-default-data-file reference.docx
   

2. Откройте custom-reference.docx в Word и отредактируйте именно стили — Heading 1, Normal, Table, блоки кода. Текстовое содержимое этого файла игнорируется; переносятся только стили и параметры страницы.

3. Конвертируйте с применением шаблона:

   pandoc report.md -f gfm --reference-doc=custom-reference.docx -o report.docx
   

В руководстве pandoc описано, какие имена стилей учитываются. Ментальная модель, с которой всё встаёт на место: вы не оформляете документ — вы один раз обучаете pandoc стилям Word вашей организации, а затем переиспользуете их при каждой конвертации.

Пакетная конвертация нескольких файлов

Вот где командная строка действительно обходит любой веб-инструмент. Конвертация целой папки:

Bash (macOS/Linux):

for f in docs/*.md; do
  pandoc "$f" -f gfm -o "${f%.md}.docx"
done

PowerShell (Windows):

Get-ChildItem docs -Filter *.md | ForEach-Object {
  pandoc $_.FullName -f gfm -o ($_.FullName -replace '\.md$', '.docx')
}

А поскольку pandoc — единственная зависимость, он встраивается в CI без лишних церемоний. Шаг GitHub Actions, который пересобирает Word-копии документации при каждом пуше, выглядит так:

- uses: pandoc/actions/setup@v1
- run: |
    for f in docs/*.md; do
      pandoc "$f" -f gfm --reference-doc=brand.docx -o "out/$(basename "${f%.md}").docx"
    done

Команды используют этот приём, чтобы держать Word-зеркало Markdown-вики для комплаенс-ревью или клиентских поставок. Если один и тот же набор файлов вы конвертируете больше двух раз, скрипт окупается сразу.

Где Pandoc упирается в ограничения (тест на 3.7)

Вот тест, который я провёл. Один Markdown-файл с таблицей, списком задач, строчной формулой ($E = mc^2$), многострочным выключным уравнением, флоучартом Mermaid и alert-блоком GFM. Конвертация в pandoc 3.7.0.2, затем распаковка .docx и чтение word/document.xml напрямую. Три вывода.

Формулы работают лучше, чем принято считать

XML документа содержит два блока <m:oMath> — по одному на каждое уравнение. Это OMML, родной формат уравнений Word. Оба уравнения полностью редактируются в редакторе формул Word, отображаются с типографским качеством и переживают копирование в другие документы Office.

Это опровергает утверждение, которое до сих пор встречается в старых туториалах (а до недавнего времени — и в одном из наших собственных гайдов): будто сложный LaTeX растрируется в картинки. В актуальном pandoc — нет. Стандартная математика LaTeX — дроби, суммы, греческие буквы, нижние индексы — из коробки превращается в нативные уравнения.

Честная граница: pandoc понимает стандартный математический синтаксис LaTeX, а не произвольный LaTeX. Пользовательские макросы \newcommand, рисунки TikZ и окружения, зависящие от пакетов, дорогу не переживут. И если ваш дистрибутив поставил pandoc 2.x, поведение будет другим — проверьте pandoc --version, прежде чем винить инструмент.

Mermaid — вот настоящая точка слома

Флоучарт Mermaid диаграммой не стал. Он прошёл насквозь как дословный моноширинный текст — сырой исходник flowchart LR, оформленный как блок кода. В XML документа — ноль графических объектов.

Сегодня это важнее, чем пять лет назад, потому что ИИ-ассистенты обожают Mermaid. Попросите у ChatGPT или Claude обзор архитектуры — и с большой вероятностью в ответе окажется код-блок mermaid. Конвертируйте такую переписку через pandoc, и в документе Word останется нечто похожее на забытый исходный код. Если это ваш сценарий, наш гайд по экспорту ответов ChatGPT в Word разбирает специфику работы с ИИ.

CLI-решение существует: mermaid-filter — фильтр pandoc, который рендерит диаграммы прямо при конвертации. Он работает, но взвесьте затраты на настройку честно: это npm-пакет, который тянет за собой headless-Chromium через Puppeteer, а вызов превращается в pandoc -F mermaid-filter .... Для документационного конвейера, конвертирующего диаграммы ежедневно, эти затраты окупаются. Для одного отчёта со сдачей сегодня после обеда — это крюк.

Мелкие потери точности по краям

Ещё два наблюдения потише из того же теста. Alert-блоки GFM (> [!NOTE]) сохраняют текст, но теряют цветное оформление выноски — в Word они читаются как обычные цитаты. А пункты списков задач приходят простым текстом списка, а не чекбоксами Word. Ни то ни другое документ не ломает; и то и другое сплющивает форматирование, которое автор, скорее всего, выбирал сознательно. Если ваша конвертация ломается иначе, частые сценарии сбоев мы собрали в статье типичные проблемы конвертации Markdown.

Командная строка или онлайн-конвертер?

После всех этих тестов вот система принятия решения, которой я бы действительно пользовался:

Оба пути легитимны. Pandoc заслуженно занимает место в любом регулярном конвейере. А для разового «мне нужен .docx в ближайшие пять минут» — особенно когда замешан Mermaid — бесплатный онлайн-конвертер Markdown в Word выдаст чистый документ с уравнениями и отрисованными диаграммами, и ставить ничего не придётся.

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

В: Можно ли конвертировать Markdown в Word, ничего не устанавливая?
О: Из командной строки — нет: pandoc требует установки. Если установка ПО не вариант, практичный путь — браузерные конвертеры; конвертация выполняется на сервере, а вы скачиваете готовый .docx.

В: Конвертирует ли pandoc математику LaTeX в настоящие уравнения Word?
О: Да. В моём тесте с Pandoc 3.7.0.2 и строчные, и выключные формулы стали нативными уравнениями OMML, редактируемыми в редакторе формул Word. Исключения — очень старые версии pandoc и пользовательские макросы LaTeX.

В: Почему моя диаграмма Mermaid отображается в Word как код?
О: Pandoc воспринимает код-блок mermaid как обычный код — диаграммы он не рендерит. Либо добавьте в конвейер mermaid-filter (нужен Node.js), либо используйте конвертер со встроенным рендерингом Mermaid.

В: Как сохранить корпоративные шрифты и стили заголовков?
О: Используйте --reference-doc=template.docx. Один раз отредактируйте стили в этом шаблоне в Word — pandoc будет применять их при каждой конвертации. Содержимое шаблона игнорируется, переносятся только стили.

В: В чём разница между -f markdown и -f gfm?
О: markdown — собственный расширенный диалект pandoc (сноски, цитирование источников); gfm соответствует тому, что выдают GitHub, ChatGPT и большинство современных инструментов — таблицы, списки задач, зачёркивание. Для Markdown от ИИ или из инструментов разработки gfm даёт меньше сюрпризов.

В: Может ли pandoc конвертировать Word обратно в Markdown?
О: Да — поменяйте аргументы местами: pandoc report.docx -o report.md. При обратном преобразовании теряется часть специфичного для Word форматирования (текстовые поля, комментарии), так что относитесь к нему как к переносу контента, а не как к циклу без потерь.

Связанные ресурсы

• Полное руководство по конвертации Markdown в Word: весь ландшафт вариантов конвертации за пределами командной строки
• ChatGPT в Word: Markdown-процесс для документов, созданных ИИ
• Markdown в PDF: когда на выходе нужен PDF
• Типичные проблемы конвертации Markdown: решения для сломанных таблиц, проблем с кодировкой и поехавшего форматирования

Заключение

Pandoc остаётся правильным ответом на вопрос «как перевести Markdown в Word через командную строку»: одна команда для отдельного файла, короткий скрипт для папки, --reference-doc для корпоративных стилей. В моём тесте с Pandoc 3.7 поддержка формул оказалась лучше своей репутации: стандартный LaTeX превращается в настоящие, редактируемые уравнения Word.

Его подлинный пробел — визуальный: диаграммы Mermaid приходят исходным кодом, если не прикрутить цепочку фильтров на Node. Так что выбирайте по рабочему процессу. Регулярный конвейер с чисто текстовыми документами — скриптуйте через pandoc. Один документ с диаграммами и дедлайном — конвертируйте в браузере и сохраните уравнения и флоучарты в целости.

Источники

• Pandoc User's Guide — официальное руководство: ридеры, райтеры, --reference-doc, обработка формул
• Installing pandoc — официальные установщики для всех платформ
• mermaid-filter — фильтр pandoc от сообщества для рендеринга диаграмм Mermaid
• pandoc/actions — официальные GitHub Actions для pandoc в CI