Customize Markdown conversions with Pandoc

Learn to fine-tune Markdown conversions with Pandoc.

Pandoc is an excellent and widely-used tool for, among many other things, converting HTML to Markdown. But by default, Pandoc uses a variant of Markdown that has an extension for tables and lots of other unusual syntax. What if you want to use standard HTML tables? Pandoc can still give you the output you want.

Pandoc’s uncommon defaults

Suppose you have input like this:

<table>
  <thead>
    <tr>
      <td>Key</td>
      <td>Value</td>
    </tr>
  </thead>
  <tr>
    <td>Name</td>
    <td>Daniel</td>
  </tr>
</table>

And you invoke Pandoc like this:

$ pandoc --from html --to markdown example.html

Then you’ll get Markdown that uses table formatting like this:

Key Value
--- ---
Name Daniel

For the simplest tables this is tolerable to read and edit, but it’s not very portable. This is one of several oddities of Pandoc’s “enhanced version of Markdown” that is uncommon to widely-used Markdown variants, including CommonMark or GitHub Flavored Markdown.

Opting out, in whole or in part

I prefer HTML tables and portability. Thankfully you can opt out of this behavior by explicitly choosing a Markdown that’s more widely used and doesn’t have a tables extension, such as CommonMark:

$ pandoc --from html --to commonmark example.html

Alternatively, you can compose a custom format by turning on or off that format’s extensions. For example, suppose you want to convert to GitHub Flavored Markdown (GFM), but you don’t want GFM’s awful tables syntax in your Markdown source.

First, get the format’s list of possible extensions:

$ pandoc --list-extensions gfm

This prints out a very long list of things that Pandoc can vary about GFM, including +pipe_tables. The + marks extensions that are turned on, with - as turned off.

Next, run the conversion with that extension turned off, using the - notation, like this:

$ pandoc --from html --to gfm-pipe_tables example.html

This preserves the original tables and your patience for editing them in the future.