Pandoc & Academic Guide · 10 min read

The Complete Guide to Pandoc Markdown Tables

Pandoc is the undisputed Swiss Army knife for academic research, book publishing, and technical documentation. Unlike standard GitHub Flavored Markdown, Pandoc supports 4 distinct table syntax models, automatic relative column width calculations, native caption cross-referencing, and direct compilation to LaTeX, PDF, and Microsoft Word.

1. The 4 Pandoc Table Syntaxes Explained

Depending on your document layout and whether you need multi-paragraph cells, Pandoc accepts four syntaxes:

A. Pipe Tables (Default GFM Compatible)Most Common

Familiar pipe syntax. Pandoc enables the pipe_tables extension by default in Pandoc Markdown.

| Sample ID | Temperature (°C) | Pressure (kPa) | Result |
| :-------- | ---------------: | -------------: | :----: |
| SMP-01    | 24.5             | 101.3          | Pass   |
| SMP-02    | 85.2             | 210.8          | Fail   |

B. Grid Tables (Multi-Paragraph & Lists in Cells)Block Elements

Uses + and - characters with = separating the header. Grid tables are the only format that allows bulleted lists, sub-paragraphs, and code spans inside cells.

+---------------+--------------------------------------+
| Feature       | Description & Implementation         |
+===============+======================================+
| Authentication| Supports OAuth2 and JWT:             |
|               |                                      |
|               | - GitHub OAuth                       |
|               | - Google Identity                    |
+---------------+--------------------------------------+
| Storage       | S3 bucket with multi-region backup.  |
+---------------+--------------------------------------+

C. Simple TablesMinimalist

Requires no vertical pipe boundaries. The position of dashes determines column boundaries and alignments.

  Right     Left     Center     Default
-------     ------ ----------   -------
     12     12        12            12
    123     123       123          123
      1     1          1             1

2. Adding Table Captions & Academic Cross-Referencing

In research papers and theses, tables must be numbered and referenced in the text (e.g. "as shown in Table 1"). Pandoc makes this effortless:

| Benchmark | Baseline (ms) | Optimized (ms) | Speedup |
| :-------- | ------------: | -------------: | ------: |
| Sort 100k | 142.5         | 38.2           | 3.73x   |
| Search 1M | 89.1          | 12.0           | 7.42x   |

Table: Algorithmic latency benchmarks across operations. {#tbl:benchmarks}

As demonstrated in @tbl:benchmarks, vectorizing the search operation
yielded an immediate 7.4x performance improvement.

When compiling with the --filter pandoc-crossref flag, Pandoc automatically numbers the table and generates hyperlinked citations in both PDF and HTML.

3. How Pandoc Calculates Column Widths in PDF & Word

A common frustration with Pandoc PDF export is text wrapping awkwardly across narrow columns. Pandoc determines relative column width percentages directly from the length of the hyphen separator row:

// 25% Width for Column 1, 75% Width for Column 2:

| Param | Description                                                 |
| :---- | :---------------------------------------------------------- |
| id    | Primary unique identifier generated via UUIDv4 for records. |

If you want columns to auto-fit to content without fixed percentage wrapping, keep the separator row dashes short (e.g. | :--- | :--- |) and ensure the entire table line length is under 80 characters.

4. Command-Line Compilation to PDF & Word

Here are the battle-tested command-line flags to compile your Markdown tables into production-ready PDFs:

# Compile to PDF via XeLaTeX with custom margins

pandoc paper.md -o paper.pdf --pdf-engine=xelatex -V geometry:margin=1in

# Compile with automatic table numbering & cross-references

pandoc report.md -o report.pdf --filter pandoc-crossref --pdf-engine=xelatex

# Export to Microsoft Word (.docx) with native Word tables

pandoc specification.md -o specification.docx

5. Frequently Asked Questions

What are the 4 table formats supported by Pandoc?

Pandoc natively supports: (1) Pipe tables (standard GFM syntax with vertical bars), (2) Simple tables (dashed underlines under headers without vertical pipes), (3) Multiline tables (headers and rows spanning multiple lines delimited by dashed borders), and (4) Grid tables (box-drawing with + and - characters supporting multi-paragraph blocks inside cells).

How do I add a caption and label to a Pandoc Markdown table for cross-referencing?

Add "Table: Your Caption Title {#tbl:myid}" immediately following the table. When compiling with the pandoc-crossref filter, you can reference the table in your text using "@tbl:myid" to generate automated numbered citations (e.g. "Table 1").

How does Pandoc calculate column widths in PDF output?

Pandoc calculates relative column widths from the length of the separator row hyphens relative to the total line length. If column 1 has 20 hyphens and column 2 has 80 hyphens, Pandoc allocates 20% width to column 1 and 80% to column 2 in LaTeX / PDF rendering.

How do I compile Markdown tables into a professional PDF using Pandoc?

Run: "pandoc input.md -o output.pdf --pdf-engine=xelatex -V geometry:margin=1in". Pandoc uses the LaTeX longtable and booktabs packages under the hood to handle multi-page table splits automatically.

Can I put bulleted lists and paragraphs inside Pandoc table cells?

Yes, but you must use Pandoc Grid tables (with +---+---+ borders). Standard pipe tables do not support raw newlines or block elements inside cells, whereas Grid tables allow paragraphs, bullet lists, and code blocks.

Need to convert between Markdown, LaTeX, and CSV?

Export your tables to LaTeX \\begin{tabular} or format ragged pipes instantly.

Markdown to LaTeX Table Formatter