Markdown / Word

A LaTeX user's day ends the moment a co-author says “just send it as a Word file”. The standard bridge is pandoc, a converter that moves between Markdown, LaTeX and .docx — but the two directions behave nothing alike. Word → LaTeX builds structure that was never there, so nothing is lost. LaTeX → Word does the opposite: it flattens the structure you carefully built — the link between \label and \ref, the meaning of a \newcommand, the shape of a formula. LaTeX is a program; a .docx is a record of a finished result. You can run a program and keep its output, but you cannot reconstruct the program from the output. That asymmetry is the backbone of this page.

Why LaTeX → Word loses more than the other direction

The answer is simple: there is nothing at the destination to receive it. A .docx is essentially a container of paragraphs, character formatting and style names. It has no equivalent of \newcommand, and no machinery for recomputing the number a \ref points to. So pandoc translates your intent as far as Word's vocabulary reaches and drops the rest. Numbers freeze as whatever they happened to be, and cross-references become plain characters rather than live links. The other direction is far easier. A Word document has little structure beyond heading levels, lists and bold, so pandoc merely maps that onto \section and itemize: information can only be added, never removed. The asymmetry is written into pandoc's own history too — docx output arrived with pandoc 1.9 in 2012, and the docx reader, complete with track-changes awareness, was contributed by Jesse Rosenthal in 2014: six and eight years after the project began.

pandoc basics: -f, -t and --pdf-engine

Using pandoc is a matter of naming the input format with -f (--from) and the output format with -t (--to). At the centre sits a single abstract syntax tree: readers build the AST, writers emit from it, and that is why adding formats does not multiply the work. Its author, John MacFarlane, is a professor of philosophy at the University of California, Berkeley, who started the project to teach himself Haskell. The first version, published on 3 August 2006, was about 3,000 lines — and it could already convert among Markdown, reStructuredText, HTML and LaTeX. Today it handles more than fifty input formats and more than seventy output formats. Adding --pdf-engine=lualatex will take you all the way to PDF through a LaTeX engine, but note that pandoc is not part of TeX Live: it is a separate program written in Haskell and has to be installed on its own.

pandoc -f markdown -t latex in.md  -o out.tex    # Markdown to LaTeX
pandoc in.md  -o out.pdf --pdf-engine=lualatex  # Markdown straight to PDF
pandoc in.tex -o out.docx                       # LaTeX to Word
pandoc in.docx -o out.tex                       # Word to LaTeX

Two further hooks let you shape the output. --template replaces the outer scaffolding of text-based output formats (latex, html and friends), so you can swap in your own preamble or \documentclass. It does nothing for binary formats such as .docx — that is what --reference-doc above is for. The other hook is a Lua filter (--lua-filter), which rewrites the AST directly, after reading and before writing. Jobs like “turn this environment into a different heading” or “strip every \todo{...}” are far safer done at that stage than with regular expressions on the LaTeX source.

What pandoc understands in LaTeX, and whether it warns you

pandoc understands only part of LaTeX, but it is not entirely silent about it. For mathematics, when it meets something it cannot parse it prints a Could not convert TeX math warning and leaves that formula in the output as LaTeX — passing it through rather than discarding it. Custom macros survive better than you might expect: with the latex_macros extension enabled, pandoc, in the words of the official manual, parses LaTeX macro definitions and applies the resulting macros to all LaTeX math and raw LaTeX. So a \newcommand{\R}{\mathbb{R}} comes through fine. What really disappears quietly is what lies beyond. A block pandoc classifies as raw LaTeX — a tikzpicture environment, say — is kept in the AST as raw, but the docx and HTML writers do not emit it. No warning is printed the way it is for math, so the accident is discovered only when the file is opened in Word and the figure is simply gone.

Controlling the look of the Word file with --reference-doc

