Table of Contents

What is Pandoc?
Getting Started with Pandoc
Basic Pandoc Command Structure
Common Document Conversions for Math Content
- Markdown with LaTeX Math to HTML with MathML
- Markdown with LaTeX Math to HTML with MathJax
- Markdown with LaTeX Math to Microsoft Word
- Markdown with LaTeX Math to Accessible PDF (Experimental)
- HTML with MathML or MathJax to Markdown (Experimental)
- Word Document with Equations to Markdown
- Markdown with LaTeX Math to EPUB
- Converting Multiple Files into a Single Document
- Word to HTML with MathML
- Word to HTML with MathJax
- Word to EPUB with MathML
Advanced Options for Math Accessibility
Examples of Math Content in Markdown
- Inline Math Example
- Display Math Example
Troubleshooting Common Issues
Getting Help
Next Steps

What is Pandoc?

Pandoc is a powerful free "Swiss Army knife" for document conversion. It's especially valuable for accessibility workflows because it can transform content between formats while doing its best to maintain the semantic and structural integrity of the content. It can convert:

Markdown to HTML, Word, PDF, EPUB, PowerPoint, and many other formats
Word documents to Markdown, HTML, PDF, and more
HTML to Markdown, Word, PDF, and other formats
And many other conversion combinations

Pandoc excels at handling mathematical content in these conversions, particularly when the source contains LaTeX math expressions.

Getting Started with Pandoc

Installing Pandoc

Windows Installation

Visit the Pandoc website
Download the Windows installer (.msi file)
Run the installer and follow the prompts
After installation, Pandoc is ready to use from the command line

macOS Installation

Option 1: Using the Installer

Visit the Pandoc website
Download the macOS installer (.pkg file)
Run the installer and follow the prompts

Option 2: Using Homebrew (for users familiar with Homebrew)

Open Terminal
Type: brew install pandoc
Press Enter

Accessing the Command Line

Pandoc is used through the command line, but don't worry if you've never used it before!

Windows: Opening Command Prompt

Click the Start menu
Type "cmd" or "command prompt"
Click on "Command Prompt" in the search results
A black window will open—this is where you'll type Pandoc commands

macOS: Opening Terminal

Open the Applications folder
Open the Utilities folder
Double-click on Terminal
A white or black window will open—this is where you'll type Pandoc commands

Navigating to Your Documents

Before converting files, you need to navigate to the folder where your documents are located:

Windows: Changing Directories

First, identify where your file is located (e.g., C:\Users\YourName\Documents\MathFiles)
In the Command Prompt, type: cd C:\Users\YourName\Documents\MathFiles
Press Enter

macOS: Changing Directories

First, identify where your file is located (e.g., /Users/YourName/Documents/MathFiles)
In Terminal, type: cd /Users/YourName/Documents/MathFiles
Press Enter

Tip: You can drag a folder from Finder (macOS) or File Explorer (Windows) into the Terminal/Command Prompt window to automatically fill in the path.

Basic Pandoc Command Structure

Pandoc commands follow this basic pattern:

pandoc -f [input-format] -t [output-format] [input-filename] -o [output-filename] [options]

Where:

-f specifies the input format
-t specifies the output format
-o specifies the output file name
[options] are additional settings that modify how the conversion works

In many cases, Pandoc can detect the formats based on file extensions, so you can use a simpler format:

pandoc [input-filename] -o [output-filename] [options]

Understanding Single (-) vs. Double (--) Dashes in Commands

Many users get confused about when to use a single dash versus double dashes in command line tools like Pandoc. Here's the distinction:

Single dash (-): Used for single-letter options (short options)
Double dash (--): Used for word options (long options)

For example, in this command:

pandoc -s input.md -o output.html --mathjax --table-of-contents

-s is the short form of --standalone
-o is the short form of --output
--mathjax and --table-of-contents don't have short forms, so they use double dashes

Both formats do the same thing, but short options (-x) are quicker to type while long options (--descriptive-name) are easier to understand when reading commands. You can use whichever style you prefer, or mix them as shown above.

Handling Filenames with Spaces

When working with file or folder names that contain spaces, you need to properly handle these spaces in the command line:

Method 1: Use Quotes

Enclose any file or folder path that contains spaces in quotes:

Windows Example:

cd "C:\Users\YourName\Documents\Math Files"
pandoc "my math document.md" -o "accessible math.pdf"

macOS Example:

cd "/Users/YourName/Documents/Math Files"
pandoc "my math document.md" -o "accessible math.pdf"

Method 2: Use Escape Characters

Alternatively, you can escape the space with a backslash:

Windows Example:

cd C:\Users\YourName\Documents\Math\ Files
pandoc my\ math\ document.md -o accessible\ math.pdf

macOS Example:

cd /Users/YourName/Documents/Math\ Files
pandoc my\ math\ document.md -o accessible\ math.pdf

Using quotes is generally easier and less error-prone, especially for beginners.

For more on pandoc commands

