Down-level headings in markdown files

[cameron-martin]

Currently when headings are rendered in markdown files, they are rendered as-is (i.e. an h1 in a markdown file gets rendered as an h1 in the styleguide). However, the sections titles also use headings, so you can get strange behaviour such as an h1 being rendered inside a section with an h3 title, when it should be an h4.

A solution to this is to just start the headings in the markdown files at the appropriate size, but this gets tedious to update when moving sections around (i.e. moving a top-level section to a sub-section).

It would be nice if the headings in the markdown were automatically "down-levelled", I.e. h1 elements inside a markdown file inside a section with an h3 heading were converted to h4 elements.

[sapegin]

It would be nice if the headings in the markdown were automatically "down-levelled", I.e. h1 elements inside a markdown file inside a section with an h3 heading were converted to h4 elements.

It won’t work because you may have nested section which is another issue with heading levels ;-) Any help or ideas how to fix all at once are very appreciated.

[cameron-martin]

You mean in this case:

- Section
- - Markdown file
- - Subsection
- - - Markdown file

where you have a subsection adjacent to a markdown file?

[sapegin]

Yup!

[cameron-martin]

It would probably be acceptable to have:

- Section heading (h1)
- - Markdown heading (h2, down-levelled from h1)
- - Subsection heading (h2)
- - - Markdown heading (h3, down-levelled from h1)

[wachunga]

This seems like a reasonable approach to me. I've encountered this problem as well.