CODEWITHSUNDEEP
githubmarkdownrestructuredtextgithub-flavored-markdown
orome
orome

Reputation: 48616

Can I "fix" heading levels in rST on GitHub?

On GitHub, in a .md file I'm able to specify heading levels that are respected in they way they are displayed on there, but my .rst files are not: the "highest" level heading is treated as a level 1 heading,

For example,

## Heading

Stuff

## Sub-heading

More stuff

in a .md will treat the first as a second-level heading and the second as a third-level heading, while its equivalent (e.g as generated by pandoc),

Heading
-------

Stuff

Sub-heading
~~~~~~~~~~~

More stuff

is treated as a first-level and second-level headings.

Is there a way to overcome this? Can I "fix" the heading level in rST, at as GitHub interprets it?

Upvotes: 1

Views: 571

Answers (1)

Waylan
Waylan

Reputation: 42685

No, this is not possible.

Docutils does not allow header levels to be skipped. In fact, it will crash hard on inconsistently nested levels. Additionally, here is no hard rule for which characters in the ReST syntax represent which level. It is simply assumed that they appear in the order they are found (the inconsistency comes when you step back up, then down again -- it is assumed that you use the same pattern going back down). Therefore, the first header is always a level 1 header (<h1>) regardless of which character you use. However, in Markdown the levels are explicit in the syntax. If a user starts with ### Header, then that first header in the document must be level 3 (<h3>). Under the hood, Docutils has no mechanism for retaining that info. It only knows whether a header is the "next higher" or "lower" level in consecutive order.

Upvotes: 4

Related Questions