r-lib · olivroy · Jun 6, 2024 · May 20, 2024 · May 20, 2024 · May 20, 2024
diff --git a/R/build-articles.R b/R/build-articles.R
@@ -173,13 +173,14 @@
 #' Additionally, htmlwidgets do not work when `as_is: true`.
 #'
 #' # Suppressing vignettes
-#' If you want articles that are not vignettes, either put them in
-#' subdirectories or list in `.Rbuildignore`. An articles link will be
+#' If you want [articles](https://r-pkgs.org/vignettes.html#sec-vignettes-article)
+#' that are not vignettes, use `usethis::use_article()` to create it. An articles link will be
 #' automatically added to the default navbar if the vignettes directory is
 #' present: if you do not want this, you will need to customise the navbar. See
 #' [build_site()] details.
 #'
 #' @inheritSection build_reference Figures
+#' @family site components
 #'
 #' @inheritParams as_pkgdown
 #' @param quiet Set to `FALSE` to display output of knitr and

diff --git a/R/build-favicons.R b/R/build-favicons.R
@@ -1,16 +1,17 @@
-#' Create favicons from package logo
+#' Initialise favicons from package logo
 #'
+#' @description
 #' This function auto-detects the location of your package logo (with the name
-#' `logo.svg` (recommended format) or `logo.png`) and runs it through the
-#' <https://realfavicongenerator.net> API to build a complete set of favicons
-#' with different sizes, as needed for modern web usage.
+#' `logo.svg` (recommended format) or `logo.png`, created with `usethis::use_logo()`)
+#' and runs it through the <https://realfavicongenerator.net> API to build a
+#' complete set of favicons with different sizes, as needed for modern web usage.
 #'
 #' You only need to run the function once. The favicon set will be stored in
 #' `pkgdown/favicon` and copied by [init_site()] to the relevant location when
 #' the website is rebuilt.
 #'
 #' Once complete, you should add `pkgdown/` to `.Rbuildignore ` to avoid a NOTE
-#' during package checking.
+#' during package checking. (`usethis::use_logo()` does this for you!)
 #'
 #' @inheritParams as_pkgdown
 #' @param overwrite If `TRUE`, re-create favicons from package logo.

diff --git a/R/build-home.R b/R/build-home.R
@@ -283,7 +283,9 @@
 #'   sidebar: FALSE
 #' ```
 #' @inheritParams build_articles
+#' @family site components
 #' @export
