Why do default R Markdown/Quarto templates use second-level headings instead of first-level ones?

[GegznaV]

I found that many of my students use second-level headers instead of first-level ones. Then I found out that even RStudio templates and several online courses teach that. I try to understand this phenomenon.

1. What are the reasons to use second-level headings ## instead of first-level ones # in the default R Markdown/Quarto templates? What is the logic behind it?
2. Is this a deliberate decision related to the structure of the document or just a habit to use ## (e.g., some people say that ## is more beautiful/readable than #? Is it the case here?)?
3. Isn't it a way to teach bad habits to new users? As the first should go before the second. When one uses numbered sections, starting with ## gives really unnatural result. If ## is needed to make the font smaller, doesn't this indicate, that the defaults are not optimal? Isn't it better to teach, e.g., some CSS for HTML output?

So I'd like some opinions here. Especially from the developers.

[technocrat]

It is a design choice reflecting several possible considerations

1. The original design of the HTML header elements i(h1 .. h6) in ancient times reflecting hardware and aesthetic environments that have become obsolete and/or gone out of fashion
2. Search engine optimization using metadata, for example, made headers less important
3. The ## default is easy enough to change manually for short uses, globally using CSS or by a custom template

The questions you raise pose a good teaching opportunity for new users around examining defaults and making deliberate decisions whether to accept them or give alternative treatments.

[phil_hummel]

The New Project | Quarto Book creates some pages with H1 headings and some with a Title. I thought the suggestion of H2 for template code was leaving the largest font for either the Title or an H1 heading in place of a title.

[cderv]

@GegznaV

What are the reasons to use second-level headings ## instead of first-level ones # in the default R Markdown/Quarto templates? What is the logic behind it?

I believe this comes from pre HTML5 design rule where only <h1> per documented made sense, for SEO and also document structure. Here is an article that gives some insights:

The Truth About Multiple H1 Tags in the HTML5 Era

title field of the document in R Markdown will often be used for a <h1>the most important header, as main title of the doc. So any other section in the document are supposed to be less important and underneath it. That is the logic behind the using second level section in document.

In some R Markdown format it does not matter a lot, but some of the formats will enforce that more striclty:

• distill_article() uses h1 for the main article title which is styled a certain way. h2 and lower level are then supposed to be used.
• revealjs will use ## for slide title, and # only to create some Title section slide - so usually in a simple presentation you would use only ##

@GegznaV

e.g., some people say that ## is more beautiful/readable than #? Is it the case here?)?

Nothing to do with style

Hope it helps understand the logic I think is behind this