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

Pandoc - самый мощный инструмент преобразования документов. Он конвертирует между десятками форматов, включая .docx в Markdown, и дает вам тонкий контроль над выходом. Это руководство охватывает все, что вам нужно использовать Pandoc для Word до Markdown преобразование.

Что такое Pandoc?

Pandoc - это бесплатный инструмент командной строки с открытым исходным кодом, который конвертирует документы между форматами. Он поддерживает более 40 форм ввода и вывода. Для преобразования Word в Markdown Pandoc является золотым стандартом более конфигурируемым, чем любой инструмент на основе браузера, включая WordToMD.

Когда использовать Pandoc против __П_А__:

Установка Pandoc

Окна

Загрузить программу установки с pandoc.org/установка.html, или используйте менеджер пакетов:

# Winget
winget install pandoc

# Chocolatey
choco install pandoc

# Scoop
scoop install pandoc

macOS (англ. macOS)

# Homebrew
brew install pandoc

# MacPorts
sudo port install pandoc

Линукс

# Ubuntu/Debian
sudo apt-get install pandoc

# Fedora
sudo dnf install pandoc

# Arch
sudo pacman -S pandoc

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

pandoc --version

Основная команда преобразования

pandoc document.docx -o output.md

Вот и всё. Pandoc выводит формат ввода из .docx и формат вывода из .md.

Более точная версия:

pandoc -f docx -t markdown document.docx -o output.md

Формат вывода

Pandoc предлагает несколько вариантов Markdown в качестве вывода:

# GitHub Flavored Markdown (GFM)
pandoc document.docx -t gfm -o output.md

# CommonMark
pandoc document.docx -t commonmark -o output.md

# Pandoc's extended Markdown (most features)
pandoc document.docx -t markdown -o output.md

# Standard Markdown (basic)
pandoc document.docx -t markdown_strict -o output.md

GFM рекомендуется для большинства случаев использования (GitHub, Obsidian, GitBook, Notion).

Полезные варианты конвертации

Извлечение медиафайлов

Изображения, встроенные в .docx, извлекаются из каталога:

pandoc document.docx --extract-media=./media -o output.md

Это сохраняет изображения в ./media/ и добавляет Markdown ссылки на изображение в выход.

Линии упаковки

Окрутка линии управления в выходе:

# No wrapping (one paragraph = one line)
pandoc document.docx --wrap=none -o output.md

# Wrap at 80 characters
pandoc document.docx --wrap=auto --columns=80 -o output.md

--wrap=none Рекомендуется для Markdown, который будет контролироваться версиями он производит более чистые Git-диффоны.

Содержание

pandoc document.docx --toc -o output.md

Самостоятельный документ с метаданными

pandoc document.docx -s -o output.md

В связи с -s (самостоятельный) флаг генерирует YAML-фронтмат из метаданных документа.

Преобразование партий

Конвертировать все файлы .docx в каталоге:

Windows PowerShell (с помощью программного обеспечения)

Get-ChildItem -Filter "*.docx" | ForEach-Object {
    $output = [System.IO.Path]::ChangeExtension($_.Name, ".md")
    pandoc $_.FullName -t gfm --wrap=none -o $output
    Write-Host "Converted: $($_.Name) → $output"
}

Bash (macOS/Linux)

for file in *.docx; do
    output="${file%.docx}.md"
    pandoc "$file" -t gfm --wrap=none -o "$output"
    echo "Converted: $file → $output"
done

Для получения дополнительных вариантов конвертации партий см. Перевод партии Word на Markdown.

Настройка выхода с помощью фильтров Lua

Pandoc поддерживает фильтры Lua, которые преобразуют документ AST во время преобразования:

pandoc document.docx --lua-filter=my-filter.lua -o output.md

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

-- add-frontmatter.lua
function Meta(meta)
  meta.draft = false
  meta.author = "WordToMD Team"
  return meta
end

Это тип настройки, который инструменты браузера не могут сравнить.

Сравнение Pandoc и мамонта.js Выпуск

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

Для сложных документов Pandoc дает более полный выход. Для простых документов WordToMD быстрее с нулевой настройкой.

Pandoc Файлы по умолчанию

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

# my-defaults.yaml
from: docx
to: gfm
wrap: none
extract-media: ./media
standalone: true

Тогда беги:

pandoc document.docx -d my-defaults.yaml -o output.md

Использование Pandoc в CI/CD

Для автоматизированных трубопроводов (GitHub действия и т.д.):

# .github/workflows/convert-docs.yml
- name: Install Pandoc
  run: sudo apt-get install pandoc

- name: Convert Word docs to Markdown
  run: |
    for f in docs/*.docx; do
      pandoc "$f" -t gfm --wrap=none -o "${f%.docx}.md"
    done

FAQ

Выходы Pandoc \ Продолжение строки в моем Markdown. Как их удалить? Добавить --wrap=none чтобы отключить обертывание.

Мои таблицы выглядят искаженными в выходе Pandoc. Попробуй . -t gfm для синтаксиса таблицы GFM вместо таблиц Pandoc Markdown по умолчанию.

Изображения не появляются в выходе. Добавить --extract-media=./images для извлечения встроенных изображений. Затем ссылайтесь на них правильно в вашей целевой среде.

Pandoc преобразует умные цитаты в " Как мне их сохранить? Добавить --no-highlight или изменять шаблон. Для умных котировок в частности, они должны быть сохранены по умолчанию в большинстве форм вывода.

Как Pandoc и WordToMD сравниваются для DOCX с Markdown? Оба хорошо работают для стандартных документов. WordToMD требует нулевой настройки и производит чистый выход GFM. Pandoc требует установки, но обрабатывает сложные документы (изображения, математику, комментарии, примечания) более полно.

Заключение

Pandoc является наиболее способным инструментом для Word в Markdown преобразование, особенно для серийной обработки, настраиваемых форм вывода и трубопроводов CI/CD. Для быстрых одноразовых преобразований без установки, WordToMD выполняет работу мгновенно. Эти два инструмента хорошо дополняют друг друга.