Convert Word documents to Markdown

Many developers write their documentation with a program like Microsoft Word. Word is widely available and easy to use. All you need to do is start writing. In a demanding field like software development, the simplest tool is often the best one.

Word, though, has its drawbacks:

• Contextual elements, like code blocks or collapsible sections, are hard or impossible to add.

• The bells and whistles distract from writing.

• Documents are hard to version control.

GitHub Pages and Markdown solves these issues. That doesn’t mean, though, you have to rewrite your Word document in Markdown. Instead, you can use a tool like pandoc to convert them for you.

The pandoc tool

The pandoc can convert documents from one format to another.

To convert your Word document to Markdown:

1. Install pandoc.

   Confirm the installation by running the following command:

   pandoc --verison

2. Run the following command:

   pandoc \
   --extract-media ./images \
   -o path/to/markdown/file.md \
   path/to/word/file.docx

Pandoc saves your converted document to path/to/markdown/file.md. The --extract-media argument saves any images from your Word document to a folder called images.

Review the output

It’s important to check that the conversion was successful. You may need to clean up some artifacts or ill-formatted tables before submitting the document to your version control system.