Customizing GFM markdown output in Pandoc

Question

I am trying to convert some .rst files to .md (GitHub flavoured markdown) using Pandoc.

I want to use # and ## instead of === and --- for headers and subheaders. I also want code samples to be in simple code fences and not with block quotes.

If I have the .rst sample on the left in a file called rst.rst, I get the markdown on the right by running pandoc rst.rst -t gfm - it uses the 'wrong' header style and adds a blockquote to the code sample.

How can I fix this? Do I need to write a custom lua filter?

Answer 1

To force ATX style headers, use the --markdown-headings=atx commandline option.

pandoc rst.rst -t gfm --markdown-headings=atx

To avoid the blockquote, remove the indentation from your rst code block. Note that a blockquote is represented by indenting a block of text in RestructuredText. Therefore, your code block is nested within a blockquote in your rst document and Pandoc is correctly replicating that document structure in the Markdown output.

$ echo "
> Header
> ======
>
> some text
>
> Subheader
> ---------
>
> A code sample
>
> .. sourcecode:: python3
>     :linenos:
>
>     class Hand(Deck):
>         pass
>
> More text" | pandoc -f rst -t gfm --markdown-headings=atx
# Header

some text

## Subheader

A code sample

``` python3
class Hand(Deck):
    pass
```

More text

Note that I get the same result without specifying the --markdown-headings option, which makes sense because ATX is documented to be the default. Perhaps you are using an older version of Pandoc, in which case you may need to use the now-deprecated --atx-headers instead. I used Pandoc version 2.11.4 to generate the example above.