Push Manifesto
All guides

Working practices

Working with Markdown

Moving documents between Word, PDF and Markdown with Pandoc, plus tables, citations and bibliographies.

Updated Sep 11, 20263 min read
markdown
pandoc
documentation
word

Push projects keep their documentation in Markdown so that it lives next to the code, diffs cleanly and renders anywhere.1 Stakeholders still want Word and PDF. This page covers the conversions in both directions using Pandoc, and the pieces around it: tables, citations and reference managers.2

Converting Microsoft Word to Markdown🔗

The following provides example CLI using Pandoc for converting Microsoft Word documents into Markdown with support for Azure DevOps Style Tables.

Note: conversion accuracy depends on styles and complexity of the document, specifically tables may require further treatment. If you see HTML Tables then try HTML-Table-To-Markdown

code
pandoc -o output.md -f docx -t markdown-simple_tables-multiline_tables-grid_tables --wrap=none --column=999 "document.docx"

Converting Markdown to Microsoft Word🔗

Pandoc supports a couple of techniques for generating Word documents, as follows:

Firstly, direct:

code
pandoc -o output.docx document.md
pandoc --extract-media ..\.media -o output.docx document.md
pandoc --extract-media ..\.media -s --bibliography biblio.json --citeproc --csl ieee.csl CITATIONS -o output.docx document.md

... and second is using a Template:

code
pandoc --reference-doc template.docx -o output.docx document.md
pandoc --reference-doc template.docx --extract-media ..\.media -s --bibliography biblio.json --citeproc --csl ieee.csl CITATIONS -o output.docx document.md
  • Note: the template only provides Word Styles not content.

Both techniques allow for a media directory (--extract-media) to be set for loading images. Multiple Markdown documents may also be included by appending to the command line.

Keep two documents in your project for corporate styling: a template that carries the Word styles, and a template body that carries the cover page, headers and fields.

For example:

  1. Convert Markdown to Word, output.docx
code
pandoc --extract-media ..\.media --reference-doc template.docx -o output.docx document.md
  1. Open the template body document then paste the resulting contents from the output.docx and File → Save to a new document. Don't forget to update the Document Properties and update the Fields.

Converting Adobe PDF to Markdown🔗

Pandoc doesn't support directly PDF to Markdown. A workaround for this is to convert the PDF to Word using Adobe's online tool: pdf-to-word. Then use the following:

code
pandoc -o output.md -f docx -t markdown-simple_tables-multiline_tables-grid_tables --wrap=none --column=999 "document.docx"

Working with Tables🔗

Finding it hard to keep track using tables? Then tablesgenerator is a good place to get your eye in. tablesgenerator does what it says and for a number of outputs as LaTeX, Html, Text, Markdown and MediaWiki.

Working with Bibliography🔗

Specifying a Bibliography🔗

Pandoc can automatically generate citations and a bibliography in a number of styles. In order to use this feature, you will need to specify a bibliography file using the bibliography metadata field in a YAML metadata section. For example:

yaml
---
title: "Sample Document"
output: pdf_document
bibliography: bibliography.bib
---

Citations🔗

Citation Syntax🔗

Citations go inside square brackets and are separated by semicolons. Each citation must have a key, composed of ‘@’ + the citation identifier from the database, and may optionally have a prefix, a locator, and a suffix. Here are some examples:

code
Blah blah [see @doe99, pp. 33-35; also @smith04, ch. 1].

Blah blah [@doe99, pp. 33-35, 38-39 and *passim*].

Blah blah [@smith04; @doe99].

A minus sign (-) before the @ will suppress the mention of the author in the citation. This can be useful when the author is already mentioned in the text:

code
Smith says blah [-@smith04].

You can also write an in-text citation, as follows:

code
@smith04 says blah.

@smith04 [p. 33] says blah.

References🔗

  • Keep an example bibliography (biblio.json) alongside your documents as a starting point.
  • ieee.csl

Software🔗

Resources🔗

Pandoc🔗

Pandoc is a Haskell library for converting from one markup format to another, and a command-line tool that uses this library.

Download via the following link:

Footnotes🔗

  1. Gruber, J. (2004). Markdown. Daring Fireball. daringfireball.net/projects/markdown ↩

  2. MacFarlane, J. Pandoc User's Guide. pandoc.org/MANUAL.html ↩

Working with Markdown | Push Manifesto · Push Manifesto