Как конвертировать Word в Markdown (и обратно) с помощью Python⁠⁠

При написании, управлении технической документацией и создании базы знаний мы чаще всего сталкиваемся с двумя форматами документов: Word и Markdown. Word благодаря мощным возможностям верстки и зрелым функциям совместного рецензирования доминирует в корпоративной офисной работе и в официальных отчетах; в то же время Markdown — благодаря простому тексту, легковесности и удобству контроля версий — очень любят программисты и технические писатели.

Однако «барьер формата» между ними часто вызывает головную боль: нужно ли вручную копировать, вставлять и подгонять оформление абзац за абзацем? Конечно же, нет. В этой статье будет подробно рассказано, как использовать Free Spire.Doc в среде Python, чтобы эффективно выполнять двунаправленную конвертацию между Word и Markdown.

Почему стоит выбрать Free Spire.Doc?

На рынке есть множество библиотек для обработки документов, но Spire.Doc особенно хорошо справляется с преобразованием между Word и Markdown. Она не только корректно обрабатывает базовый текст, но и отлично распознает и конвертирует сложные структуры — такие как заголовки, абзацы, таблицы и списки. Более того, она поддерживает оба формата Word: .doc и .docx, а также стандартный синтаксис Markdown. Конвертированные документы аккуратно отформатированы и логично структурированы, требуя почти никаких дополнительных правок.

Установка библиотеки Spire.Doc:

pip install spire.doc.free

Word → Markdown: всего три строки ключевого кода

from spire.doc import *

from spire.doc.common import *

# Создаем объект Document

document = Document()

# Загружаем Word-файл (поддерживает .docx и .doc)

document.LoadFromFile("input.docx")

# Сохраняем как файл Markdown

document.SaveToFile("WordToMarkdown.md", FileFormat.Markdown)

document.Close()

После выполнения кода все уровни заголовков в документе Word автоматически сопоставляются с тегами Markdown #–######, абзацы сохраняют корректные переносы строк, таблицы конвертируются в синтаксис таблиц Markdown, а упорядоченные/неупорядоченные списки распознаются правильно. Весь процесс занимает всего несколько секунд, значительно повышая эффективность работы.

Markdown → Word: так же просто

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

from spire.doc import *

from spire.doc.common import *

document = Document()

# Загружаем файл Markdown

document.LoadFromFile("input.md")

# Сохраняем как документ Word (поддерживает .docx и .doc)

document.SaveToFile("MdToDocx.docx", FileFormat.Docx)

# Если нужен старый формат .doc, можно сохранить отдельно

# document.SaveToFile("MdToDoc.doc", FileFormat.Doc)

document.Close()

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

Обработка изображений: проблема встраивания Base64 и решения

При конвертации Word в Markdown есть легко упускаемая из виду проблема: обработка изображений . По умолчанию Spire.Doc конвертирует встраиваемые изображения в Word в кодировку Base64 и напрямую встраивает их в файл Markdown. Плюс этого подхода в том, что один файл становится самодостаточным — им удобно делиться.

Но минус также очевиден: если документ содержит много высокоразрешенных изображений, размер Markdown-файла может резко увеличиться, достигнув десятков или даже сотен мегабайт. Это приводит к лагам в редакторе и раздувает Git-репозитории.

Решение оптимизации: извлечь изображение для внешних ссылок

Лучше извлечь изображения в отдельную папку, а затем ссылаться на них в Markdown через относительные пути. Хотя Spire.Doc напрямую не предоставляет параметр «автоматически внешнее вынесение ссылок на изображения при сохранении», мы можем решить задачу вручную: извлечь изображения и заменить ссылки.

from spire.doc import *

import os

document = Document()

document.LoadFromFile("input.docx")

# Создаем директорию для изображений

image_dir = "images"

os.makedirs(image_dir, exist_ok=True)

# Проходим по всем изображениям и извлекаем их

for i, image inenumerate(document.Images):

withopen(f"{image_dir}/img_{i}.png", "wb") as f:

f.write(image.ImageData)

# Сначала конвертируем в Markdown (все еще со встроенными Base64)

document.SaveToFile("temp.md", FileFormat.Markdown)

# Далее с помощью regex или замены строк заменяем Base64-изображения на локальные ссылки

# Этот шаг нужно выполнить вручную или с помощью дополнительного скрипта

document.Close()

Если документов много, процесс можно полностью автоматизировать: распарсить сгенерированный Markdown-файл, найти блоки Base64-изображений, декодировать их и сохранить локально, затем заменить на формат . Коллекция document.Images в Spire.Doc дает нам возможность извлекать изображения, и в сочетании со скриптингом можно добиться полной автоматизации этой оптимизации.

Практические сценарии применения

Это решение было проверено в нескольких реальных ситуациях:

1. Миграция технической документации : пакетно конвертировать существующие руководства по продуктам в формате Word в Markdown для импорта в VuePress или Docsify базы знаний.

2. Публикации в нескольких форматах : писать в Markdown и конвертировать в Word, чтобы соответствовать требованиям клиента или руководителя к официальным документам.

3. Совместный обзор : команда просматривает изменения в режиме Word «Отслеживание изменений», затем возвращает обратно в Markdown одним кликом, чтобы продолжить разработку.

Итоги

С библиотекой Spire.Doc разработчики на Python могут выполнять двунаправленную конвертацию между Word и Markdown всего несколькими строками кода, при этом полностью сохраняя ключевые структуры — заголовки, абзацы, таблицы и списки. Для документов с большим числом изображений объединение извлечения изображений с решениями для внешних ссылок позволяет эффективно контролировать размер файлов и улучшать опыт управления документами. Если вы часто переключаетесь между этими форматами, попробуйте это решение — и попрощайтесь с утомительной ручной версткой.