+#' @order 1
 build_home <- function(pkg = ".",
                        override = list(),
                        preview = NA,

diff --git a/R/build-news.R b/R/build-news.R
@@ -66,6 +66,7 @@
 #' news:
 #'   cran_dates: false
 #' ```
+#' @family site components
 #'
 #' @seealso [Tidyverse style for News](https://style.tidyverse.org/news.html)
 #'

diff --git a/R/build-reference.R b/R/build-reference.R
@@ -83,7 +83,7 @@
 #' * `has_lifecycle("deprecated")` will select all topics with lifecycle 
 #'   deprecated.
 #'
-#' All functions (except for `has_keywords()`) automatically exclude internal
+#' All functions (except for `has_keyword()`) automatically exclude internal
 #' topics (i.e. those with `\keyword{internal}`). You can choose to include
 #' with (e.g.) `starts_with("build_", internal = TRUE)`.
 #'
@@ -136,6 +136,7 @@
 #' as HTML widgets.
 #'
 #' @inheritParams build_articles
+#' @family site components
 #' @param lazy If `TRUE`, only rebuild pages where the `.Rd`
 #'   is more recent than the `.html`. This makes it much easier to
 #'   rapidly prototype. It is set to `FALSE` by [build_site()].

diff --git a/R/build-tutorials.R b/R/build-tutorials.R
@@ -26,6 +26,7 @@
 #'   url: https://jjallaire.shinyapps.io/learnr-tutorial-01-data-basics/
 #' ```
 #' @inheritParams build_articles
+#' @family site components
 #' @export
 build_tutorials <- function(pkg = ".", override = list(), preview = NA) {
   pkg <- section_init(pkg, depth = 1L, override = override)

diff --git a/R/build.R b/R/build.R
@@ -28,7 +28,7 @@
 #'    It specifies where the site will be published and is used to allow other
 #'    pkgdown sites to link to your site when needed (`vignette("linking")`),
 #'    generate a `sitemap.xml`, automatically generate a `CNAME` when
-#'    [deploying to github][deploy_site_github], generate the metadata needed
+#'    [deploying to github][build_site_github_pages()], generate the metadata needed
 #'    rich social "media cards" (`vignette("metadata")`), and more.
 #'
 #' *  `title` overrides the default site title, which is the package name.

diff --git a/R/init.R b/R/init.R
@@ -12,7 +12,7 @@
 #' display of your site.
 #'
 #' # Build-ignored files
-#' We recommend using [usethis::use_pkgdown()] to build-ignore `docs/` and
+#' We recommend using [usethis::use_pkgdown_github_pages()] to build-ignore `docs/` and
 #' `_pkgdown.yml`. If use another directory, or create the site manually,
 #' you'll need to add them to `.Rbuildignore` yourself. A `NOTE` about
 #' an unexpected file during `R CMD CHECK` is an indication you have not

diff --git a/README.Rmd b/README.Rmd
@@ -44,17 +44,19 @@ pak::pak("r-lib/pkgdown")
 Get started with [usethis](https://usethis.r-lib.org/):
 
 ```{r, eval = FALSE}
-# Run once to configure your package to use pkgdown
-usethis::use_pkgdown()
+# Run once to configure your package to use and deploy pkgdown
+usethis::use_pkgdown_github_pages()
 ```
 
-Then use pkgdown to build your website:
-
 ```{r, eval = FALSE}
+# Preview your site locally before publishing
 pkgdown::build_site()
 ```
 
-This generates a `docs/` directory containing a website. Your `README.md` becomes the homepage, documentation in `man/` generates a function reference, and vignettes will be rendered into `articles/`. Read `vignette("pkgdown")` for more details, and to learn how to deploy your site to GitHub pages.
+This adds the necessary components and sets up GitHub Actions[^1] for automatic site building when deploying.
+Your `README.md` becomes the homepage, documentation in `man/` generates a function reference, and vignettes will be rendered into `articles/`.
+
+[^1]: If you don't use GitHub, you can use `usethis::use_pkgdown()` + `pkgdown::build_site()` to create a website.
 
 ### pkgdown 2.0.0 and Bootstrap 5
 
@@ -69,7 +71,7 @@ Then learn about the many new ways to customise your site in `vignette("customis
 
 ## In the wild
 
-At last count, pkgdown is used [by over 11,000 packages](https://github.com/search?q=path%3A_pkgdown.yml+language%3AYAML&type=code&l=YAML). Here are a few examples created by contributors to pkgdown:
+At last count, pkgdown is used [by over 12,000 packages](https://github.com/search?q=path%3A_pkgdown.yml+language%3AYAML&type=code&l=YAML). Here are a few examples:
 
 * [bayesplot](http://mc-stan.org/bayesplot/index.html)
   ([source](https://github.com/stan-dev/bayesplot/tree/gh-pages)):
@@ -88,6 +90,8 @@ At last count, pkgdown is used [by over 11,000 packages](https://github.com/sear
   ([source](https://github.com/renozao/NMF)):
   a framework to perform non-negative matrix factorization (NMF).
 
+* [tidyverse and r-lib packages source](https://github.com/search?q=path%3A%22_pkgdown.yml%22+AND+%28org%3Atidyverse+OR+org%3Ar-lib%29&type=code)
+
 Comparing the source and output of these sites is a great way to learn new pkgdown techniques.
 
 ## Code of conduct

diff --git a/README.md b/README.md
@@ -48,21 +48,19 @@ pak::pak("r-lib/pkgdown")
 Get started with [usethis](https://usethis.r-lib.org/):
 
 ``` r
-# Run once to configure your package to use pkgdown
-usethis::use_pkgdown()
+# Run once to configure your package to use and deploy pkgdown
+usethis::use_pkgdown_github_pages()
 ```
 
-Then use pkgdown to build your website:
-
 ``` r
+# Preview your site locally before publishing
 pkgdown::build_site()
 ```
 
-This generates a `docs/` directory containing a website. Your
-`README.md` becomes the homepage, documentation in `man/` generates a
-function reference, and vignettes will be rendered into `articles/`.
-Read `vignette("pkgdown")` for more details, and to learn how to deploy
-your site to GitHub pages.
+This adds the necessary components and sets up GitHub Actions[^1] for
+automatic site building when deploying. Your `README.md` becomes the
+homepage, documentation in `man/` generates a function reference, and
+vignettes will be rendered into `articles/`.
 
 ### pkgdown 2.0.0 and Bootstrap 5
 
@@ -82,9 +80,9 @@ Then learn about the many new ways to customise your site in
 
 ## In the wild
 
-At last count, pkgdown is used [by over 11,000
+At last count, pkgdown is used [by over 12,000
 packages](https://github.com/search?q=path%3A_pkgdown.yml+language%3AYAML&type=code&l=YAML).
-Here are a few examples created by contributors to pkgdown:
+Here are a few examples:
 
 - [bayesplot](http://mc-stan.org/bayesplot/index.html)
   ([source](https://github.com/stan-dev/bayesplot/tree/gh-pages)):
@@ -103,6 +101,9 @@ Here are a few examples created by contributors to pkgdown:
   ([source](https://github.com/renozao/NMF)): a framework to perform
   non-negative matrix factorization (NMF).
 
+- [tidyverse and r-lib packages
+  source](https://github.com/search?q=path%3A%22_pkgdown.yml%22+AND+%28org%3Atidyverse+OR+org%3Ar-lib%29&type=code)
+
 Comparing the source and output of these sites is a great way to learn
 new pkgdown techniques.
 
@@ -111,3 +112,6 @@ new pkgdown techniques.
 Please note that this project is released with a [Contributor Code of
 Conduct](https://pkgdown.r-lib.org/CODE_OF_CONDUCT.html). By
 participating in this project you agree to abide by its terms.
+
+[^1]: If you don’t use GitHub, you can use `usethis::use_pkgdown()` +
+    `pkgdown::build_site()` to create a website.
diff --git a/man/build_articles.Rd b/man/build_articles.Rd
diff --git a/man/build_favicons.Rd b/man/build_favicons.Rd
diff --git a/man/build_home.Rd b/man/build_home.Rd
diff --git a/man/build_news.Rd b/man/build_news.Rd
diff --git a/man/build_reference.Rd b/man/build_reference.Rd
diff --git a/man/build_site.Rd b/man/build_site.Rd
diff --git a/man/build_tutorials.Rd b/man/build_tutorials.Rd
diff --git a/man/init_site.Rd b/man/init_site.Rd