Pandoc is a command-line program that converts documents from one format to another. It reads Markdown, DOCX, HTML, LaTeX, ODT and many other formats, and writes just as many. It is free, open source and runs on Windows, macOS and Linux.
Its practical value is that it lets you write once, in a simple format, and then get the versions you need: a DOCX to send to people who work in Word, a PDF to archive, an HTML page to publish. In my work it is the tool that closes the loop between Markdown notes and deliverable documents.
How Pandoc thinks
Pandoc does not translate directly from one format to another. It reads the source file, turns it into an internal representation made of blocks (headings, paragraphs, lists, tables, notes) and from there generates the target format.
This explains its behaviour: it preserves the structure of the document very well and the appearance much less. A level 2 heading stays a level 2 heading; a colour applied by hand in Word, on the other hand, is lost. If the structure is tidy, the conversion is clean.
The basic commands
The format is inferred from the file extension:
pandoc report.md -o report.docx
pandoc report.md -o report.html --standalone
pandoc report.docx -o report.md
-osets the output file.--standalone(or-s) produces a complete document, with a header, instead of a fragment.- The third line shows the reverse conversion: from Word to Markdown, useful for recovering texts written by others.
To state formats explicitly you use -f (from) and -t (to), for example -f docx -t gfm.
Getting a PDF
Pandoc does not draw PDFs by itself: it relies on an external engine. The most common is LaTeX, which has to be installed separately:
pandoc report.md -o report.pdf --pdf-engine=xelatex -V lang=en
XeLaTeX and LuaLaTeX handle accented characters and system fonts better. Alternatively you can go through HTML and use an engine such as WeasyPrint, which lays out pages with CSS. If installing LaTeX seems heavy, there is also the simpler route: convert to DOCX or ODT and save as PDF from the word processor.
Styling the DOCX
By default the generated DOCX uses neutral styles. To get your company look you use a reference document:
- Generate the base file:
pandoc -o reference.docx --print-default-data-file reference.docx. - Open it in Word or Writer and modify the styles for headings, body text, tables and so on. Modify the styles, not the text.
- Convert using that file:
pandoc text.md -o text.docx --reference-doc=reference.docx.
From then on every conversion inherits fonts, colours, margins and spacing. That is why it pays to write in Markdown even documents that will ultimately be delivered in Word.
Metadata, table of contents and numbering
Title, author and date can go in the YAML header of the Markdown file or on the command line with -M title="...". Other useful options:
| Option | Effect |
|---|---|
--toc |
Inserts a table of contents |
--toc-depth=2 |
Limits the contents to the first two levels |
-N |
Numbers the headings (1, 1.1, 1.2…) |
--resource-path=img |
Tells Pandoc where to look for images |
--citeproc |
Processes bibliographic citations |
Automating with a configuration file
When the options pile up, retyping them every time is awkward and error-prone. Pandoc accepts settings files (--defaults=settings.yaml) in which you list output format, reference document, PDF engine and filters. Alternatively a small script or a Makefile is enough. That way anyone in the group gets the same result with a single command.
Frequent problems
- Missing images. Paths are relative to the folder from which you run the command, not to the file's folder. Use
--resource-pathor run Pandoc from the right folder. - Complex tables. Merged cells and nested Word tables have no Markdown equivalent and get simplified.
- Direct formatting lost. Bold and italics survive; colours, highlights and hand-picked fonts disappear. It is a sign that the original document did not use styles.
- Odd characters in the PDF. This often depends on the engine: with
pdflatexsome Unicode characters fail, withxelatexthey usually do not.
In short
- Pandoc converts between dozens of formats via a common internal structure.
- It preserves headings, lists, tables and notes well; it loses formatting applied by hand.
- PDF output needs an external engine, usually XeLaTeX or LuaLaTeX.
- With a reference document, the generated DOCX takes on the company style.
- A settings file makes conversions repeatable for the whole group.
