From Pandoc to Quarto: Building a “Formulas, Charts, and Code–Friendly” Document Workflow

In today’s era of information overload, creating documents that are beautiful, consistent, and portable across multiple formats is a constant challenge.

How do you take a simple Markdown file and turn it into a polished Word report, a LaTeX-style PDF, or even a blog-ready HTML page—complete with math formulas, flowcharts, syntax-highlighted code, and well-styled tables?

The answer often comes down to two powerful tools: Pandoc and Quarto.

In this guide, we’ll break down what these tools are, how they differ, and how to use them effectively in your workflow.

1. Why Do You Need Pandoc?

A common beginner question is:

“Can’t I just use Word? Why bother with Pandoc?”

👉 Fair question. The difference is:

• Word is an editor. It saves files in its own format.
• Pandoc is a universal document conversion engine. It can take input in one format and output it in many others.

Pandoc can convert between dozens of file types, including:

• Markdown → Word (.docx)
• Markdown → LaTeX/PDF
• Markdown → HTML (for websites)
• Markdown → EPUB (eBooks)
• Markdown → ODT, RTF, and many others

📌 Use cases for Pandoc:

• Academics: Convert Markdown papers into LaTeX + PDF with perfect equation rendering.
• Developers: Turn Markdown project docs into HTML sites.
• Business users: Export clean Word reports from Markdown without breaking formatting.

In short: Pandoc is like FFmpeg, but for documents.

2. What Is Quarto? How Does It Relate to Pandoc?

Newcomers often ask:

“Wait, isn’t Quarto just a wrapper around Pandoc?”

The answer: Yes and no.

Think of the relationship like this:

• Pandoc = Engine (the raw power of document conversion).
• Quarto = Vehicle + Dashboard (a higher-level framework that uses Pandoc under the hood, with extra features).

Quarto’s advantages:

• Native support for data analysis reports (Markdown + executable code in R, Python, Julia, Observable JS).
• Built-in math rendering (LaTeX / MathJax).
• Mermaid diagrams for flowcharts and graphs.
• One-click rendering of Jupyter Notebooks into Word/PDF/HTML.

If Pandoc is the Swiss Army knife, Quarto is the all-in-one publishing platform built on top of it.

3. Installation Guide: Setting Up Pandoc and Quarto

Here’s how to get both tools running smoothly.

1. Install Pandoc

• macOS (via Homebrew):

  brew install pandoc
  

• Linux (Debian/Ubuntu):

  sudo apt-get install pandoc
  

• Windows: Download the installer from Pandoc’s official site.

Verify installation:

pandoc -v

2. Install Quarto

• macOS:

  brew install --cask quarto
  

• Windows/Linux: Download from Quarto’s website.

Verify installation:

quarto --version

4. Real-World Workflow: Markdown → Word/PDF/HTML

Let’s say you’ve written a mydoc.md file that includes math formulas, code blocks, a Mermaid diagram, and a table.

Example Markdown (mydoc.md)

# My Report

## Math Formula
Einstein’s mass–energy equivalence:
$$ E = mc^2 $$

## Code Block
```python
def hello():
    print("Hello, Pandoc & Quarto!")

Mermaid Diagram

graph TD
  A[Input] --> B[Processing]
  B --> C[Output]

Table

---

### Using Pandoc

1. Convert to **Word**:
   ```bash
   pandoc mydoc.md -o mydoc.docx

2. Convert to PDF (requires LaTeX, e.g. TeX Live):

   pandoc mydoc.md -o mydoc.pdf
   

3. Convert to HTML:

   pandoc mydoc.md -o mydoc.html
   

Using Quarto

If your file is mydoc.qmd instead of .md, you can render directly:

1. To Word:

   quarto render mydoc.qmd --to docx
   

2. To PDF:

   quarto render mydoc.qmd --to pdf
   

3. To HTML:

   quarto render mydoc.qmd --to html
   

⚠️ Common error:
ERROR: No valid input files passed to render

• Ensure the file extension is .qmd (not .md).
• Double-check the file is in your current working directory.

5. FAQ: Common Beginner Questions

Q1. Why don’t equations display correctly in Word?

• Word uses Office MathML. If formatting breaks, export to PDF for best results.

Q2. Can Mermaid diagrams show up in Word?

• Not natively.

  • Option 1: Render to HTML with Quarto.
  • Option 2: Export Mermaid → PNG, then insert into Word.

Q3. Why did my syntax highlighting disappear?

• Use Pandoc’s --highlight-style flag, e.g.:

  pandoc mydoc.md --highlight-style=pygments -o mydoc.pdf
  

Q4. Can I make an eBook from Markdown?

• Yes, with EPUB:

  pandoc mydoc.md -o book.epub
  

6. Knowledge Graph: Pandoc vs Quarto Ecosystem

Related concepts (Wikipedia):

• LaTeX — Scientific publishing standard
• Markdown — Lightweight markup language
• MathJax — Web-based math rendering
• Mermaid — Text-to-diagram engine

7. Final Thoughts: Which Should You Use?

• If you’re a document conversion enthusiast → Pandoc alone may be enough.

• If you’re a researcher, data analyst, or blogger → Quarto is the better fit.

• If you want the best of both worlds:

  • Write in Markdown
  • Render with Quarto
  • Let Pandoc handle the heavy lifting under the hood

🎯 Best practice workflow:
Markdown + Quarto + Pandoc = one-click, multi-format publishing pipeline

✅ In one sentence:

Pandoc is the “translator” of the document world, while Quarto is the “stage manager.”
One solves the format problem, the other solves the publishing problem.
Together, they give you a professional, AI-friendly document workflow.