Merge branch 'main' into reference-title

NEWS.md

@@ -1,11 +1,16 @@
 # pkgdown (development version)
 
 * The title for the "Reference" page is now "Package index" since this page might contain more than just function details (#2181).
+* Anywhere you can use `_pkgdown.yml`, you can now use `_pkgdown.yaml` (#2244).
+* pkgdown no longer overrides the default selection colours. This improves accessibility for users who have set their own colours in their browser settings (#2139, @glin).
+* `build_article()` now escapes html characters in the title (#2286).
+* `build_article()` no longer generates the wrong source link when you build your site outside of the root directory (#2172).
 * `build_reference()` matches usage for S3 and S4 methods to the style used by R 4.0.0 and later (#2187).
 * `<source>` tags now have their `srcref` attributes tweaked in the same way that the `src` attributes of `<img>` tags are (#2402).
 * New translation for "Search site", the label applied to the search box for screenreaders. This was previously incorrectly labelled as "Toggle navigation" (#2320).
 * You can now choose where the search box is placed with the "search" navbar component. This has been documented for a very long time, but as far as I can tell, never worked (#2320). If you have made your own template with a custom `navbar`, you will need to remove the `<form>` with `role="search"` to avoid getting two search boxes.
 * The mobile version of pkgdown sites no longer has a scrollburglar (a small amount of horizontal scroll) (#2179, @netique).
+* The `template.bslib` item now also accepts a `bootswatch` key (@gadenbuie, #2483).
 
 # pkgdown 2.0.9
 

R/build-articles.R

@@ -174,6 +174,9 @@ build_articles <- function(pkg = ".",
                            override = list(),
                            preview = NA) {
   pkg <- section_init(pkg, depth = 1L, override = override)
+  check_bool(quiet)
+  check_bool(lazy)
+  check_number_whole(seed, allow_null = TRUE)
 
   if (nrow(pkg$vignettes) == 0L) {
     return(invisible())
@@ -182,14 +185,14 @@ build_articles <- function(pkg = ".",
   cli::cli_rule("Building articles")
 
   build_articles_index(pkg)
-  purrr::walk(
+  unwrap_purrr_error(purrr::walk(
     pkg$vignettes$name,
     build_article,
     pkg = pkg,
     lazy = lazy,
     seed = seed,
     quiet = quiet
-  )
+  ))
 
   preview_site(pkg, "articles", preview = preview)
 }
@@ -248,10 +251,10 @@ build_article <- function(name,
   as_is <- isTRUE(purrr::pluck(front, "pkgdown", "as_is"))
 
   default_data <- list(
-    pagetitle = front$title,
+    pagetitle = escape_html(front$title),
     toc = toc <- front$toc %||% TRUE,
     opengraph = list(description = front$description %||% pkg$package),
-    source = repo_source(pkg, path_rel(input, pkg$src_path)),
+    source = repo_source(pkg, input),
     filename = path_file(input),
     output_file = output_file,
     as_is = as_is
@@ -297,7 +300,8 @@ build_article <- function(name,
     output_options = options,
     seed = seed,
     new_process = new_process,
-    quiet = quiet
+    quiet = quiet,
+    call = quote(build_article())
   )
 }
 

R/build-home.R

@@ -14,15 +14,278 @@
 #' `build_home_index()` rebuilds just the index page; it's useful for rapidly
 #' iterating when experimenting with site styles.
 #'
-#' ```{r child="man/rmd-fragments/home-configuration.Rmd"}
+#' # Home page
+#' 
+#' The main content of 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.
+#' 
+#' Extra markdown files in the base directory (e.g. `ROADMAP.md`) or in 
+#' `.github/` (e.g. `CODE_OF_CONDUCT.md`) are copied by `build_home()` to `docs/` and converted to HTML.
+#' 
+#' The home page also features a sidebar with information extracted from the 
+#' package. You can tweak it via the configuration file, to help make the home 
+#' page an as informative as possible landing page.
+#' 
+#' ## 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:
+#' 
+#' ``` r
+#' knitr::opts_chunk$set(
+#'   fig.path = "man/figures/"
+#' )
 #' ```
-#' ```{r child="man/rmd-fragments/authors-configuration.Rmd"}
+#' 
+#' This should usually go in a chunk with `include = FALSE`.
+#' 
+#' ```` markdown
+#' ```{r chunk-name, include=FALSE}`r ''`
+#' knitr::opts_chunk$set(
+#'   fig.path = "man/figures/"
+#' )
 #' ```
-#'
-#' @section Sidebar:
-#' ```{r child="man/rmd-fragments/sidebar-configuration.Rmd"}
+#' ````
+#' 
+#' ## Package logo
+#' 
+#' If you have a package logo, you can include it at the top of your README
+#' in a level-one heading:
+#' 
+#' ``` markdown
+#' # pkgdown <img src="man/figures/logo.png" align="right" />
+#' ```
+#' 
+#' [init_site()] will also automatically create a favicon set from your package logo.
+#' 
+#' ## YAML config - home
+#' 
+#' To tweak the home page, you need a section of the configuration file called 
+#' `home`.
+#' 
+#' ### Page title and description
+#' 
+#' 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 on search engines, it's good practice to override the `title` and 
+#' `description`, thinking about what people might search for:
+#' 
+#' ```yaml
+#' 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 `>` i.e. "YAML pipes"; this is a convenient way of writing paragraphs of text.)
+#' 
+#' ## Dev badges
+#' 
+#' 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()`. There should always be an empty line after 
+#'     the `<!-- badges: end -->` line. If you divide badges into paragraphs, 
+#'     make sure to add an empty line before the `<!-- badges: end -->` line.
+#' 
+#' -   Any image-containing links within `<div id="badges"></div>`.
+#' 
+#' -   Within the first paragraph, if it only contains image-containing links.
+#' 
+#' Identified badges are **removed** from the _main content_.
+#' They are shown or not in the _sidebar_ depending on the development mode and
+#' sidebar customization, see the sidebar section.
+#' 
+#' # Authors
+#' 
+#' By default, pkgdown will display author information in three places:
+#' 
+#' * the sidebar,
+#' * the left part side of the footer,
+#' * the author page.
+#' 
+#' This documentation describes how to customise the overall author display. 
+#' See `?build_home` and `?build_site` for details about changing the location 
+#' of the authors information within the home sidebar and the site footer.
+#' 
+#' ## Authors ORCID and bio
+#' 
+#' Author ORCID identification numbers in the `DESCRIPTION` are linked using 
+#' the ORCID logo:
+#' 
+#' ```r
+#' Authors@R: c(
+#'     person("Hadley", "Wickham", , "[email protected]", role = c("aut", "cre"),
+#'       comment = c(ORCID = "0000-0003-4757-117X")
+#'     ),
+#'     person("Jay", "Hesselberth", role = "aut",
+#'       comment = c(ORCID = "0000-0002-6299-179X")
+#'     )
+#'   )
+#' ```
+#' 
+#' If you want to add more details about authors or their involvement with the 
+#' package, you can use the comment field, which will be rendered on the 
+#' authors page.
+#' 
+#' ```r
+#' Authors@R: c(
+#'     person("Hadley", "Wickham", , "[email protected]", role = c("aut", "cre"),
+#'       comment = c(ORCID = "0000-0003-4757-117X", "Indenter-in-chief")
+#'     ),
+#'     person("Jay", "Hesselberth", role = "aut",
+#'       comment = c(ORCID = "0000-0002-6299-179X")
+#'     )
+#'   )
+#' ```
+#' 
+#' ## YAML config - authors
+#' 
+#' You can tweak a few things via the `authors` YAML field:
+#' 
+#' * display of each author in the footer, sidebar and authors page,
+#' * which authors (by role) are displayed in the sidebar and footer,
+#' * text before authors in the footer, 
+#' * text before and after authors in the sidebar,
+#' * text before and after authors on the authors page.
+#' 
+#' 
+#' You can modify how each author's name is displayed by adding a subsection 
+#' for `authors`. Each entry in `authors` should be named 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. Use an absolute URL to an image, not a relative link. Use an empty 
+#'   alternative text rather than no alternative text so a screen-reader would 
+#' skip over it.
+#' 
+#' ```yaml
+#' authors:
+#'   firstname lastname:
+#'     href: "http://name-website.com"
+#'     html: "<img src='https://website.com/name-picture.png' width=72 alt=''>"
+#' ```
+#' 
+#' 
+#' By default, the "developers" list shown in the sidebar and footer is 
+#' populated by the maintainer ("cre"), authors ("aut"), and funder ("fnd") 
+#' from the `DESCRIPTION`. You could choose other roles for filtering.
+#' With the configuration below:
+#' 
+#' * only the maintainer and funder(s) appear in the footer, after the text 
+#'   "Crafted by",
+#' * all authors and contributors appear in the sidebar,
+#' * the authors list on the sidebar is preceded and followed by some text,
+#' * the authors list on the authors page is preceded and followed by some text.
+#' 
+#' 
+#' ```yaml
+#' authors:
+#'   footer:
+#'     roles: [cre, fnd]
+#'     text: "Crafted by"
+#'   sidebar:
+#'     roles: [aut, ctb]
+#'     before: "So *who* does the work?"
+#'     after: "Thanks all!"
+#'   before: "This package is proudly brought to you by:"
+#'   after: "See the [changelog](news/index.html) for other contributors. :pray:"
+#' ```
+#' 
+#' If you want to filter authors based on something else than their roles, 
+#' consider using a custom sidebar/footer component 
+#' (see `?build_home`/`?build_site`, respectively).
+#' 
+#' # Sidebar
+#' 
+#' You can customise the homepage sidebar with the `home.sidebar` field.
+#' It's made up of two pieces: `structure`, which defines the overall layout, 
+#' and `components`, which defines what each piece looks like. This organisation 
+#' makes it easy to mix and match the pkgdown defaults with your own 
+#' customisations.
+#' 
+#' This is the default structure:
+#' 
+#' ``` yaml
+#' home:
+#'   sidebar:
+#'     structure: [links, license, community, citation, authors, dev]
+#' ```
+#' 
+#' These are drawn from seven built-in components:
+#' 
+#' -   `links`: automated links generated from `URL` and `BugReports` fields 
+#'     from `DESCRIPTION` plus manual links from the `home.links` field:
+#' 
+#'     ``` yaml
+#'     home:
+#'       links:
+#'       - text: Link text
+#'         href: https://website.com
+#'       - text: Roadmap
+#'         href: /roadmap.html
+#'     ```
+#' 
+#' -   `license`: Licensing information if `LICENSE`/`LICENCE` or 
+#'     `LICENSE.md`/`LICENCE.md` files are present.
+#' 
+#' -   `community`: links to to `.github/CONTRIBUTING.md`, 
+#'     `.github/CODE_OF_CONDUCT.md`, etc.
+#' 
+#' -   `citation`: link to package citation information. Uses either 
+#'     `inst/CITATION` or, if absent, information from the `DESCRIPTION`.
+#' 
+#' -   `authors`: selected authors from the `DESCRIPTION`.
+#' 
+#' -   `dev`: development status badges extracted from `README.md`/`index.md`. 
+#'     This is only shown for "development" versions of websites; see 
+#'     "Development mode" in `?build_site` for details. 
+#' 
+#' -   `toc`: a table of contents for the README (not shown by default).
+#' 
+#' You can also add your own components, where `text` is markdown text:
+#' 
+#' ``` yaml
+#' home:
+#'   sidebar:
+#'     structure: [authors, custom, toc, dev]
+#'     components:
+#'       custom:
+#'         title: Funding
+#'         text: We are *grateful* for funding!
+#' ```
+#' 
+#' Alternatively, you can provide a ready-made sidebar HTML:
+#' 
+#' ``` yaml
+#' home:
+#'   sidebar:
+#'     html: path-to-sidebar.html
+#' ```
+#' 
+#' Or completely remove it:
+#' 
+#' ``` yaml
+#' home:
+#'   sidebar: FALSE
 #' ```
-#'
 #' @inheritParams build_articles
 #' @export
 build_home <- function(pkg = ".",
@@ -31,6 +294,8 @@ build_home <- function(pkg = ".",
                        quiet = TRUE) {
 
   pkg <- section_init(pkg, depth = 0L, override = override)
+  check_bool(quiet)
+
   cli::cli_rule("Building home")
   dir_create(pkg$dst_path)
 

R/build-news.R

@@ -117,6 +117,8 @@ build_news_multi <- function(pkg = ".") {
   )
 
   render_news <- function(version, file_out, contents) {
+    # Older, major, versions first on each page
+    # https://github.com/r-lib/pkgdown/issues/2285#issuecomment-2070966518
     render_page(
       pkg,
       "news",

R/build-reference.R

@@ -158,6 +158,12 @@ build_reference <- function(pkg = ".",
                             document = "DEPRECATED",
                             topics = NULL) {
   pkg <- section_init(pkg, depth = 1L, override = override)
+  check_bool(lazy)
+  check_bool(examples)
+  check_bool(run_dont_run)
+  check_number_whole(seed, allow_null = TRUE)
+  check_bool(devel)
+  check_character(topics, allow_null = TRUE)
 
   if (document != "DEPRECATED") {
     lifecycle::deprecate_warn(

R/build-tutorials.R

@@ -29,6 +29,7 @@
 #' @export
 build_tutorials <- function(pkg = ".", override = list(), preview = NA) {
   pkg <- section_init(pkg, depth = 1L, override = override)
+
   tutorials <- pkg$tutorials
 
   if (nrow(tutorials) == 0) {