Run pandoc --help for a list of options
Visit the Pandoc documentation for comprehensive guidance
For math-specific questions, check the Pandoc Math documentation

Common Document Conversions for Math Content

### Markdown with LaTeX Math to HTML with MathML This conversion creates a web page with native MathML (without requiring MathJax or any JavaScript) from a Markdown document containing LaTeX math. **Command:** ``` pandoc -s math_document.md -o math_webpage_mathml.html --mathml ``` **Important Notes:** - The `-s` option creates a standalone HTML file with necessary headers - The `--mathml` option converts LaTeX math directly to MathML in the HTML - MathML is natively supported by most modern browsers and can be more accessible for some than MathJax - This approach doesn't require JavaScript to render the math - Screen readers with MathML support can directly access the mathematical content - For complex equations, the quality of conversion depends on Pandoc's LaTeX-to-MathML converter (MathJax might work better with complex math)

Markdown with LaTeX Math to HTML with MathML

This conversion creates a web page with native MathML (without requiring JavaScript) from a Markdown document containing LaTeX math.

Command:

pandoc -s math_document.md -o math_webpage_mathml.html --mathml

Important Notes:

The -s option creates a standalone HTML file with necessary headers
The --mathml option converts LaTeX math directly to MathML in the HTML
MathML is natively supported by most modern browsers and is more accessible than MathJax
This approach doesn't require JavaScript to render the math
Screen readers with MathML support can directly access the mathematical content
For complex equations, the quality of conversion depends on Pandoc's LaTeX-to-MathML converter

Markdown with LaTeX Math to HTML with MathJax

This conversion creates a web page with MathJax-enabled math from a Markdown document containing LaTeX math.

Command:

pandoc -s math_document.md -o math_webpage.html --mathjax

Important Notes:

The -s option creates a standalone HTML file with necessary headers
The --mathjax option adds a link to the MathJax CDN for rendering math in the browser
Both inline math ( $...$ ) and display math ($$...$$) from your Markdown will be properly converted

Markdown with LaTeX Math to Microsoft Word

This conversion creates a Word document (.docx) with editable equations from Markdown with LaTeX math.

Command:

pandoc math_document.md -o math_document.docx

Important Notes:

Math expressions are converted to native Word equations
These equations will be accessible to screen readers that support Microsoft's math format
For complex documents, you may need a reference document: --reference-doc=template.docx

Markdown with LaTeX Math to Accessible PDF (Experimental)

Creating an accessible PDF requires a the TeX distribution to be installed (MiKTeX for Windows, MacTeX for macOS) containing the latest Unicode engine luaLaTeX. This example uses the recommended PDF engine (luaLaTeX) for accessibility and tells pandoc to pass in the necessary metadata to create a fully tagged PDF using the "MathML Structure Element tagging" technique. See the [TODO] page for more details on this process.

Command:

pandoc math_document.md -o math_document.pdf --pdf-engine=lualatex --variable=header-includes:"\RequirePackage{pdfmanagement-testphase}\DeclareDocumentMetadata{uncompress,lang=en,testphase=latest,pdfversion=2.0,pdfstandard=ua-2,pdfstandard=a-4f}\tagpdfsetup{math/mathml/structelem,math/tex/AF=false,math/mathml/AF=false,math/mathml/sources=}"

Important Notes:

This requires a TeX distribution to be installed (MiKTeX for Windows, MacTeX for macOS)
For truly accessible math with proper tagging, you need to use LuaLaTeX (not XeLaTeX) with specific LaTeX3 tagging project settings

The LaTeX3 tagging project (as of 2024-2025) allows PDFs to include directly embedded MathML in the structure tree using the Structure Element technique, which is better supported by screen readers than the Associated Files approach
Note that Pandoc alone cannot create fully accessible math PDFs without these special LaTeX settings
This conversion is listed as "Experimental" because I have had mixed success with using pandoc to do these conversions

HTML with MathML or MathJax to Markdown (Experimental)

This converts a web page with math into a Markdown document with LaTeX math expressions.

Command:

pandoc math_webpage.html -o math_document.md

Important Notes:

Pandoc will attempt to convert MathML or MathJax expressions back to LaTeX syntax
The quality of conversion depends on how the original HTML was structured
This is useful for extracting content from web resources for further editing

Word Document with Equations to Markdown

This extracts content and equations from a Word document into a Markdown file with LaTeX math.

Command:

pandoc math_document.docx -o math_document.md

Important Notes:

Word equations will be converted to LaTeX math syntax
Complex formatting may not convert perfectly
Tables and other structures are preserved as Markdown syntax

Markdown with LaTeX Math to EPUB

This creates an e-book with accessible math from a Markdown document.

Command:

pandoc math_document.md -o math_ebook.epub --mathml

Important Notes:

The --mathml option uses MathML in the EPUB, which is better for accessibility
EPUB readers with MathML support will properly display the mathematics
This creates EPUB 3, which has better accessibility support than EPUB 2