When the look of the produced .docx is wrong, the knob to turn is not a template but --reference-doc. The official manual explains the mechanism plainly: the contents of the reference docx are ignored, and only its stylesheets and document properties — including margins, page size, header and footer — are used in the new docx. The reference file is a blank sample of formatting, not a boilerplate text. The right way to build one is therefore to extract pandoc's default reference file, open it in Word or LibreOffice, edit the styles (Heading 1, Body Text, Table Caption and so on) to match the submission guidelines, save it and reuse it. The manual adds that for best results the reference docx should be a modified version of a docx produced by pandoc. In the extraction command, -o must come before --print-default-data-file.

# 1. extract the default reference file (-o must come first)
pandoc -o custom-reference.docx --print-default-data-file reference.docx

# 2. edit the STYLES in Word or LibreOffice, then save

# 3. reuse it for every export
pandoc in.tex -o out.docx --reference-doc=custom-reference.docx

The options that actually matter going Word → LaTeX

A .docx is really a ZIP archive of XML, so pandoc can read it directly. The first flag to add on import is --extract-media=media, which does what the official manual says: extract images and other media contained in or linked from the source document into that directory and adjust the image references to point at the extracted files. Forget it and the figures appear nowhere. Files coming back from a co-author usually carry tracked changes, and --track-changes=accept / reject / all decides what happens to them — all keeps everything wrapped in spans. The option only affects the docx reader. Bibliographies can be resolved with --citeproc plus a .bib file, with the CSL style chosen by --csl. If the hard-wrapped paragraphs in the output annoy you, add --wrap=none. Word's paragraph styles survive as custom-style, which gives you a handle for mapping an author's house styles onto LaTeX environments.

pandoc in.docx -o out.tex \
  --extract-media=media \
  --track-changes=accept \
  --wrap=none

# with a bibliography and a journal style
pandoc in.docx -o out.tex --citeproc --bibliography=refs.bib --csl=apa.csl

Getting to Word without installing pandoc: tex4ht's ODT output

It is not widely known, but TeX Live alone can reach a word-processor format. Running make4ht -f odt file.tex produces an .odt — an OpenDocument text file. Opening it up, it turns out not to be a paste-up of pictures: the mathematics is embedded as ODF formula objects of media type application/vnd.oasis.opendocument.formula, and inside them is MathML. The equations stay equations on the word-processor side. mk4ht oolatex file.tex takes the same route (older articles mention a standalone oolatex command; in TeX Live 2024 it is invoked as a job name of mk4ht). Word can open OpenDocument text, and if you want certainty you can open it in LibreOffice and re-save as .docx. When the point is to hand over equations that remain editable, this can beat the pandoc route.

# LaTeX to OpenDocument text, using only TeX Live
make4ht -f odt file.tex

# the same route under its historical name
mk4ht oolatex file.tex

Two other tools deserve a mention by name. writer2latex is an open-source Java tool that converts LibreOffice/OpenOffice documents to LaTeX, and GrindEQ is a commercial Word ↔ LaTeX converter known for handling MathType equations well. Neither is part of TeX Live, and neither was installed on the machine used for this article, so their behaviour has not been checked here. If you adopt one, try it first on a small piece of your real file and see with your own eyes whether the equations and figures survive.

Living with a co-author who insists on Word

• Keep LaTeX as the source of truth. A .docx is output, not a working file. The moment a version edited directly in Word becomes the master, every round trip starts degrading it.
• Hand over sections, not the whole paper. Sending only the section you want comments on is far easier to merge back than one giant .docx.
• Read what comes back with --track-changes=all first. See what changed, then either import with accept or copy just the changes into the source by hand.
• Keep figures as image files from the start. TikZ disappears through pandoc, so a setup where figures are exported to SVG or PDF and pulled in with \includegraphics survives every conversion.
• If the equations must stay editable, try the ODT route. make4ht -f odt leaves them as MathML formula objects.
• Lock the journal's formatting into a --reference-doc. Fixing margins and styles by hand in Word is something you will certainly forget to redo the second time.