Documentation reorg / edit suggestions + recommend use_pkgdown_github_pages() over use_pkgdown()

R/build-articles.R

@@ -173,7 +173,8 @@
 #' Additionally, htmlwidgets do not work when `as_is: true`.
 #'
 #' # Suppressing vignettes
-#' If you want articles that are not vignettes, either put them in
+#' If you want [articles](https://r-pkgs.org/vignettes.html#sec-vignettes-article)
+#'  that are not vignettes, use `usethis::use_article()` either put them in
 #' subdirectories or list in `.Rbuildignore`. 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

R/build-home.R

@@ -284,6 +284,7 @@
 #' ```
 #' @inheritParams build_articles
 #' @export
+#' @order 1
 build_home <- function(pkg = ".",
                        override = list(),
                        preview = NA,

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.

README.Rmd

@@ -69,7 +69,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 11,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 +88,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

README.md

@@ -84,7 +84,7 @@ Then learn about the many new ways to customise your site in
 
 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:
+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 +103,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.
 

pkgdown/_pkgdown.yml

@@ -9,9 +9,9 @@ authors:
   Maëlle Salmon:
     href: https://masalmon.eu
   Hadley Wickham:
-    href: http://hadley.nz
+    href: https://hadley.nz
   Posit Software, PBC:
-    href: https://www.posit.co
+    href: https://posit.co
     html: >-
       <img src='https://www.tidyverse.org/posit-logo.svg' alt='Posit' width='62' height='16' style="margin-bottom: 3px;" />
 
@@ -52,21 +52,22 @@ articles:
 
 reference:
 - title: Build
-  
+
 - subtitle: Build the complete site
   contents:
   - build_site
   - clean_site
   - preview_site
   - pkgdown_sitrep
-  
+
 - subtitle: Build part of a site
   desc: These functions are useful for rapid iteration when you're working on a
     specific part of your site.
   contents:
   - starts_with("build_")
   - -build_site
   - -build_site_github_pages
+  - -build_favicons
   - init_site
 
 - subtitle: Customisation
@@ -86,6 +87,7 @@ reference:
   - as_pkgdown
   - in_pkgdown
   - render_page
+  - build_favicons
 
 - title: Regression tests
   contents:

vignettes/pkgdown.Rmd

@@ -134,10 +134,12 @@ It just re-builds the index page, making it faster to quickly change `_pkgdown.y
 ## Articles
 
 pkgdown will automatically build all vignettes found in `vignettes/`, translating them to HTML files in `articles/`.
-Due to the way that pkgdown has to integrate RMarkdown generated HTML with its own HTML, relatively little control is available over the output format.
+It is recommended to name your intro article with your package name to generate a Get Started page automatically.
+
+Due to the way that pkgdown has to integrate R Markdown generated HTML with its own HTML, relatively little control is available over the output format.
 You can see the details in `?build_articles`.
 
-If you want to include an article on the website but not in the package (e.g., because it's large), you can either place it in a subdirectory of `vignettes/` (e.g. `vignettes/web_only`) or add it to `.Rbuildignore` (and make sure that there's no `vignettes:` section in the yaml header).
+If you want to include an article on the website but not in the package (e.g., because it's large), you can either place it in a subdirectory of `vignettes/` (e.g. `vignettes/web_only`) or add it to `.Rbuildignore` (and make sure that there's no `vignettes:` section in the yaml header). See `usethis::use_article()` for an automated way to do this.
 In the extreme case where you want to produce only articles but not vignettes, you should add the complete `vignettes/` directory to `.Rbuildignore` and ensure that DESCRIPTION does not have a `VignetteBuilder` field.
 
 ## News
@@ -168,10 +170,8 @@ See `?build_news` for more customisation options including how to:
 
 If you use GitHub, there are two ways to publish your site on GitHub Pages:
 
--   Build the site locally, check in the docs directory, then configure GitHub Pages to [use that directory](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site).
-
 -   Use GitHub actions to automatically build and publish the site every time you make a change.
-    The easiest way to set this up is to run `usethis::use_pkgdown_github_pages()`.
+    The easiest way to set this up is to run `usethis::use_pkgdown_github_pages()`, and if you need to customize the action, see [README.md r-lib/actions](https://github.com/r-lib/actions/tree/v2-branch/examples#build-pkgdown-site).
 
 ## Promoting
 
@@ -187,4 +187,4 @@ Once your finalized site is built and published on the web, you should publicize
 
     (`usethis::use_pkgdown_github_pages()` does this for you.)
 
-3.  On Twitter (make sure to include `#rstats`).
+3.  On social media (make sure to include `#rstats`).