This page is a quickstart introduction to the free Pandoc conversion utility.

About Pandoc

Pandoc (pandoc.org) is a powerful open-source utility which can facilitate conversion between file formats, including those with embedded math data. Pandoc requires a command line interface, but simple commands can be quickly learned and reused as needed.

Pandoc is also embedded in some conversion utilities such as the DAISY WordtoEPUB (Windows Only) converter.

Command Line Programs

Before installing Pandoc, make sure you have access to a command line interface for your operating system. Options include:

Install Pandoc

Pandoc is availble for Windows, Macintosh or Linux. To install Pandoc:

  1. Go to the Pandoc Install page at pandoc.org.
  2. Click the blue button link "Download the latest installer." A window listing files opens.
    Note: Additional installation options are given, but experience with Unix or other command line interfaces are recommended to use those.
  3. Select and download the file labeled with the appropriate operating system.
  4. Extract the contents and follow the installation instructions. You may not need to open the command line interface at this point.

Establish a Pandoc Folder/Directory

After you install Pandoc, it is recommended to create a folder named "Pandoc" or something memorable.

If you consistently place files that need to be converted in the same folder, you will reduce the changes needed in your conversion commands.

See Pandoc Getting Started for details.

Running Pandoc

Confirm Pandoc Installation

Once Pandoc is installed, it is activated through a command line interface. You can run a quick test to make sure it’s installed.

  1. Open your preferred command line interface program.
  2. In the command line window type
    pandoc --version
  3. If Pandoc is installed, you will see a message indicating which version is installed.
    Note: The text "pandoc" is the command which activates Pandoc. The text "--version" indicates that Pandoc will list out which version is installed.
ALT: Terminal window showing the outpit of the pandoc –version command. See details below.

A command line interface showing that Pandoc 3.1.8 (release in 2023) has been installed and which folder it is in (blurred in the image).

The licensing notice is "Copyright (C) 2006-2023 John MacFarlane. Web: https://pandoc.org. This is free software; see the source for copying conditions. There is no warranty, not even for merchantability or fitness for a particular purpose."

Navigating Folders/Directories

The Pandoc conversion commands rely on knowing the location of the files being converted. A best practice is to use the command line interface to navigate to the correct folder. Below are some example commands:

Basic Navigation Commands

  1. pwd – show current (working) directory
  2. ls – lists files and directories in the current working directory
  3. cd – change directory. Use with an option such as ones listed below
    1. <pwd>/xx – down one directory into to directory (folder) "xx"
    2. ../ – up one directory
    3. ../xx – up one directory then into directory "xx"

See the document for Pandoc Getting Started, Step 3 section to learn details of the commands for navigating folders in the command line interface.

 

Example Pandoc Commands

This section explains how Pandoc commands are structured then gives some examples. To learn more about the program, visit the links given at the bottom of the document

Template of a Pandoc Command

First, note that all Pandoc commands begin with the word

pandoc

After this command are parameters which specify input file, optional input parameters, output parameters and designated output file name. Thus, the command structure is similar to the one given below:

pandoc <optional extra commands> <input file name> <input and output parameters> <output file name>

As you will see in the example commands below, pandoc assumes that you are within the same directory as the input file. The output file will also be placed in that same directory.

TEX + LaTeX to HTML + MathML

This command converts a .tex file containing LaTeX math and converts it to an HTML file with the LaTeX converted into MathML.

pandoc foo.tex -f latex -t html -s --mathml -o foo.html

Note that the following parameters are present:

  • input file = foo.tex
  • -f = from (input file type)
    • latex = file type
  • -t = to (output file type)
    • html -s –mathml = HTML, standalone, with HTML
  • -o = output to
  • output file = fooML.html

Word + Equation to HTML + MathML

For a Microsoft Word file, Pandoc needs to first extract media from the .docx file, then convert it to a desired output. In this case, the output is again, an HTML file with MathML used for the any embedded equations.

Note: This command assumes that the Microsoft Office equation editor is being used.

pandoc –extract-media=. –s foo.docx –t html –s –mathml –o foo.html

If the Word file contains heading styles and images with alt text, they will be converted to HTML H-tags and links images with the alt text attribute.

Embedded Images and ALT Text

If a Word file contains embedded images with image ALT text, the images will be placed into a file called "media", and the output HTML file will contain links to the image along with any image ALT text inserted into Word.

Custom CSS

Pandoc will insert default CSS, but you can also insert a link to a custom CSS file by inserting an argument -c <foo.css>. See example below.

pandoc –extract-media=. –s foo.docx –t html -c foo.css –s –mathml –o foo.html

 

Additional Examples

See the Pandoc Demos page for additional conversion scenarios. The Try Pandoc! page is a GUI/WYSIWYG editor which lets you generate commands.

Pandoc Links

Top of Page

Last Update: October 17, 2023