Converting Word Documents to Markdown Using Python

Markdown stores content as plain text with lightweight structural markup. It renders on a wide range of documentation platforms and can equally be processed as ordinary text. When existing documents need to feed a documentation site, a static blog, a code repository, or a corpus for a large language model, Markdown is often a better intermediate format than Word: it is easier to version, easier to search in bulk, and does not depend on a particular application to open.

The difficulty is that a large amount of existing material is in .docx format. Opening each file by hand, copying the content, and re-formatting it as Markdown is slow, and with dozens or hundreds of files it barely moves forward.

Using Spire.Doc for Python, this article covers converting Word documents to Markdown, along with the related operations of PDF-to-Markdown conversion and batch processing, both of which also produce plain text. Every output in this workflow is a text file, so the result can be checked in a text editor.

Setting Up the Environment

Install the Spire.Doc library:

pip install Spire.Doc

Then import the required modules in your script:

from spire.doc import *
from spire.doc.common import *

Converting a Word Document to Markdown

The core operation takes two steps: load the document, then save it with FileFormat.Markdown.

doc = Document()

# Load a Word document
doc.LoadFromFile("Data/ToMarkdown.docx")

# Convert to Markdown format
doc.SaveToFile("ToMarkdown_output.md", FileFormat.Markdown)

doc.Close()

The FileFormat enum determines the output format; set it to Markdown to produce an .md file. Paragraphs are converted into their corresponding Markdown structures, headings map to # levels, and body text stays as ordinary paragraphs.

The same Document object can also be saved to other formats as needed, for example producing a docx and a PDF in the same run:

doc.SaveToFile("output.docx", FileFormat.Docx)
doc.SaveToFile("output.pdf", FileFormat.PDF)

The reverse direction works too: a Markdown file can be loaded and saved as another format, and LoadFromFile() recognizes the .md extension automatically.

doc.LoadFromFile("Data/FromMarkdown.md")
doc.SaveToFile("FromMarkdown_docx.docx", FileFormat.Docx)

One thing worth noting here: the output is plain text, so checking the result needs no Word or image viewer. Opening the .md file in a text editor is enough, and it also makes line-by-line diffing in version control straightforward.

Converting a PDF Document to Markdown

Alongside Word, a large share of existing material is PDF. PDF conversion goes through a different interface: construct a PdfToMarkdownConverter with the source file path, then call ConvertToMarkdown() to write the output.

from spire.pdf import *

inputFile = "DeleteImage.pdf"
outputFile = "out2.md"

# Create a converter with the input PDF file
converter = PdfToMarkdownConverter(inputFile)

# Convert the PDF content to Markdown and save it
converter.ConvertToMarkdown(outputFile)

Conversion behavior is adjusted through the MarkdownOptions property. If only the text matters and the images in the PDF do not need to be processed, set IgnoreImage to True to skip them:

converter = PdfToMarkdownConverter(inputFile)

# Skip processing images in the PDF
converter.MarkdownOptions.IgnoreImage = True

converter.ConvertToMarkdown(outputFile)

For text-heavy material, skipping images often yields cleaner output and shortens the conversion.

Converting Documents in Batch

Once single-file conversion is wrapped in a function, batch processing is just a loop. The following example walks every .docx file in a directory and converts each to a .md file of the same name:

import os

input_folder = "documents"
output_folder = "markdown"

for filename in os.listdir(input_folder):
    if not filename.lower().endswith(".docx"):
        continue

    doc = Document()
    doc.LoadFromFile(os.path.join(input_folder, filename))

    md_name = os.path.splitext(filename)[0] + ".md"
    doc.SaveToFile(os.path.join(output_folder, md_name), FileFormat.Markdown)
    doc.Close()

Keeping the output filename identical to the input (only the extension changes) makes the source easy to trace and lets later steps match files by name.

Practical Tips

• Markdown has limited expressive power. Elements such as text boxes, multi-column layouts, headers and footers, and complex table styling have no native syntax in Markdown, so they may be dropped or degraded into ordinary paragraphs after conversion. Run a representative document through first to confirm how the content you care about survives.
• Verify the output programmatically. Because the result is plain text, a script can check whether a file is empty, whether heading levels are correct, and whether key paragraphs are present — far more reliable than reading each file by hand.
• For PDF-to-Markdown conversion, whether the source is a text-based or a scanned PDF makes a large difference. Text-based PDFs allow text to be extracted directly, whereas a scanned PDF is essentially a set of images and needs OCR before usable text exists.
• Pay attention to the filtering condition in batch tasks. On Windows, opening a document in Word creates temporary files whose names start with ~$; filtering by extension and excluding those keeps unrelated files out of the run.
• Call Close() when finished to release resources. This matters especially inside a batch loop, where otherwise file handles accumulate.

Conclusion

This article covered converting documents to Markdown with Python: loading a Word document through Document and saving it with FileFormat.Markdown, while the same object can also be saved as docx, PDF, and other formats; handling PDFs with PdfToMarkdownConverter and MarkdownOptions.IgnoreImage; and converting a whole folder with a single loop. Because every output is a text file, both verification and downstream processing can be done by script, which suits batch workflows such as documentation sites and corpus preparation.