Clarify README/index building

No longer fallback to .Rmds, if .md not found (as documented)

Fixes #1136. Closes #1140.

NEWS.md

@@ -1,5 +1,8 @@
 # pkgdown (development version)
 
+* `build_home()` no longer uses (unrendered) `README.Rmd` or `index.Rmd` if
+  corresponding `.md` files are not found.
+
 * You can have much richer control over Open Graph and Twitter metadata for 
   the site as the whole, and for individual articles. See `vignette("metadata")`
   for details (@gadenbuie, #936).
@@ -27,8 +30,8 @@
 * pkgdown now uses the ORCiD logo included in Font Awesome 5.11 instead of 
   querying it from members.orcid.org (@bisaloo, #1153)
 
-* `build_home()` now looks for `pkgdown/index.md` and `pkgdown/index.Rmd` in
-  addition to the top-level `index` or `README` files (@nteetor, #1184)
+* `build_home()` now looks for `pkgdown/index.md` in addition to the top-level 
+  `index` or `README` files (@nteetor, #1031)
 
 * New `deploy_to_branch()` function to build and deploy a site to a branch,
   defaulting to `gh-pages` to use with GitHub Pages. (@jimhester, #1221)
@@ -63,9 +66,9 @@
     library, and runs examples/articles in a new process.
 
 * `build_reference()` no longer runs `devtools::document()` (#1079) and
-  `build_home()` no longer re-builds `README.Rmd`.  This makes the scope 
-  of responsibility of pkgdown more clear: it now only creates/modifies 
-  files in `doc/`.
+  `build_home()` no longer re-builds `README.Rmd` or `index.Rmd`. This makes 
+  the scope of responsibility of pkgdown more clear: it now only 
+  creates/modifies files in `doc/`.
 
 * `build_home()` now strips quotes from `Title` and `Description` fields 
   when generating page metadata. Additionally, you can now override the 

R/build-home-index.R

@@ -7,11 +7,8 @@ build_home_index <- function(pkg = ".", quiet = TRUE) {
   src_path <- path_first_existing(
     pkg$src_path,
     c("pkgdown/index.md",
-      "pkgdown/index.Rmd",
       "index.md",
-      "README.md",
-      "index.Rmd",
-      "README.Rmd"
+      "README.md"
     )
   )
   dst_path <- path(pkg$dst_path, "index.html")

R/build-home.R

@@ -1,11 +1,20 @@
 #' Build home section
 #'
-#' This function generates the home page, and converts other `.md` files
-#' typically found in the package root and in `.github/`. It generates the home
-#' page from  `index.md` or `README.md`, falling back to the description field
-#' in `DESCRIPTION` if neither is found. It also builds an authors page
-#' from the `DESCRIPTION` and `inst/CITATION` (if present) and
-#' a license page, and converts any `.md` files found in
+#' 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: