Search code examples
markdownpandocrestructuredtext

pandoc converting reStructuredText to Markdown fails on headings

I try to convert a reStructuredText into Markdown using pandoc. But from my understanding pandoc does fail on the headings.

Here is an test.rst file

Heading 1
=========
one

Heading 2
---------
two

Heading 3
+++++++++
three

Now I use this command to convert it

pandoc test.rst -f rst -t markdown --output test.md

The result is

Heading 1
=========

one

Heading 2
---------

two

### Heading 3

This is IMHO not correct. What I would expect is this output

# Heading 1

one

## Heading 2

two

### Heading 3

I assume that pandoc is right and just my assumption are wrong. Can someone explain this?

Solution

  • What you are seeing are so-called “setext-style headings”, while those starting with a hash # are “ATX-style headings”. Older pandoc versions used setext-style as the default, but will switch to ATX-style if the --atx-headers command line option is given.

    Newer pandoc versions (2.11.2 and later) use ATX-style headings as default, and can switch to setext-style via --markdown-headings=setext, so updating to the latest version would help as well.