Heading inconsistency makes it hard to share Rmd fragments between .Rd and .Rmd

[hadley]

.Rmd usually have one <h1> at the top of the doc, and sections use <h2>, but .Rd roxygen markup uses # for section headings.

[gaborcsardi]

OTOH it seems like a waste to use a single <h1> as the title in an Rmd, there is already a title after all? But if most .Rmds are like that then I guess we'll have to accept that.

[hadley]

pkgdown does something like this if the contents contain more than one h1:

tweak_section_levels <- function(html) {
  sections <- xml2::xml_find_all(html, ".//div[contains(@class, 'section level')]")

  # Update headings
  xml2::xml_set_name(xml2::xml_find_all(sections, ".//h5"), "h6")
  xml2::xml_set_name(xml2::xml_find_all(sections, ".//h4"), "h5")
  xml2::xml_set_name(xml2::xml_find_all(sections, ".//h3"), "h4")
  xml2::xml_set_name(xml2::xml_find_all(sections, ".//h2"), "h3")
  xml2::xml_set_name(xml2::xml_find_all(sections, ".//h1"), "h2")

  # Update section
  xml2::xml_attr(sections, "class") <- paste0("section level", get_section_level(sections) + 1)

  invisible()
}

[hadley]

I'm no longer convinced of general utility of @includeRmd.