Why use the h1 heder for each version of the NEWS.md?

[eitsupi]

Currently when NEWS files are updated by usethis uses h1 # for the heading of each version.

usethis/R/news.R

Lines 36 to 59 in 709f825

 use_news_heading <- function(version) { 
   news_path <- proj_path("NEWS.md") 
   if (!file_exists(news_path)) { 
     return(invisible()) 
   } 
  
   news <- read_utf8(news_path) 
   title <- glue("# {project_name()} {version}") 
  
   if (title == news[[1]]) { 
     return(invisible()) 
   } 
  
   development_title <- glue("# {project_name()} (development version)") 
   if (development_title == news[[1]]) { 
     news[[1]] <- title 
  
     ui_done("Replacing development heading in NEWS.md") 
     return(write_utf8(news_path, news)) 
   } 
  
   ui_done("Adding new heading to NEWS.md") 
   write_utf8(news_path, c(title, "", news)) 
 } 

But normally h1 is supposed to be used one for each page, wouldn't it be more natural to use h2?
Do you think it is worth having such an option to at least use h2 ##?

[Jennifer (Jenny) Bryan]

I don't really know why h1 was chosen here, but I think it would be pretty painful to do anything else at this point. There is code in usethis and pkgdown, just for starters, I imagine, that is built around this assumption.

@hadley do you have any observations?

[Hadley Wickham]

Yeah h2 is arguably more correct, but it’s too late to change now.

[eitsupi]

Would you add an opt-in option to use h2 headers, as having multiple h1 headers may cause various tools to not work well.

[Hadley Wickham]

This is going to be a bunch of work for us, so you'd need to provide compelling evidence that this is worth it.