pandoc: Convert GitHub-flavoured MarkDown containing mixed html and markdown to html

Question

My markdown was created according to the style from this top-result cheatsheet with HTML directives, using this commmand:

pandoc -f gfm -t html --atx-headers -s -o out.html in.md

However, the generated html always ignores titles that contains the following HTML code above them, leaving tons of ###, #### in my output HTML. My titles look like these:

# H1

<a name=toc-anchor-h2 />
## H2

<a name=toc-anchor-h3 />
### H3

<a name=toc-anchor-h4 />
#### H4

Then H1 works fine, but the # in the rest levels are all seen by pandoc as plain text. How should I solve this problem?

Waylan Waylan · Accepted Answer · 2018-05-25T15:36:46

The headers must be preceded by a blank line. The missing blank line is causing the Markdown parser to not recognize them as headers. Therefore, edit your document to the following:

# H1

<a name=toc-anchor-h2 />

## H2

<a name=toc-anchor-h3 />

### H3

<a name=toc-anchor-h4 />

#### H4

Of, if you are concerned that that moves the anchors too far away from the intended target, include them inline:

# H1


## <a name=toc-anchor-h2 />H2


### <a name=toc-anchor-h3 />H3


#### <a name=toc-anchor-h4 />H4

Or, as you are using Pandoc, you could use one of the many Pandocs extensions which assigns identifiers directly to each header.

As it turns out, Pandoc's gfm variant of Markdown (which you are using) already includes the auto_identifiers extension. As the name implies, the auto_identifiers extension will cause id attributes to be auto-generated for every header. As a reminder, assigning an id attribute to an HTML element has the same effect as defining an anchor; you can link to either with a hash fragment. Therefore, you could simply remove your anchors and use the auto-generated ids which have already been assigned to the headers themselves.

However, if you would like to define your own custom id attributes for each header, then you may want to enable the header_attributes extension and alter your Markdown as follows:

# H1

## H2 {#toc-anchor-h2}

### H3 {#toc-anchor-h3}

#### H4 {#toc-anchor-h4}

which would generate the following HTML:

<h1 id="h1">H1</h1>
<h2 id="toc-anchor-h2">H2</h2>
<h3 id="toc-anchor-h3">H3</h3>
<h4 id="toc-anchor-h4">H4</h4>

Note that the "H1" header has an auto id assigned (based upon the text content of the element), while the remaining headers have the custom ids assigned to them.

One word of caution regarding the header_attributes extension: The syntax for defining the custom ids is non-standard and not supported by most Markdown implementations. If you want portable Markdown, then you should probably stick to the auto-generated ids as that does not require any non-standard markup in your documents.

Update: Note that according to the docs, the header_attributes extension is not compatible with gfm. Therefore, you wouldn't be able to use that extension. However, you get auto_identifiers by default. If you want custom identifiers, the you would need to use the custom raw HTML anchors. Of course that gives you the added benefit of a portable Markdown document.

pandoc: Convert GitHub-flavoured MarkDown containing mixed html and markdown to html

1 Answers