So conversion is part of the job. The trouble is that these three formats were built for different things, and every conversion between them throws something away. This guide covers what each format really stores, which direction converts cleanly, and how to set up a workflow where the losses don't hurt.

Three formats, three different ideas of a document

Markdown is plain text with light structure: headings, lists, links, code blocks, emphasis and (in GitHub Flavored Markdown) tables. It has no concept of page size, fonts or margins. That is why it diffs well in Git and why it is pleasant to review in a pull request.

DOCX is a ZIP archive of XML files. It stores structure (paragraph styles such as Heading 1), but also direct formatting, comments, tracked changes, headers, footers, section breaks and embedded images. Much of what makes a Word file look right lives in styles and layout settings that Markdown has no place for.

PDF is a page description format. It records where glyphs and shapes go on a fixed page. A paragraph in a PDF is often just a series of positioned text runs, and a table may be a grid of lines with text placed inside it. Tagged PDFs can carry a logical structure, but plenty of PDFs in the wild don't have one.

Put simply: Markdown stores meaning, PDF stores appearance, and DOCX stores a mix of both. Conversions that go from meaning to appearance work well. Conversions that go from appearance back to meaning involve guessing.

Markdown as the source of truth

The workflow that causes the least pain treats Markdown as the only file you edit and generates DOCX and PDF from it when someone needs them. Generated files are build artifacts. You don't commit edits to them and you don't fix typos in them.

Pandoc is the standard tool for this. A few commands cover most needs:

# Markdown to DOCX, using your company template for styles
pandoc guide.md -o guide.docx --reference-doc=company-template.docx

# Markdown to PDF (needs a PDF engine; LaTeX is the default)
pandoc guide.md -o guide.pdf --pdf-engine=xelatex

# Markdown to standalone HTML, which you can then print to PDF
pandoc guide.md -s -o guide.html

The --reference-doc option is worth knowing. Pandoc maps Markdown headings, body text and code to named Word styles, and takes the look of those styles from the reference document. Fonts, colours and spacing come out matching the corporate template without anyone touching the DOCX by hand.

For PDF, the main decision is the engine. LaTeX engines give good typography but need a large install. HTML-based engines such as WeasyPrint let you style the output with CSS, which many web developers find easier. Either way, run the build in CI so the PDF attached to a release always matches the Markdown in the tag.

Bringing DOCX into the repo

Sooner or later someone hands you a Word document that has to become docs. Pandoc handles this direction well, because DOCX keeps real structure underneath the formatting:

pandoc spec.docx -t gfm --wrap=none --extract-media=./media -o spec.md

What each flag does:

• -t gfm writes GitHub Flavored Markdown, so tables survive as pipe tables where possible.
• --wrap=none keeps each paragraph on one line, which makes later diffs much cleaner.
• --extract-media=./media writes embedded images to a folder and links them from the Markdown.

If the document has tracked changes, decide what you want before converting. Pandoc's --track-changes option accepts accept, reject or all. Accepting is usually right for a final spec. Keeping all changes is useful when you need to see what a reviewer did.

The usual problems come from authors who formatted by hand instead of using styles. A line made bold and 16pt is not a heading as far as the file is concerned, so it arrives in Markdown as bold text. Merged table cells, text boxes and floating images also have no Markdown equivalent. Expect to spend a few minutes fixing headings and tables after the conversion. Searching the output for ** at the start of lines is a quick way to find fake headings.

Getting text out of PDF without false expectations

PDF to Markdown is the hardest direction, because the converter has to rebuild structure from layout. It guesses headings from font size and weight, paragraphs from line spacing, and tables from alignment. Multi-column layouts, footnotes, running headers and page numbers all get in the way.

Some practical rules:

• Find the source first. If the PDF was exported from Word, Google Docs or a docs site, ask for the original. A DOCX or HTML file will convert far better than the PDF made from it.
• Check whether the PDF has a text layer. Try selecting text in a viewer. If you can't, the file is a scan, and you need OCR before any Markdown conversion means anything.
• Treat the output as a draft. Expect to fix heading levels, rejoin hyphenated words, delete repeated headers and footers, and rebuild complex tables by hand.
• Diff, don't trust. Put the converted Markdown in a branch and read it in the PR view next to the original PDF.

For a one-off file where installing a toolchain isn't worth it, a browser converter is the quickest way to get a first draft. The PDF to Markdown converter on CleverUtils runs in the browser, needs no account, and uploaded files are deleted automatically after 2 hours. That still means uploading the file to a server, so keep confidential documents on local tools.

A workflow that holds up

Putting it together, a setup that works for small and mid-sized teams looks like this:

1. One source format. Docs live as Markdown in the repo. Everyone edits there, through pull requests.
2. Generated outputs. A CI job builds DOCX (with a reference template) and PDF on every release and attaches them as artifacts. Nobody edits those files.
3. One-way imports. When a DOCX or PDF arrives from outside, convert it once, clean it up, commit the Markdown, and archive the original. After that, the Markdown is the document.
4. Comments come back as Markdown changes. If a reviewer marks up the DOCX, apply their changes to the Markdown source instead of merging the Word file back.
5. Images live in a folder. Keep extracted and new images in a predictable path such as docs/media/ and reference them with relative links, so every output format can find them.

The point of all this is to never round-trip. Markdown to DOCX and back to Markdown loses something each time, usually in tables and image references, and after a few cycles the source is a mess.

Quick reference

Local tools like Pandoc are the right choice for anything repeatable or sensitive. For the odd file that lands in your inbox in a format you don't have tools for, CleverUtils (https://cleverutils.com) has 200+ converters that run in the browser with no account and no watermarks. It is made in Kyiv, Ukraine.