#' Build home section
#'
#' This function generates the home page, converts `.md` files found in the
#' package root (and in `.github/`), and builds an authors page from
#' `DESCRIPTION` and `inst/CITATION` (if present).
#'
#' @section Home page:
#' The home page (`index.html`) is generated from `_pkgdown/index.md`,
#' `index.md`, or `README.md`, in that order. Most packages will use `README.md`
#' because that's also displayed by GitHub and CRAN. Use `index.md` if you want
#' your package website to look different to your README, and use
#' `_pkgdown/index.md` if you don't want that file to live in your package
#' root directory.
#'
#' If you use `index.Rmd` or `README.Rmd` it's your responsibility to knit
#' the document to create the corresponding `.md`. pkgdown does not do this
#' for you because it only touches files in the `doc/` directory.
#'
#' @section Sidebar:
#' The sidebar is automatically populated with:
#'
#' *   Development status badges found in `README.md`/`index.md`. pkgdown
#'     identifies badges in three ways:
#'
#'     * Any image-containing links between `<!-- badges: start -->` and
#'       `<!-- badges: end -->`, as e.g. created by `usethis::use_readme_md()`
#'       or `usethis::use_readme_rmd()`.
#'
#'     * Any image-containing links within `<div id="badges"></div>`.
#'
#'     * Within the first paragraph, if it only contains image-containing links.
#'
#' *   A link for bug reports is added if the `BugReports` field in
#'     `DESCRIPTION` contains a link. You can use `usethis::use_github_links()`
#'     to populate this field.
#'
#' *   Licensing information if `LICENSE`/`LICENCE` or `LICENSE.md`/`LICENCE.md`
#'     files are present.
#'
#' *   Community information is linked in the side bar using the
#'     `.github/CONTRIBUTING.md` and `.github/CODE_OF_CONDUCT.md` files,
#'     if present.
#'
#' *   Extra markdown files in the base directory or in `.github/` are copied
#'     to `docs/` and converted to HTML.
#'
#' *   Citation information from a `inst/CITATION` file is linked in the side bar
#'     to the [authors page](https://testthat.r-lib.org/authors.html).
#'
#' *   Author ORCID identification numbers in the `DESCRIPTION` are linked under
#'     "Developers" using the ORCID logo:
#'
#'     ```
#'     Authors@R: c(
#'         person("Hadley", "Wickham", , "hadley@rstudio.com", role = c("aut", "cre"),
#'           comment = c(ORCID = "0000-0003-4757-117X")
#'         ),
#'         person("Jay", "Hesselberth", role = "aut",
#'           comment = c(ORCID = "0000-0002-6299-179X")
#'         )
#'       )
#'     ```
#'
#' @section Images and figures:
#' If you want to include images in your `README.md`, they must be stored
#' somewhere in the package so that they can be displayed on the CRAN website.
#' The best place to put them is `man/figures`. If you are generating figures
#' with R Markdown, make sure you set up `fig.path` as followed:
#'
#' ```
#' knitr::opts_chunk$set(
#'   fig.path = "man/figures/"
#' )
#' ```
#'
#' This should usually go in a block with `include = FALSE`.
#'
#' @section Package logo:
#' If you have a package logo, you can include it at the top of your README in a
#' level-one heading:
#'
#' ```
#' # pkgdown <img src="man/figures/logo.png" align="right" />
#' ```
#'
#' [init_site()] will also automatically create a favicon set from your package
#' logo.
#'
#' @section YAML config - home:
#' To tweak the home page, you need a section called `home`.
#'
#' By default, the page title and description are extracted automatically
#' from the `Title` and `Description` fields `DESCRIPTION` (stripping
#' single quotes off quoted words). CRAN ensures that these fields don't contain
#' phrases like "R package" because that's obvious on CRAN. To make your
#' package more findable with google, it's good practice to override the
#' `title` and `description`, thinking about what people might search for:
#'
#' ```
#' home:
#'   title: An R package for pool-noodle discovery
#'   description: >
#'     Do you love R? Do you love pool-noodles? If so, you might enjoy
#'     using this package to automatically discover and add pool-noodles
#'     to your growing collection.
#' ```
#'
#' (Note the use of YAML's `>`; this is a convenient way of writing paragraphs
#' of text.)
#'
#' The sidebar links are automatically generated by inspecting the `URL` and
#' `BugReports` fields of the `DESCRIPTION`. You can add additional links with a
#' subsection called `links`, which should contain a list of `text` + `href`
#' elements:
#'
#' ```
#' home:
#'   links:
#'   - text: Link text
#'     href: http://website.com
#' ```
#'
#' READMEs usually start with an `<h1>` containing the package name. If
#' that feels duplicative with the package name in the navbar you can
#' remove it with `strip_header: true`:
#'
#' ```
#' home:
#'   strip_header: true
#' ```
#'
#' @section YAML config - authors:
#' The "developers" list is populated by the maintainer ("cre"), authors
#' ("aut"), and funder ("fnd") from the `DESCRIPTION`. You can modify their
#' display on the home page by adding a subsection for `authors`. Each entry
#' in `authors` should be named with the author's name (matching `DESCRIPTION`)
#' and can contain `href` and/or `html` fields:
#'
#' * If `href` is provided, the author's name will be linked to this url.
#' * If `html` is provided, it will be shown instead of the author's name.
#'   This is particularly useful if you want to display the logo of a corporate
#'   sponsor.
#'
#' ```
#' authors:
#'   firstname lastname:
#'     href: "http://name-website.com"
#'     html: "<img src='name-picture.png' height=24>"
#' ```
#' @inheritParams build_articles
#' @export
build_home <- function(pkg = ".",
                       override = list(),
                       preview = NA,
                       quiet = TRUE) {

  pkg <- section_init(pkg, depth = 0L, override = override)
  rule("Building home")
  dir_create(pkg$dst_path)

  if (has_citation(pkg$src_path)) {
    build_citation_authors(pkg)
  } else {
    build_authors(pkg)
  }
  build_home_md(pkg)
  build_home_license(pkg)
  build_home_index(pkg, quiet = quiet)

  preview_site(pkg, "/", preview = preview)
}