Converting Multiple Files into a Single Document

To combine multiple Markdown files into a single output document:

Command:

pandoc chapter1.md chapter2.md chapter3.md -o complete_document.docx

Important Notes:

Files are processed in the order listed
You can use wildcards like *.md to include all Markdown files in a directory
Add -s for standalone output with proper document structure

Word to HTML with MathML

Converting Word documents with equations to HTML using native MathML:

Command:

pandoc document.docx -o mathml_webpage.html -s --mathml --extract-media=images

Important Notes:

The --mathml option converts Word equations to MathML in the HTML output
MathML is natively supported by most modern browsers
This approach doesn't require JavaScript, unlike MathJax
MathML is generally more accessible for screen readers
For complex equations created in Word, the quality of conversion to MathML may vary
Equations created with the modern Word Equation Editor convert more reliably than legacy equation objects
If accessibility is a priority, this option is preferable to MathJax

Word to HTML with MathJax

Converting Word documents with equations to HTML using MathJax for rendering:

Command:

pandoc document.docx -o math_webpage.html -s --mathjax --extract-media=images

Important Notes:

Word equations are converted to LaTeX syntax and rendered with MathJax
The --mathjax option adds a link to the MathJax CDN for client-side rendering
MathJax provides high-quality math rendering that works across browsers
This approach requires JavaScript to be enabled in the browser
Add --extract-media=images to handle any images in the document
Word's native equations (created with the Equation Editor) are supported
Equations inserted as images or objects might not convert properly

Word to EPUB with MathML

Consider using the wonderful WordToEPUB Add-in for Microsoft Word from DAISY which effectively adds an easy to use GUI to this process.

Converting Word documents with equations to accessible EPUB format using MathML:

Command:

pandoc document.docx -o math_ebook.epub --mathml

Important Notes:

This converts Word equations to MathML in the EPUB output
Using the --mathml option is essential for accessible math in e-books
By default, pandoc creates EPUB 3 format, which has better support for MathML
You can specify EPUB version explicitly with --epub-version=3

Add metadata to improve accessibility:

pandoc document.docx -o math_ebook.epub --mathml --epub-cover-image=cover.jpg --metadata title="Math Document" --metadata creator="Your Name"

Word's native equations (created with the Equation Editor) convert more reliably

For complex documents, you may need to specify a custom CSS:

pandoc document.docx -o math_ebook.epub --mathml --css=custom_style.css

To ensure proper language tagging for accessibility:

pandoc document.docx -o math_ebook.epub --mathml --metadata lang=en

EPUB files can be validated with the EPUBCheck tool to verify accessibility

Testing Accessibility: After conversion, test your EPUB with:

Apple Books (macOS/iOS)
VoiceOver on macOS/iOS
NVDA or JAWS with supportive e-readers on Windows
Thorium Reader (free, accessible EPUB reader)

Advanced Options for Better Accessibility:

pandoc document.docx -o accessible_math.epub --mathml --toc --toc-depth=2 --metadata lang=en --metadata title="Accessible Math" --metadata creator="Author Name" --css=accessible.css

--toc and --toc-depth=2 create a navigable table of contents
Language metadata ensures proper language identification for screen readers
Title and creator metadata improve discovery in e-reader libraries

Advanced Options for Math Accessibility

Using Templates

Templates can help ensure consistent, accessible output:

pandoc math_document.md -o math_document.html --template=accessible_template.html

Adding Document Metadata

Adding proper title, author, and other metadata improves accessibility:

pandoc math_document.md -o math_document.pdf --metadata title="Accessible Math Document" --metadata author="Your Name"

Converting Math to Speech Formats

For formats focused on speech output:

pandoc math_document.md -o math_document.ssml --to ssml

Examples of Math Content in Markdown

Here's how to write math in your Markdown files for optimal conversion:

Inline Math Example

The quadratic formula is $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$ which can be used to solve quadratic equations.

Display Math Example

The general solution for a linear differential equation is:

$$\frac{dy}{dx} + P(x)y = Q(x)$$

$$y = e^{-\int P(x) dx} \left( \int Q(x) e^{\int P(x) dx} dx + C \right)$$

Troubleshooting Common Issues

Error: "pandoc: command not found"

Solution: Ensure Pandoc is installed and that you've restarted your Terminal/Command Prompt after installation.

Math Not Rendering Correctly

Solution: Check your math syntax and ensure you're using the correct conversion options (like --mathjax or --mathml).

File Not Found Errors

Solution: Verify you're in the correct directory or use the full path to your files.

Getting Help

Run pandoc --help for a list of options
Visit the Pandoc documentation for comprehensive guidance
For math-specific questions, check the Pandoc Math documentation

Next Steps

After converting your documents, remember to verify the accessibility of the output using appropriate testing tools for the target format. Math content may require additional testing with screen readers that support mathematics, such as NVDA with the MathCAT plugin or JAWS with the MathCAT early adopter feature enabled.